0
# Cache Expiration Management
1
2
Direct programmatic control over cache expiration with configurable age and entry limits, providing manual cache management and custom expiration workflows.
3
4
## Capabilities
5
6
### CacheExpiration Class
7
8
The primary class for programmatic cache expiration management.
9
10
```typescript { .api }
11
/**
12
* Allows you define an expiration and/or limit on the number of responses stored in a Cache
13
*/
14
class CacheExpiration {
15
/**
16
* Constructs a new CacheExpiration instance. At least one of maxEntries or maxAgeSeconds must be provided.
17
* @param cacheName - Name of the cache to apply restrictions to
18
* @param config - Configuration options for cache expiration
19
*/
20
constructor(cacheName: string, config: CacheExpirationConfig = {});
21
22
/**
23
* Expires entries for the given cache based on the configured criteria.
24
* Removes entries that exceed maxEntries (LRU) or are older than maxAgeSeconds.
25
*/
26
expireEntries(): Promise<void>;
27
28
/**
29
* Updates the timestamp for the given URL to ensure accurate LRU tracking
30
* and expiration calculations. Call this when a cached response is used.
31
* @param url - The URL to update the timestamp for
32
*/
33
updateTimestamp(url: string): Promise<void>;
34
35
/**
36
* Checks if a URL has expired based on maxAgeSeconds configuration.
37
* Performs IndexedDB lookup so can be slow.
38
* Note: This method will not remove the cached entry.
39
* @param url - The URL to check for expiration
40
* @returns true if the URL has expired, false otherwise
41
*/
42
isURLExpired(url: string): Promise<boolean>;
43
44
/**
45
* Removes the IndexedDB object store used to keep track of cache expiration metadata.
46
* Call this when you no longer need expiration tracking for this cache.
47
*/
48
delete(): Promise<void>;
49
}
50
51
interface CacheExpirationConfig {
52
/** Maximum number of entries to cache. Entries used least recently will be removed first. */
53
maxEntries?: number;
54
/** Maximum age of an entry in seconds before it's treated as stale and removed. */
55
maxAgeSeconds?: number;
56
/** CacheQueryOptions that will be used when calling delete() on the cache. */
57
matchOptions?: CacheQueryOptions;
58
}
59
```
60
61
**Usage Examples:**
62
63
```typescript
64
import { CacheExpiration } from "workbox-expiration";
65
66
// Create cache expiration with entry limit
67
const cacheExpiration = new CacheExpiration("api-responses", {
68
maxEntries: 50,
69
});
70
71
// Create cache expiration with age limit
72
const timeLimitedCache = new CacheExpiration("temp-data", {
73
maxAgeSeconds: 60 * 60, // 1 hour
74
});
75
76
// Combined limits
77
const restrictedCache = new CacheExpiration("restricted-cache", {
78
maxEntries: 100,
79
maxAgeSeconds: 60 * 60 * 24, // 24 hours
80
matchOptions: { ignoreSearch: true },
81
});
82
83
// Manual expiration
84
await cacheExpiration.expireEntries();
85
86
// Update timestamp when using a cached response
87
await cacheExpiration.updateTimestamp("https://api.example.com/data");
88
89
// Check if URL is expired before using
90
const expired = await cacheExpiration.isURLExpired("https://api.example.com/data");
91
if (!expired) {
92
// Use cached response
93
}
94
95
// Clean up when done
96
await cacheExpiration.delete();
97
```
98
99
### Error Conditions
100
101
**Constructor Errors:**
102
- Throws `WorkboxError` with code `max-entries-or-age-required` if neither `maxEntries` nor `maxAgeSeconds` is provided
103
104
**isURLExpired Errors:**
105
- Throws `WorkboxError` with code `expired-test-without-max-age` if called without `maxAgeSeconds` configured (development builds only)
106
107
### Implementation Details
108
109
- Uses IndexedDB to persist cache entry timestamps across service worker restarts
110
- Implements least-recently-used (LRU) eviction for `maxEntries` limits
111
- Supports HTTP Date header validation for lightweight freshness checks
112
- Handles concurrent expiration requests to prevent race conditions
113
- Automatically normalizes URLs by removing hash fragments