0
# Caching System
1

2
HTTP caching implementation with multiple storage backends and standards-compliant cache behavior following WHATWG CacheStorage specification.
3

4
## Capabilities
5

6
### CacheStorage
7

8
Global cache storage instance providing access to named Cache instances.
9

10
```javascript { .api }
11
/**
12
 * Global cache storage instance
13
 */
14
const caches: CacheStorage;
15

16
/**
17
 * Cache storage management system
18
 */
19
class CacheStorage {
20
  /**
21
   * Opens a named cache, creating it if it doesn't exist
22
   * @param cacheName - Name of the cache to open
23
   * @returns Promise resolving to Cache instance
24
   */
25
  open(cacheName: string): Promise<Cache>;
26
  
27
  /**
28
   * Checks if a named cache exists
29
   * @param cacheName - Name of the cache to check
30
   * @returns Promise resolving to boolean
31
   */
32
  has(cacheName: string): Promise<boolean>;
33
  
34
  /**
35
   * Deletes a named cache
36
   * @param cacheName - Name of the cache to delete
37
   * @returns Promise resolving to boolean indicating success
38
   */
39
  delete(cacheName: string): Promise<boolean>;
40
  
41
  /**
42
   * Returns an array of cache names
43
   * @returns Promise resolving to array of cache names
44
   */
45
  keys(): Promise<string[]>;
46
}
47
```
48

49
**Usage Examples:**
50

51
```javascript
52
import { caches } from 'undici';
53

54
// Open a cache
55
const cache = await caches.open('api-responses');
56

57
// Store a response
58
const response = await fetch('https://api.example.com/data');
59
await cache.put('https://api.example.com/data', response.clone());
60

61
// Retrieve cached response
62
const cachedResponse = await cache.match('https://api.example.com/data');
63
if (cachedResponse) {
64
  const data = await cachedResponse.json();
65
}
66

67
// Check if cache exists
68
const exists = await caches.has('api-responses');
69

70
// Delete cache
71
await caches.delete('api-responses');
72
```
73

74
### Cache
75

76
Individual cache instance for storing Request/Response pairs.
77

78
```javascript { .api }
79
/**
80
 * Individual cache instance
81
 */
82
class Cache {
83
  /**
84
   * Adds a request/response pair to the cache
85
   * @param request - Request to use as key
86
   * @param response - Response to cache
87
   * @returns Promise resolving when stored
88
   */
89
  put(request: RequestInfo, response: Response): Promise<void>;
90
  
91
  /**
92
   * Retrieves a cached response for the request
93
   * @param request - Request to match
94
   * @param options - Match options
95
   * @returns Promise resolving to Response or undefined
96
   */
97
  match(request: RequestInfo, options?: CacheQueryOptions): Promise<Response | undefined>;
98
  
99
  /**
100
   * Retrieves all cached responses matching the request
101
   * @param request - Request to match (optional)
102
   * @param options - Match options
103
   * @returns Promise resolving to array of Responses
104
   */
105
  matchAll(request?: RequestInfo, options?: CacheQueryOptions): Promise<Response[]>;
106
  
107
  /**
108
   * Adds a request to the cache, fetching the response
109
   * @param request - Request to fetch and cache
110
   * @returns Promise resolving when cached
111
   */
112
  add(request: RequestInfo): Promise<void>;
113
  
114
  /**
115
   * Adds multiple requests to the cache
116
   * @param requests - Array of requests to fetch and cache
117
   * @returns Promise resolving when all are cached
118
   */
119
  addAll(requests: RequestInfo[]): Promise<void>;
120
  
121
  /**
122
   * Deletes cached entries matching the request
123
   * @param request - Request to match
124
   * @param options - Match options
125
   * @returns Promise resolving to boolean indicating if entries were deleted
126
   */
127
  delete(request: RequestInfo, options?: CacheQueryOptions): Promise<boolean>;
128
  
129
  /**
130
   * Returns all cached request objects
131
   * @param request - Request to match (optional)
132
   * @param options - Match options
133
   * @returns Promise resolving to array of Requests
134
   */
135
  keys(request?: RequestInfo, options?: CacheQueryOptions): Promise<Request[]>;
136
}
137

138
interface CacheQueryOptions {
139
  ignoreSearch?: boolean;
140
  ignoreMethod?: boolean;
141
  ignoreVary?: boolean;
142
}
143
```
144

145
### Cache Storage Backends
146

147
Multiple storage backend implementations for different persistence requirements.
148

149
```javascript { .api }
150
const cacheStores: {
151
  /**
152
   * In-memory cache store implementation
153
   */
154
  MemoryCacheStore: typeof MemoryCacheStore;
155
  
156
  /**
157
   * SQLite-based persistent cache store implementation
158
   */
159
  SqliteCacheStore: typeof SqliteCacheStore;
160
};
161

162
/**
163
 * In-memory cache implementation
164
 */
165
class MemoryCacheStore {
166
  constructor(options?: MemoryCacheStoreOptions);
167
}
168

169
/**
170
 * SQLite-based persistent cache implementation
171
 */
172
class SqliteCacheStore {
173
  constructor(options?: SqliteCacheStoreOptions);
174
}
175

176
interface MemoryCacheStoreOptions {
177
  maxSize?: number;
178
  maxAge?: number;
179
}
180

181
interface SqliteCacheStoreOptions {
182
  location?: string;
183
  maxSize?: number;
184
}
185
```
186

187
**Usage Examples:**
188

189
```javascript
190
import { cacheStores } from 'undici';
191

192
// Create custom cache store
193
const memoryStore = new cacheStores.MemoryCacheStore({
194
  maxSize: 100,
195
  maxAge: 300000 // 5 minutes
196
});
197

198
const sqliteStore = new cacheStores.SqliteCacheStore({
199
  location: './cache.db',
200
  maxSize: 1000
201
});
202
```