Skip to content

Commit 357a38c

Browse files
PabloSzxPabloSzx
committed
Docs
1 parent c6decd7 commit 357a38c

File tree

1 file changed

+294
-2
lines changed

1 file changed

+294
-2
lines changed

‎README.md‎

Lines changed: 294 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,295 @@
1-
# fine-cache
1+
# Fine-Grained Cache
22

3-
Already open source on public npm : https://www.npmjs.com/package/@soundxyz/fine-grained-cache
3+
This module provides a flexible caching utility designed to work with Redis and an in-memory cache (like LRUCache). It supports features like locking for preventing thundering herd problems, stale-while-revalidate patterns, timed invalidation, and fine-grained key invalidation.
4+
5+
## FineGrainedCache Factory
6+
7+
The `FineGrainedCache` function is a factory that creates a cache instance configured with your Redis client and other options.
8+
9+
**Parameters:**
10+
11+
- `options`: An object containing configuration options for the cache.
12+
- `redis`: (`Redis`) The Redis client instance to use for caching.
13+
- `redLock`: (`{ client: RedLock; maxExpectedTime?: StringValue; retryLockTime?: StringValue; useByDefault?: boolean; }`, optional) Configuration for RedLock for distributed locking.
14+
- `client`: (`RedLock`) The RedLock client instance.
15+
- `maxExpectedTime`: (`StringValue`, optional) Maximum time to wait for the lock.
16+
- `retryLockTime`: (`StringValue`, optional) Time to wait between lock retry attempts.
17+
- `useByDefault`: (`boolean`, optional) Whether to use RedLock by default for `getCached`. Defaults to `false`.
18+
- `keyPrefix`: (`KeyPrefix`, optional) A prefix to use for all Redis keys managed by this cache instance. Defaults to `"fine-cache-v1"`.
19+
- `memoryCache`: (`MemoryCache<unknown>`, optional) An instance of an in-memory cache (e.g., LRUCache) to use as a tier 1 cache.
20+
- `onError`: (`(err: unknown) => void`, optional) A callback function to handle errors that occur within the cache operations.
21+
- `logEvents`: (`{ events: LoggedEvents; log?: (args: LogEventArgs) => void; }`, optional) Configuration for logging cache events.
22+
- `events`: (`LoggedEvents`) An object specifying which events to log.
23+
- `log`: (`(args: LogEventArgs) => void`, optional) The logging function to use. Defaults to `console.log`.
24+
- `GETRedisTimeout`: (`number`, optional) The maximum amount of milliseconds for `getCached` to wait for a GET response from Redis.
25+
- `pipelineRedisGET`: (`boolean | number`, optional) Enables the use of Redis pipelines for GET operations. If a number is specified, it's the maximum number of operations per pipeline.
26+
- `pipelineRedisSET`: (`boolean | number`, optional) Enables the use of Redis pipelines for SET operations. If a number is specified, it's the maximum number of operations per pipeline.
27+
- `defaultUseMemoryCache`: (`boolean`, optional) Should `getCached` use the memory cache by default? Can be overridden per call. Defaults to `true`.
28+
- `awaitRedisSet`: (`boolean`, optional) Should `getCached` await the Redis SET operation? Defaults to `process.env.NODE_ENV === "test"`.
29+
30+
## Main Entry Points
31+
32+
These are the primary functions for interacting with the cache.
33+
34+
### `getCached`
35+
36+
Fetches a value from the cache or generates it using the provided callback if a cache miss occurs. Supports timed invalidation, locking, and stale-while-revalidate (implicitly via `ttl` and `timedInvalidation`).
37+
38+
```typescript
39+
<T>(
40+
cb: CachedCallback<T>,
41+
options: {
42+
timedInvalidation?: Date | (() => Date | Promise<Date>);
43+
ttl: StringValue | "Infinity";
44+
keys: string | [string, ...(string | number)[]];
45+
maxExpectedTime?: StringValue;
46+
retryLockTime?: StringValue;
47+
checkShortMemoryCache?: boolean;
48+
useRedlock?: boolean;
49+
forceUpdate?: boolean;
50+
}
51+
) => Awaited<T> | Promise<Awaited<T>>;
52+
```
53+
54+
**Parameters:**
55+
56+
- `cb`: (`CachedCallback<T>`) An asynchronous function that generates the value to be cached.
57+
- `options`: An object containing options for this specific cache retrieval.
58+
- `timedInvalidation`: (`Date | (() => Date | Promise<Date>)`, optional) Specifies a future date or a function that returns a future date when the cache entry should be considered invalid, even if the `ttl` has not expired.
59+
- `ttl`: (`StringValue | "Infinity"`) The time-to-live for the cache entry in Redis. Can be a string like "1m", "1h", "1d", or "Infinity".
60+
- `keys`: (`string | [string, ...(string | number)[]]`) A string or an array of strings and numbers used to generate the cache key.
61+
- `maxExpectedTime`: (`StringValue`, optional) Overrides the default RedLock `maxExpectedTime` for this operation.
62+
- `retryLockTime`: (`StringValue`, optional) Overrides the default RedLock `retryLockTime` for this operation.
63+
- `checkShortMemoryCache`: (`boolean`, optional) Should the memory cache be checked before hitting Redis? Overrides the default.
64+
- `useRedlock`: (`boolean`, optional) Should RedLock be used for this operation to prevent thundering herd? Overrides the default.
65+
- `forceUpdate`: (`boolean`, optional) Forces the cache to regenerate the value using the callback, ignoring any existing cache entry.
66+
67+
**Returns:**
68+
69+
(`Awaited<T> | Promise<Awaited<T>>`) The cached or newly generated value.
70+
71+
### `getStaleWhileRevalidate`
72+
73+
Fetches a value using the stale-while-revalidate pattern. It immediately returns a potentially stale value from the cache while asynchronously updating it in the background.
74+
75+
```typescript
76+
<T>(
77+
cb: StaleWhileRevalidateCallback<T>,
78+
options: {
79+
revalidationTTL: StringValue;
80+
dataTTL?: StringValue | "Infinity";
81+
keys: string | [string, ...(string | number)[]];
82+
forceUpdate?: boolean;
83+
}
84+
) => Promise<Awaited<T>>;
85+
```
86+
87+
**Parameters:**
88+
89+
- `cb`: (`StaleWhileRevalidateCallback<T>`) An asynchronous function that generates the fresh value.
90+
- `options`: An object containing options for this SWR operation.
91+
- `revalidationTTL`: (`StringValue`) The duration after which the cached data is considered stale and a background revalidation is triggered.
92+
- `dataTTL`: (`StringValue | "Infinity"`, optional) The maximum time the data is allowed to live in the cache, even if not revalidated. Defaults to `Infinity`.
93+
- `keys`: (`string | [string, ...(string | number)[]]`) A string or an array of strings and numbers used to generate the cache key.
94+
- `forceUpdate`: (`boolean`, optional) Forces the cache to regenerate the value using the callback immediately, ignoring any existing cache entry.
95+
96+
**Returns:**
97+
98+
(`Promise<Awaited<T>>`) A promise that resolves with the cached (potentially stale) or newly generated value.
99+
100+
### `invalidateCache`
101+
102+
Invalidates (deletes) cache entries based on the provided keys.
103+
104+
```typescript
105+
(...keys: [string, ...(string | number)[]]) => Promise<void>;
106+
```
107+
108+
**Parameters:**
109+
110+
- `...keys`: (`[string, ...(string | number)[]]`) One or more arrays of strings and numbers representing the keys to invalidate.
111+
112+
**Returns:**
113+
114+
(`Promise<void>`) A promise that resolves when the invalidation is complete.
115+
116+
## Secondary Utility Functions
117+
118+
These functions provide lower-level access and additional flexibility for developers.
119+
120+
### `generateCacheKey`
121+
122+
Generates a standardized cache key string based on the provided keys and the factory's `keyPrefix`.
123+
124+
```typescript
125+
(keys: string | [string, ...(string | number)[]]) => string;
126+
```
127+
128+
**Parameters:**
129+
130+
- `keys`: (`string | [string, ...(string | number)[]]`) A string or an array of strings and numbers to be included in the key.
131+
132+
**Returns:**
133+
134+
(`string`) The generated cache key.
135+
136+
### `generateSWRDataKey`
137+
138+
Generates a standardized key string specifically for storing SWR data, based on the provided keys and the factory's `swrKeyPrefix`.
139+
140+
```typescript
141+
(keys: string | [string, ...(string | number)[]]) => string;
142+
```
143+
144+
**Parameters:**
145+
146+
- `keys`: (`string | [string, ...(string | number)[]]`) A string or an array of strings and numbers to be included in the key.
147+
148+
**Returns:**
149+
150+
(`string`) The generated SWR data key.
151+
152+
### `keyPrefix`
153+
154+
The key prefix configured for this cache instance.
155+
156+
```typescript
157+
KeyPrefix;
158+
```
159+
160+
**Type:** `KeyPrefix`
161+
162+
### `swrKeyPrefix`
163+
164+
The key prefix used specifically for Stale-While-Revalidate data.
165+
166+
```typescript
167+
`${KeyPrefix}-swr`;
168+
```
169+
170+
**Type:** `` `${KeyPrefix}-swr` ``
171+
172+
### `memoryCache`
173+
174+
The in-memory cache instance used by this cache utility.
175+
176+
```typescript
177+
MemoryCache<unknown>;
178+
```
179+
180+
**Type:** `MemoryCache<unknown>`
181+
182+
### `setCache`
183+
184+
Manually sets a value in the cache.
185+
186+
```typescript
187+
<T = unknown>(options: {
188+
populateMemoryCache?: boolean;
189+
ttl: StringValue | "Infinity";
190+
keys: string | [string, ...(string | number)[]];
191+
value: T;
192+
swr?: boolean;
193+
}) => Promise<void>;
194+
```
195+
196+
**Parameters:**
197+
198+
- `options`: An object containing options for setting the cache value.
199+
- `populateMemoryCache`: (`boolean`, optional) Whether to also set the value in the in-memory cache. Defaults to the factory's `defaultUseMemoryCache` setting.
200+
- `ttl`: (`StringValue | "Infinity"`) The time-to-live for the cache entry in Redis.
201+
- `keys`: (`string | [string, ...(string | number)[]]`) A string or an array of strings and numbers used to generate the cache key.
202+
- `value`: (`T`) The value to cache.
203+
- `swr`: (`boolean`, optional) If true, sets the value using the SWR key prefix.
204+
205+
**Returns:**
206+
207+
(`Promise<void>`) A promise that resolves when the value has been set in the cache.
208+
209+
### `readCache`
210+
211+
Reads a value directly from the cache without using a callback to generate it.
212+
213+
```typescript
214+
<T = unknown>(options: {
215+
keys: string | [string, ...(string | number)[]];
216+
swr?: boolean;
217+
}) =>
218+
Promise<{
219+
found: boolean;
220+
value: Awaited<T>;
221+
}>;
222+
```
223+
224+
**Parameters:**
225+
226+
- `options`: An object containing options for reading the cache value.
227+
- `keys`: (`string | [string, ...(string | number)[]]`) A string or an array of strings and numbers used to generate the cache key.
228+
- `swr`: (`boolean`, optional) If true, reads the value using the SWR key prefix.
229+
230+
**Returns:**
231+
232+
(`Promise<{ found: boolean; value: Awaited<T>; }>`) A promise that resolves with an object indicating if the key was found and the cached value.
233+
234+
### `getRedisValue`
235+
236+
Gets a raw value directly from Redis using a specific key (without applying the key prefix).
237+
238+
```typescript
239+
(key: string) => Promise<string | null>;
240+
```
241+
242+
**Parameters:**
243+
244+
- `key`: (`string`) The exact Redis key to retrieve.
245+
246+
**Returns:**
247+
248+
(`Promise<string | null>`) A promise that resolves with the value from Redis, or `null` if the key does not exist.
249+
250+
### `setRedisValue`
251+
252+
Sets a raw value directly in Redis using a specific key (without applying the key prefix).
253+
254+
```typescript
255+
({
256+
key,
257+
value,
258+
ttl,
259+
nx,
260+
}: {
261+
key: string;
262+
value: string;
263+
ttl?: number;
264+
nx?: boolean;
265+
}) => Promise<unknown>;
266+
```
267+
268+
**Parameters:**
269+
270+
- `options`: An object containing options for setting the Redis value.
271+
- `key`: (`string`) The exact Redis key to set.
272+
- `value`: (`string`) The string value to store.
273+
- `ttl`: (`number`, optional) The time-to-live for the key in seconds.
274+
- `nx`: (`boolean`, optional) If true, set the key only if it does not already exist.
275+
276+
**Returns:**
277+
278+
(`Promise<unknown>`) A promise that resolves with the result of the Redis SET command.
279+
280+
### `clearRedisValues`
281+
282+
Deletes one or more raw keys directly from Redis (without applying the key prefix).
283+
284+
```typescript
285+
({ keys }: { keys: string | string[] }) => Promise<number>;
286+
```
287+
288+
**Parameters:**
289+
290+
- `options`: An object containing the keys to clear.
291+
- `keys`: (`string | string[]`) A single string key or an array of string keys to delete.
292+
293+
**Returns:**
294+
295+
(`Promise<number>`) A promise that resolves with the number of keys that were removed.

0 commit comments

Comments
 (0)