0
# Workbox Expiration
1

2
Workbox Expiration is a service worker helper library that expires cached responses based on age or maximum number of entries. It provides two main approaches for cache expiration: programmatic cache management via the `CacheExpiration` class and seamless integration with Workbox strategies through the `ExpirationPlugin`.
3

4
## Package Information
5

6
- **Package Name**: workbox-expiration
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install workbox-expiration`
10

11
## Core Imports
12

13
```typescript
14
import { CacheExpiration, ExpirationPlugin } from "workbox-expiration";
15
import type { ExpirationPluginOptions } from "workbox-expiration";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { CacheExpiration, ExpirationPlugin } = require("workbox-expiration");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { ExpirationPlugin } from "workbox-expiration";
28
import { StaleWhileRevalidate } from "workbox-strategies";
29

30
// Using ExpirationPlugin with a Workbox strategy
31
const strategy = new StaleWhileRevalidate({
32
  cacheName: "api-cache",
33
  plugins: [
34
    new ExpirationPlugin({
35
      maxEntries: 50,
36
      maxAgeSeconds: 60 * 60 * 24, // 24 hours
37
    }),
38
  ],
39
});
40

41
// Direct cache expiration management
42
import { CacheExpiration } from "workbox-expiration";
43

44
const cacheExpiration = new CacheExpiration("my-cache", {
45
  maxEntries: 100,
46
  maxAgeSeconds: 60 * 60, // 1 hour
47
});
48

49
// Manually expire entries
50
await cacheExpiration.expireEntries();
51
```
52

53
## Architecture
54

55
Workbox Expiration is built around several key components:
56

57
- **CacheExpiration Class**: Direct programmatic interface for cache expiration management
58
- **ExpirationPlugin Class**: Workbox plugin that automatically handles expiration during cache operations
59
- **IndexedDB Integration**: Persistent timestamp storage via CacheTimestampsModel for tracking entry age and usage
60
- **Lifecycle Hooks**: Integration with Workbox plugin lifecycle for automatic expiration
61
- **Quota Management**: Optional automatic cleanup when storage quota is exceeded
62

63
## Capabilities
64

65
### Cache Expiration Management
66

67
Direct programmatic control over cache expiration with configurable age and entry limits. Ideal for manual cache management and custom expiration workflows.
68

69
```typescript { .api }
70
class CacheExpiration {
71
  constructor(cacheName: string, config: CacheExpirationConfig = {});
72
  expireEntries(): Promise<void>;
73
  updateTimestamp(url: string): Promise<void>;
74
  isURLExpired(url: string): Promise<boolean>;
75
  delete(): Promise<void>;
76
}
77

78
interface CacheExpirationConfig {
79
  maxEntries?: number;
80
  maxAgeSeconds?: number;
81
  matchOptions?: CacheQueryOptions;
82
}
83
```
84

85
[Cache Expiration Management](./cache-expiration.md)
86

87
### Plugin-Based Expiration
88

89
Workbox plugin for seamless integration with caching strategies, providing automatic expiration based on age and entry limits during cache operations.
90

91
```typescript { .api }
92
class ExpirationPlugin {
93
  constructor(config: ExpirationPluginOptions = {});
94
  deleteCacheAndMetadata(): Promise<void>;
95
}
96

97
interface ExpirationPluginOptions {
98
  maxEntries?: number;
99
  maxAgeSeconds?: number;
100
  matchOptions?: CacheQueryOptions;
101
  purgeOnQuotaError?: boolean;
102
}
103
```
104

105
[Plugin-Based Expiration](./expiration-plugin.md)