@marianmeres/kv 2.4.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/API.md CHANGED
@@ -20,10 +20,10 @@ Creates and returns a KV client configured for the specified storage backend.
20
20
 
21
21
  ```typescript
22
22
  function createKVClient<T extends keyof KnownTypes>(
23
- namespace: string = "",
24
- type: T = "memory",
25
- options: Partial<KnownTypes[T]["options"]> = {}
26
- ): KnownTypes[T]["adapter"]
23
+ namespace: string = "",
24
+ type: T = "memory",
25
+ options: Partial<KnownTypes[T]["options"]> = {},
26
+ ): KnownTypes[T]["adapter"];
27
27
  ```
28
28
 
29
29
  **Type Parameters:**
@@ -31,18 +31,17 @@ function createKVClient<T extends keyof KnownTypes>(
31
31
 
32
32
  **Parameters:**
33
33
 
34
- | Parameter | Type | Default | Description |
35
- |-----------|------|---------|-------------|
36
- | `namespace` | `string` | `""` | Key prefix applied to all operations. Must end with `:` or be empty. |
37
- | `type` | `"memory" \| "redis" \| "postgres" \| "deno-kv"` | `"memory"` | The storage backend to use. |
38
- | `options` | `Partial<AdapterOptions>` | `{}` | Adapter-specific configuration options. |
34
+ | Parameter | Type | Default | Description |
35
+ | ----------- | ----------------------------------- | ---------- | -------------------------------------------------------------------- |
36
+ | `namespace` | `string` | `""` | Key prefix applied to all operations. Must end with `:` or be empty. |
37
+ | `type` | `"memory" \| "redis" \| "postgres"` | `"memory"` | The storage backend to use. |
38
+ | `options` | `Partial<AdapterOptions>` | `{}` | Adapter-specific configuration options. |
39
39
 
40
40
  **Returns:** A configured adapter instance. Call `initialize()` before use.
41
41
 
42
42
  **Throws:**
43
43
  - `TypeError` - If namespace doesn't end with `:` (and is not empty)
44
44
  - `TypeError` - If an unsupported adapter type is specified
45
- - `Error` - If `"deno-kv"` is used outside the Deno runtime
46
45
  - `Error` - If required options (like `db`) are missing for the adapter
47
46
 
48
47
  **Example:**
@@ -65,11 +64,6 @@ import pg from "pg";
65
64
  const pool = new pg.Pool({ connectionString: "..." });
66
65
  const postgres = createKVClient("myapp:", "postgres", { db: pool });
67
66
  await postgres.initialize();
68
-
69
- // Deno KV (Deno runtime only)
70
- const kv = await Deno.openKv();
71
- const denoKv = createKVClient("myapp:", "deno-kv", { db: kv });
72
- await denoKv.initialize();
73
67
  ```
74
68
 
75
69
  ---
@@ -104,9 +98,9 @@ destroy(hard?: boolean): Promise<void>
104
98
 
105
99
  **Parameters:**
106
100
 
107
- | Parameter | Type | Default | Description |
108
- |-----------|------|---------|-------------|
109
- | `hard` | `boolean` | `false` | If `true`, performs a hard cleanup (e.g., drops tables in PostgreSQL). |
101
+ | Parameter | Type | Default | Description |
102
+ | --------- | --------- | ------- | ---------------------------------------------------------------------- |
103
+ | `hard` | `boolean` | `false` | If `true`, performs a hard cleanup (e.g., drops tables in PostgreSQL). |
110
104
 
111
105
  ---
112
106
 
@@ -122,7 +116,7 @@ info(): AdapterInfo
122
116
 
123
117
  ```typescript
124
118
  const info = client.info();
125
- console.log(info.type); // "redis", "postgres", "memory", or "deno-kv"
119
+ console.log(info.type); // "redis", "postgres", or "memory"
126
120
  ```
127
121
 
128
122
  ---
@@ -141,11 +135,11 @@ Values are automatically serialized to JSON. If the key already exists, it will
141
135
 
142
136
  **Parameters:**
143
137
 
144
- | Parameter | Type | Description |
145
- |-----------|------|-------------|
146
- | `key` | `string` | The key to store the value under. |
147
- | `value` | `any` | The value to store. Can be any JSON-serializable value. `undefined` is stored as `null`. |
148
- | `options` | `Partial<SetOptions>` | Optional settings including TTL. |
138
+ | Parameter | Type | Description |
139
+ | --------- | --------------------- | ---------------------------------------------------------------------------------------- |
140
+ | `key` | `string` | The key to store the value under. |
141
+ | `value` | `any` | The value to store. Can be any JSON-serializable value. `undefined` is stored as `null`. |
142
+ | `options` | `Partial<SetOptions>` | Optional settings including TTL. |
149
143
 
150
144
  **Returns:** `Promise<boolean>` - `true` if the operation was successful.
151
145
 
@@ -179,7 +173,7 @@ setIfAbsent(key: string, value: any, options?: Partial<SetOptions>): Promise<boo
179
173
 
180
174
  ```typescript
181
175
  if (await client.setIfAbsent("lock:job:42", { by: "worker-1" }, { ttl: 30 })) {
182
- // we got the lock
176
+ // we got the lock
183
177
  }
184
178
  ```
185
179
 
@@ -210,22 +204,22 @@ decr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>
210
204
 
211
205
  **Parameters:**
212
206
 
213
- | Parameter | Type | Default | Description |
214
- |---|---|---|---|
215
- | `key` | `string` | — | The key to increment |
216
- | `by` | `number` | `1` | Amount to add (or subtract for `decr`) |
217
- | `options` | `Partial<SetOptions>` | — | TTL only applies on key creation — existing keys keep their TTL |
207
+ | Parameter | Type | Default | Description |
208
+ | --------- | --------------------- | ------- | --------------------------------------------------------------- |
209
+ | `key` | `string` | — | The key to increment |
210
+ | `by` | `number` | `1` | Amount to add (or subtract for `decr`) |
211
+ | `options` | `Partial<SetOptions>` | — | TTL only applies on key creation — existing keys keep their TTL |
218
212
 
219
213
  **Returns:** the new value after the operation.
220
214
 
221
- **Errors:** throws `TypeError("KV value is not a number")` when the stored value is not a JSON number. On Deno KV under heavy contention, may throw `KvRaceError` after `atomicRetryAttempts` (default 20) failed CAS attempts.
215
+ **Errors:** throws `TypeError("KV value is not a number")` when the stored value is not a JSON number.
222
216
 
223
217
  **Example:**
224
218
 
225
219
  ```typescript
226
- await client.incr("views"); // creates "views" = 1
227
- await client.incr("views", 10); // now 11
228
- await client.decr("views", 3); // now 8
220
+ await client.incr("views"); // creates "views" = 1
221
+ await client.incr("views", 10); // now 11
222
+ await client.decr("views", 3); // now 8
229
223
 
230
224
  // Sliding window: TTL only applied on first hit
231
225
  await client.incr("rate:user:1", 1, { ttl: 60 });
@@ -245,14 +239,16 @@ cas(key: string, expected: any, next: any, options?: Partial<SetOptions>): Promi
245
239
 
246
240
  > Missing keys never match, even when `expected` is `null`.
247
241
 
248
- When `options.ttl` is supplied, the stored expiration is updated on success. When it is omitted, the existing TTL is preserved (Deno KV: best-effort — see the Deno KV section).
242
+ When `options.ttl` is supplied, the stored expiration is updated on success. When it is omitted, the existing TTL is preserved.
249
243
 
250
244
  **Example** (optimistic update):
251
245
 
252
246
  ```typescript
253
247
  const current = await client.get("counter");
254
248
  const swapped = await client.cas("counter", current, current + 1);
255
- if (!swapped) { /* retry or reconcile */ }
249
+ if (!swapped) {
250
+ /* retry or reconcile */
251
+ }
256
252
  ```
257
253
 
258
254
  ---
@@ -267,9 +263,9 @@ get(key: string): Promise<any>
267
263
 
268
264
  **Parameters:**
269
265
 
270
- | Parameter | Type | Description |
271
- |-----------|------|-------------|
272
- | `key` | `string` | The key to retrieve. |
266
+ | Parameter | Type | Description |
267
+ | --------- | -------- | -------------------- |
268
+ | `key` | `string` | The key to retrieve. |
273
269
 
274
270
  **Returns:** `Promise<any>` - The stored value, or `null` if the key doesn't exist or has expired.
275
271
 
@@ -278,7 +274,7 @@ get(key: string): Promise<any>
278
274
  ```typescript
279
275
  const user = await client.get("user:123");
280
276
  if (user) {
281
- console.log(user.name);
277
+ console.log(user.name);
282
278
  }
283
279
  ```
284
280
 
@@ -294,14 +290,12 @@ delete(key: string): Promise<boolean>
294
290
 
295
291
  **Parameters:**
296
292
 
297
- | Parameter | Type | Description |
298
- |-----------|------|-------------|
299
- | `key` | `string` | The key to delete. |
293
+ | Parameter | Type | Description |
294
+ | --------- | -------- | ------------------ |
295
+ | `key` | `string` | The key to delete. |
300
296
 
301
297
  **Returns:** `Promise<boolean>` - `true` if the key existed and was deleted, `false` if it didn't exist.
302
298
 
303
- > **Note:** Deno KV always returns `true`, even for non-existent keys.
304
-
305
299
  ---
306
300
 
307
301
  #### `exists(key)`
@@ -314,9 +308,9 @@ exists(key: string): Promise<boolean>
314
308
 
315
309
  **Parameters:**
316
310
 
317
- | Parameter | Type | Description |
318
- |-----------|------|-------------|
319
- | `key` | `string` | The key to check. |
311
+ | Parameter | Type | Description |
312
+ | --------- | -------- | ----------------- |
313
+ | `key` | `string` | The key to check. |
320
314
 
321
315
  **Returns:** `Promise<boolean>` - `true` if the key exists and hasn't expired.
322
316
 
@@ -334,15 +328,13 @@ expire(key: string, ttl: number): Promise<boolean>
334
328
 
335
329
  **Parameters:**
336
330
 
337
- | Parameter | Type | Description |
338
- |-----------|------|-------------|
339
- | `key` | `string` | The key to set expiration on. |
340
- | `ttl` | `number` | Time-to-live in seconds from now. |
331
+ | Parameter | Type | Description |
332
+ | --------- | -------- | --------------------------------- |
333
+ | `key` | `string` | The key to set expiration on. |
334
+ | `ttl` | `number` | Time-to-live in seconds from now. |
341
335
 
342
336
  **Returns:** `Promise<boolean>` - `true` if the expiration was set, `false` if the key doesn't exist.
343
337
 
344
- > **Note:** Not supported in Deno KV (always returns `false`).
345
-
346
338
  **Example:**
347
339
 
348
340
  ```typescript
@@ -367,25 +359,29 @@ type TtlResult =
367
359
 
368
360
  **Parameters:**
369
361
 
370
- | Parameter | Type | Description |
371
- |-----------|------|-------------|
372
- | `key` | `string` | The key to check. |
362
+ | Parameter | Type | Description |
363
+ | --------- | -------- | ----------------- |
364
+ | `key` | `string` | The key to check. |
373
365
 
374
366
  **Returns:** A `TtlResult`. Switch on `.state`:
375
367
  - `"missing"` — key doesn't exist (or has expired)
376
368
  - `"no-ttl"` — key exists with no expiration
377
369
  - `"expires"` — key exists and will expire at `.at`
378
370
 
379
- > **Note:** Deno KV cannot query TTL — existing keys always return `{ state: "no-ttl" }`; absent keys return `{ state: "missing" }`.
380
-
381
371
  **Example:**
382
372
 
383
373
  ```typescript
384
374
  const t = await client.ttl("session:abc");
385
375
  switch (t.state) {
386
- case "expires": console.log(`Expires at ${t.at.toISOString()}`); break;
387
- case "no-ttl": console.log("No expiration set"); break;
388
- case "missing": console.log("Key does not exist"); break;
376
+ case "expires":
377
+ console.log(`Expires at ${t.at.toISOString()}`);
378
+ break;
379
+ case "no-ttl":
380
+ console.log("No expiration set");
381
+ break;
382
+ case "missing":
383
+ console.log("Key does not exist");
384
+ break;
389
385
  }
390
386
  ```
391
387
 
@@ -424,8 +420,8 @@ Uses Redis-style wildcard patterns:
424
420
 
425
421
  **Parameters:**
426
422
 
427
- | Parameter | Type | Description |
428
- |-----------|------|-------------|
423
+ | Parameter | Type | Description |
424
+ | --------- | -------- | ---------------------------------------------------------------------- |
429
425
  | `pattern` | `string` | The pattern to match keys against (e.g., `"user:*"`, `"session:???"`). |
430
426
 
431
427
  **Returns:** `Promise<string[]>` - Array of matching keys (without namespace prefix), sorted alphabetically.
@@ -457,14 +453,13 @@ Ordering is not guaranteed across adapters — use `keys()` if you need sorted o
457
453
  **Per-adapter behavior:**
458
454
  - Redis: wraps `SCAN` (non-blocking).
459
455
  - PostgreSQL: uses a server-side cursor (`DECLARE CURSOR`) inside a short transaction. Early break releases the cursor and commits.
460
- - Deno KV: direct `db.list()` pass-through.
461
456
  - Memory: yields from the internal `Map`.
462
457
 
463
458
  **Example:**
464
459
 
465
460
  ```typescript
466
461
  for await (const k of client.keysIter("user:*")) {
467
- if (someCondition(k)) break; // safe — cursor is released
462
+ if (someCondition(k)) break; // safe — cursor is released
468
463
  }
469
464
  ```
470
465
 
@@ -482,8 +477,8 @@ Uses the same pattern syntax as `keys()`.
482
477
 
483
478
  **Parameters:**
484
479
 
485
- | Parameter | Type | Description |
486
- |-----------|------|-------------|
480
+ | Parameter | Type | Description |
481
+ | --------- | -------- | ---------------------------------- |
487
482
  | `pattern` | `string` | The pattern to match keys against. |
488
483
 
489
484
  **Returns:** `Promise<number>` - The number of keys deleted.
@@ -514,14 +509,14 @@ setMultiple(
514
509
 
515
510
  Accepts either the legacy tuple shape or an object shape that allows a **per-pair `ttl`** overriding `options.ttl`.
516
511
 
517
- More efficient than multiple individual `set` calls, especially for Redis, PostgreSQL, and Deno KV (the latter commits atomically).
512
+ More efficient than multiple individual `set` calls, especially for Redis and PostgreSQL.
518
513
 
519
514
  **Parameters:**
520
515
 
521
- | Parameter | Type | Description |
522
- |-----------|------|-------------|
523
- | `entries` | `[string, any][]` or `{ key, value, ttl? }[]` | Pairs to store. |
524
- | `options` | `Partial<SetOptions>` | Fallback TTL used when a pair has no explicit `ttl`. |
516
+ | Parameter | Type | Description |
517
+ | --------- | --------------------------------------------- | ---------------------------------------------------- |
518
+ | `entries` | `[string, any][]` or `{ key, value, ttl? }[]` | Pairs to store. |
519
+ | `options` | `Partial<SetOptions>` | Fallback TTL used when a pair has no explicit `ttl`. |
525
520
 
526
521
  **Returns:** `Promise<boolean[]>` — one per entry.
527
522
 
@@ -529,11 +524,11 @@ More efficient than multiple individual `set` calls, especially for Redis, Postg
529
524
 
530
525
  ```typescript
531
526
  await client.setMultiple(
532
- [
533
- ["user:1", { name: "Alice" }], // uses options.ttl
534
- { key: "user:2", value: { name: "Bob" }, ttl: 60 }, // overrides to 60s
535
- ],
536
- { ttl: 3600 }
527
+ [
528
+ ["user:1", { name: "Alice" }], // uses options.ttl
529
+ { key: "user:2", value: { name: "Bob" }, ttl: 60 }, // overrides to 60s
530
+ ],
531
+ { ttl: 3600 },
537
532
  );
538
533
  ```
539
534
 
@@ -551,9 +546,9 @@ More efficient than multiple individual `get` calls.
551
546
 
552
547
  **Parameters:**
553
548
 
554
- | Parameter | Type | Description |
555
- |-----------|------|-------------|
556
- | `keys` | `string[]` | Array of keys to retrieve. |
549
+ | Parameter | Type | Description |
550
+ | --------- | ---------- | -------------------------- |
551
+ | `keys` | `string[]` | Array of keys to retrieve. |
557
552
 
558
553
  **Returns:** `Promise<Record<string, any>>` - Object mapping keys to their values. Only **missing** or expired keys are reported as `null`; stored falsy values (`false`, `0`, `""`, `null`) are returned verbatim.
559
554
 
@@ -581,19 +576,18 @@ transaction(operations: Operation[]): Promise<any[]>
581
576
 
582
577
  Atomicity per adapter:
583
578
 
584
- | Adapter | Atomic | Notes |
585
- |---------|:-:|---|
586
- | Memory | ✓ | Single-threaded by nature |
587
- | Redis | ✓ | Uses `MULTI`/`EXEC` |
588
- | PostgreSQL | ✓ | Pins a single connection for `BEGIN`/…/`COMMIT`, even on a `pg.Pool` |
589
- | Deno KV | Conditional | Atomic via `Deno.Kv.atomic()` when the transaction contains **no** `get` ops; falls back to sequential (non-atomic) when a `get` is present (Deno.Kv has no atomic-read) |
579
+ | Adapter | Atomic | Notes |
580
+ | ---------- | :----: | -------------------------------------------------------------------- |
581
+ | Memory | ✓ | Single-threaded by nature |
582
+ | Redis | ✓ | Uses `MULTI`/`EXEC` |
583
+ | PostgreSQL | ✓ | Pins a single connection for `BEGIN`/…/`COMMIT`, even on a `pg.Pool` |
590
584
 
591
- Per-operation `options.ttl` is honored by **all** adapters (Redis, PostgreSQL, Memory, Deno KV).
585
+ Per-operation `options.ttl` is honored by **all** adapters (Redis, PostgreSQL, Memory).
592
586
 
593
587
  **Parameters:**
594
588
 
595
- | Parameter | Type | Description |
596
- |-----------|------|-------------|
589
+ | Parameter | Type | Description |
590
+ | ------------ | ------------- | ------------------------------- |
597
591
  | `operations` | `Operation[]` | Array of operations to execute. |
598
592
 
599
593
  **Returns:** `Promise<any[]>` - Array of results for each operation.
@@ -602,9 +596,9 @@ Per-operation `options.ttl` is honored by **all** adapters (Redis, PostgreSQL, M
602
596
 
603
597
  ```typescript
604
598
  const results = await client.transaction([
605
- { type: "set", key: "counter", value: 1, options: { ttl: 60 } },
606
- { type: "get", key: "counter" },
607
- { type: "delete", key: "old:key" },
599
+ { type: "set", key: "counter", value: 1, options: { ttl: 60 } },
600
+ { type: "get", key: "counter" },
601
+ { type: "delete", key: "old:key" },
608
602
  ]);
609
603
  // [true, 1, true]
610
604
  ```
@@ -619,8 +613,8 @@ Options for the `set` operation.
619
613
 
620
614
  ```typescript
621
615
  interface SetOptions {
622
- /** Time-to-live in seconds. After this time, the key will expire. */
623
- ttl: number;
616
+ /** Time-to-live in seconds. After this time, the key will expire. */
617
+ ttl: number;
624
618
  }
625
619
  ```
626
620
 
@@ -632,8 +626,8 @@ Information about the adapter instance.
632
626
 
633
627
  ```typescript
634
628
  interface AdapterInfo {
635
- /** The adapter type identifier. */
636
- type: string; // "redis" | "postgres" | "memory" | "deno-kv"
629
+ /** The adapter type identifier. */
630
+ type: string; // "redis" | "postgres" | "memory"
637
631
  }
638
632
  ```
639
633
 
@@ -645,18 +639,18 @@ Base options shared by all adapter implementations.
645
639
 
646
640
  ```typescript
647
641
  interface AdapterAbstractOptions {
648
- /** Default TTL in seconds applied to all set operations when not explicitly specified. Set to 0 to disable. */
649
- defaultTtl: number;
650
- /** Optional logger instance for debugging and error logging. */
651
- logger?: Logger;
652
- /**
653
- * When true (default), keys are validated on every operation:
654
- * - non-empty string
655
- * - no `\0` characters
656
- * - total `namespace + key` length ≤ 512
657
- * Set to false to opt out.
658
- */
659
- validateKeys?: boolean;
642
+ /** Default TTL in seconds applied to all set operations when not explicitly specified. Set to 0 to disable. */
643
+ defaultTtl: number;
644
+ /** Optional logger instance for debugging and error logging. */
645
+ logger?: Logger;
646
+ /**
647
+ * When true (default), keys are validated on every operation:
648
+ * - non-empty string
649
+ * - no `\0` characters
650
+ * - total `namespace + key` length ≤ 512
651
+ * Set to false to opt out.
652
+ */
653
+ validateKeys?: boolean;
660
654
  }
661
655
  ```
662
656
 
@@ -666,9 +660,9 @@ interface AdapterAbstractOptions {
666
660
 
667
661
  ```typescript
668
662
  type TtlResult =
669
- | { state: "missing" }
670
- | { state: "no-ttl" }
671
- | { state: "expires"; at: Date };
663
+ | { state: "missing" }
664
+ | { state: "no-ttl" }
665
+ | { state: "expires"; at: Date };
672
666
  ```
673
667
 
674
668
  Return shape of `ttl(key)`. See the `ttl()` method above.
@@ -678,39 +672,27 @@ Return shape of `ttl(key)`. See the `ttl()` method above.
678
672
  ### `SetMultipleEntry`
679
673
 
680
674
  ```typescript
681
- type SetMultipleEntry =
682
- | [string, any]
683
- | { key: string; value: any; ttl?: number };
675
+ type SetMultipleEntry = [string, any] | { key: string; value: any; ttl?: number };
684
676
  ```
685
677
 
686
678
  Input shape accepted by `setMultiple()`.
687
679
 
688
680
  ---
689
681
 
690
- ### `KvRaceError`
691
-
692
- ```typescript
693
- class KvRaceError extends Error { /* ... */ }
694
- ```
695
-
696
- Thrown by Deno KV-backed CAS primitives (`incr`, `decr`, `getSet`, `cas`) when the retry budget is exhausted due to contention. Configurable via the adapter's `atomicRetryAttempts` option.
697
-
698
- ---
699
-
700
682
  ### `Operation`
701
683
 
702
684
  Represents a single operation within a transaction.
703
685
 
704
686
  ```typescript
705
687
  interface Operation {
706
- /** The type of operation to perform. */
707
- type: "set" | "get" | "delete";
708
- /** The key to operate on. */
709
- key: string;
710
- /** The value to set (only used for "set" operations). */
711
- value?: any;
712
- /** Optional settings for the operation (only used for "set" operations). */
713
- options?: Partial<SetOptions>;
688
+ /** The type of operation to perform. */
689
+ type: "set" | "get" | "delete";
690
+ /** The key to operate on. */
691
+ key: string;
692
+ /** The value to set (only used for "set" operations). */
693
+ value?: any;
694
+ /** Optional settings for the operation (only used for "set" operations). */
695
+ options?: Partial<SetOptions>;
714
696
  }
715
697
  ```
716
698
 
@@ -722,12 +704,12 @@ interface Operation {
722
704
 
723
705
  ```typescript
724
706
  interface AdapterMemoryOptions extends AdapterAbstractOptions {
725
- /**
726
- * Interval in seconds for automatic cleanup of expired keys.
727
- * Set to 0 to disable automatic cleanup (expired keys will still be
728
- * lazily removed on access).
729
- */
730
- ttlCleanupIntervalSec: number;
707
+ /**
708
+ * Interval in seconds for automatic cleanup of expired keys.
709
+ * Set to 0 to disable automatic cleanup (expired keys will still be
710
+ * lazily removed on access).
711
+ */
712
+ ttlCleanupIntervalSec: number;
731
713
  }
732
714
  ```
733
715
 
@@ -737,16 +719,16 @@ interface AdapterMemoryOptions extends AdapterAbstractOptions {
737
719
 
738
720
  ```typescript
739
721
  interface AdapterRedisOptions extends AdapterAbstractOptions {
740
- /**
741
- * Redis client instance created via `createClient()` or `createClientPool()`.
742
- * Pool support is experimental and not fully tested.
743
- */
744
- db: ReturnType<typeof createClient> | ReturnType<typeof createClientPool>;
745
- /**
746
- * Set to `true` if connecting to a Redis Cluster.
747
- * Note: `keys()` and `clear()` operations are not supported in cluster mode.
748
- */
749
- isCluster: boolean;
722
+ /**
723
+ * Redis client instance created via `createClient()` or `createClientPool()`.
724
+ * Pool support is experimental and not fully tested.
725
+ */
726
+ db: ReturnType<typeof createClient> | ReturnType<typeof createClientPool>;
727
+ /**
728
+ * Set to `true` if connecting to a Redis Cluster.
729
+ * Note: `keys()` and `clear()` operations are not supported in cluster mode.
730
+ */
731
+ isCluster: boolean;
750
732
  }
751
733
  ```
752
734
 
@@ -764,22 +746,22 @@ interface AdapterRedisOptions extends AdapterAbstractOptions {
764
746
 
765
747
  ```typescript
766
748
  interface AdapterPostgresOptions extends AdapterAbstractOptions {
767
- /** PostgreSQL connection instance - either `pg.Pool` or `pg.Client`. */
768
- db: pg.Pool | pg.Client;
769
- /**
770
- * Name of the table to use for storing key-value pairs.
771
- * The table will be created automatically if it doesn't exist.
772
- * May be prefixed with a schema, e.g. "public.kv".
773
- * Must match `^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$`
774
- * (word characters, optionally with one `schema.` prefix).
775
- * @default "__kv"
776
- */
777
- tableName: string;
778
- /**
779
- * Interval in seconds for automatic cleanup of expired keys.
780
- * Set to 0 to disable automatic cleanup.
781
- */
782
- ttlCleanupIntervalSec: number;
749
+ /** PostgreSQL connection instance - either `pg.Pool` or `pg.Client`. */
750
+ db: pg.Pool | pg.Client;
751
+ /**
752
+ * Name of the table to use for storing key-value pairs.
753
+ * The table will be created automatically if it doesn't exist.
754
+ * May be prefixed with a schema, e.g. "public.kv".
755
+ * Must match `^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$`
756
+ * (word characters, optionally with one `schema.` prefix).
757
+ * @default "__kv"
758
+ */
759
+ tableName: string;
760
+ /**
761
+ * Interval in seconds for automatic cleanup of expired keys.
762
+ * Set to 0 to disable automatic cleanup.
763
+ */
764
+ ttlCleanupIntervalSec: number;
783
765
  }
784
766
  ```
785
767
 
@@ -795,43 +777,6 @@ interface AdapterPostgresOptions extends AdapterAbstractOptions {
795
777
 
796
778
  ---
797
779
 
798
- ### `AdapterDenoKvOptions`
799
-
800
- ```typescript
801
- interface AdapterDenoKvOptions extends AdapterAbstractOptions {
802
- /**
803
- * Deno.Kv instance obtained via `Deno.openKv()`.
804
- */
805
- db: Deno.Kv;
806
-
807
- /**
808
- * When true, `delete()` pre-checks the key's existence and returns the
809
- * real "did it exist?" flag — at the cost of one extra round-trip.
810
- * Default false preserves the Deno.Kv native always-true behavior.
811
- */
812
- strictDeleteResult?: boolean;
813
-
814
- /**
815
- * Max retry attempts for CAS-based primitives (incr/decr/getSet/cas)
816
- * before throwing KvRaceError. Each retry adds exponential-with-jitter
817
- * backoff capped at 50ms.
818
- * @default 20
819
- */
820
- atomicRetryAttempts?: number;
821
- }
822
- ```
823
-
824
- **Limitations:**
825
- - Only works in Deno runtime
826
- - `delete()` always returns `true` by default (Deno.Kv limitation) — opt-in to strict behavior via `strictDeleteResult: true`
827
- - `expire()` is not supported (always returns `false`)
828
- - `ttl()` returns `{ state: "no-ttl" }` for any existing key and `{ state: "missing" }` for absent ones — Deno.Kv cannot report the actual expiration
829
- - TTL can be set during `set()` but cannot be queried afterward
830
- - `transaction()` is atomic (via `Deno.Kv.atomic()`) **only** when the transaction contains no `get` operations — a mixed transaction falls back to sequential, non-atomic execution
831
- - `cas()` without `options.ttl` is best-effort TTL-preserving: Deno.Kv cannot read the current expiration, so any existing `expireIn` is cleared when the swap succeeds. Supply `options.ttl` explicitly if the key should remain bounded.
832
-
833
- ---
834
-
835
780
  ## Utility Functions
836
781
 
837
782
  ### `sleep(timeout, __timeout_ref__?)`
@@ -839,17 +784,14 @@ interface AdapterDenoKvOptions extends AdapterAbstractOptions {
839
784
  Delays execution for the specified number of milliseconds.
840
785
 
841
786
  ```typescript
842
- function sleep(
843
- timeout: number,
844
- __timeout_ref__?: { id: number }
845
- ): Promise<void>
787
+ function sleep(timeout: number, __timeout_ref__?: { id: number }): Promise<void>;
846
788
  ```
847
789
 
848
790
  **Parameters:**
849
791
 
850
- | Parameter | Type | Default | Description |
851
- |-----------|------|---------|-------------|
852
- | `timeout` | `number` | - | The delay in milliseconds. |
792
+ | Parameter | Type | Default | Description |
793
+ | ----------------- | ---------------- | ------------ | ---------------------------------------------------------------- |
794
+ | `timeout` | `number` | - | The delay in milliseconds. |
853
795
  | `__timeout_ref__` | `{ id: number }` | `{ id: -1 }` | Optional reference object to capture the timeout ID for cleanup. |
854
796
 
855
797
  **Example:**