You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A simple in-memory cache with automatic or manual cache invalidation and elegant syntax written in Typescript.
7
+
A simple in-memory cache with support of different cache policies and elegant syntax written in Typescript.
8
8
9
-
- Elegant syntax: Wrap existing API calls in the `cacheable` method, assign a cache key and optionally a maxAge to save some of those precious API calls.
10
-
- Written in Typescript.
11
-
- Integrated Logs: Check on the timing of your API calls.
9
+
- Elegant syntax: **Wrap existing API calls** to save some of those precious API calls.
10
+
-**Fully typed results**. No type casting required.
11
+
- Supports different **cache policies**.
12
+
- Written in **Typescript**.
13
+
-**Integrated Logs**: Check on the timing of your API calls.
// Fetch some fresh weather data and store it in our cache.
52
83
const weatherData =awaitgetWeatherData()
53
84
54
-
// 3 seconds later
55
-
awaitwait (3e3)
85
+
/** 3 seconds later **/
56
86
57
-
// In this case the cached weather data is returned as the
58
-
// maxAge of 5 seconds probably did not yet expire.
59
-
// Please be aware that the timestamp that maxAge is checked
60
-
// against is set **before** the resource is fetched.
87
+
// The cached weather data is returned as the
88
+
// maxAge of 5 seconds did not yet expire.
61
89
const cachedWeatherData =awaitgetWeatherData()
62
90
63
-
// Another 3 seconds later
64
-
awaitwait (3e3)
91
+
/** Another 3 seconds later **/
65
92
66
-
// Now that the maxAge of cacheable `weather` is
67
-
//expired, the resource will be refetched and stored in our cache.
93
+
// Now that the maxAge is expired, the resource
94
+
// will be fetched and stored in our cache.
68
95
const freshWeatherData =awaitgetWeatherData()
69
96
```
70
97
71
98
`cacheable` serves both as the getter and setter. This method will return a cached resource if available or use the provided argument `resource` to fill the cache and return a value.
72
99
73
-
> Be aware that there is no exclusive getter as the Promise provided by the first argument to `cacheable` is used to infer the return type of the cached resource.
100
+
> Be aware that there is no exclusive cache getter (like `cache.get('key)`). This is by design as the Promise provided by the first argument to `cacheable` is used to infer the return type of the cached resource.
- If a resource exists in the cache (determined by the presence of a value with key `key`) `cacheable`returns the cached resource.
106
-
- If there's no resource in the cache, the provided argument `resource` will be used to store a value with key `key` and the value is returned.
132
+
- If a resource exists in the cache (determined by the presence of a value with key `key`) `cacheable`decides on returning a cache based on the provided cache policy.
133
+
- If there's no resource in the cache, the provided `resource` will be called and used to store a cache value with key `key` and the value is returned.
107
134
108
135
#### Arguments
109
136
110
137
##### - `resource: () => Promise<T>`
111
138
112
-
A function that returns a `Promise<T>`.
139
+
A function that returns a `Promise<T>`.
113
140
114
141
##### - `key: string`
115
142
116
-
A key to store the cache at.
143
+
A key to store the cache at.
144
+
See [Cacheables.key()](#cacheableskeyargs-string--number-string) for a safe and easy way to generate unique keys.
145
+
146
+
##### - `options?: CacheableOptions` (optional)
117
147
118
-
##### - `maxAge?: number` (optional)
148
+
An object defining the cache policy and possibly other options in the future.
149
+
The default cache policy is `cache-only`.
150
+
See [Cache Policies](#cache-policies).
119
151
120
-
A maxAge in milliseconds after which the cache will be treated as invalid.
152
+
```ts
153
+
typeCacheableOptions= {
154
+
cachePolicy:'cache-only'|'network-only-non-concurrent'|'network-only'|'max-age'|'stale-while-revalidate'// See cache policies for details
155
+
maxAge?:number// Required if cache policy is `max-age`
|`cache-only` (default) | All requests should return a value from the cache. |
228
+
|`network-only`| All requests should be handled by the network.<br>Simultaneous requests trigger simultaneous network requests. |
229
+
|`network-only-non-concurrent`| All requests should be handled by the network but no concurrent network requests are allowed.<br>All requests made in the timeframe of a network request are resolved once that is finished. |
230
+
|`max-age`| All requests should be checked against max-age.<br>If max-age is expired, a network request is triggered.<br>All requests made in the timeframe of a network request are resolved once that is finished. |
231
+
|`stale-while-revalidate`| All requests immediately return a cached value.<br>If no network request is running, a network request is triggered, 'silently' updating the cache in the background.<br>After the network request finished, subsequent requests will receive the updated cached value. |
232
+
233
+
### Cache Only (default)
234
+
235
+
The default and simplest cache policy. If there is a cache, return it.
236
+
If there is no cache yet, all calls will be resolved by the first network request (i.e. non-concurrent).
A version of `network-only` but only one network request is running at any point in time.
256
+
All requests should be handled by the network but no concurrent network requests are allowed. All requests made in the timeframe of a network request are resolved once that is finished.
The cache policy `max-age` defines after what time a cached value is treated as invalid.
266
+
All requests should be checked against max-age. If max-age is expired, a network request is triggered. All requests made in the timeframe of a network request are resolved once that is finished.
267
+
268
+
##### Example
269
+
```ts
270
+
// Trigger a network request if the cached value is older than 1 second.
271
+
cache.cacheable(() =>fetch(url), 'a', {
272
+
cachePolicy: 'max-age',
273
+
maxAge: 1000
274
+
})
275
+
```
276
+
277
+
### Stale While Revalidate
278
+
279
+
The cache policy `stale-while-revalidate` will return a cached value immediately and – if there is no network request already running – trigger a network request to 'silently' update the cache in the background.
280
+
281
+
##### Example
282
+
```ts
283
+
// If there is a cache, return it but 'silently' update the cache.
0 commit comments