@marianmeres/kv 2.4.0 → 3.1.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" \| "sqlite"` | `"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:**
@@ -66,10 +65,10 @@ const pool = new pg.Pool({ connectionString: "..." });
66
65
  const postgres = createKVClient("myapp:", "postgres", { db: pool });
67
66
  await postgres.initialize();
68
67
 
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();
68
+ // SQLite storage (node:sqlite ships with Node)
69
+ import { DatabaseSync } from "node:sqlite";
70
+ const sqlite = createKVClient("myapp:", "sqlite", { db: new DatabaseSync("kv.db") });
71
+ await sqlite.initialize();
73
72
  ```
74
73
 
75
74
  ---
@@ -104,9 +103,9 @@ destroy(hard?: boolean): Promise<void>
104
103
 
105
104
  **Parameters:**
106
105
 
107
- | Parameter | Type | Default | Description |
108
- |-----------|------|---------|-------------|
109
- | `hard` | `boolean` | `false` | If `true`, performs a hard cleanup (e.g., drops tables in PostgreSQL). |
106
+ | Parameter | Type | Default | Description |
107
+ | --------- | --------- | ------- | --------------------------------------------------------------------------------- |
108
+ | `hard` | `boolean` | `false` | If `true`, performs a hard cleanup (e.g., drops tables in PostgreSQL and SQLite). |
110
109
 
111
110
  ---
112
111
 
@@ -122,7 +121,7 @@ info(): AdapterInfo
122
121
 
123
122
  ```typescript
124
123
  const info = client.info();
125
- console.log(info.type); // "redis", "postgres", "memory", or "deno-kv"
124
+ console.log(info.type); // "redis", "postgres", "sqlite", or "memory"
126
125
  ```
127
126
 
128
127
  ---
@@ -141,11 +140,11 @@ Values are automatically serialized to JSON. If the key already exists, it will
141
140
 
142
141
  **Parameters:**
143
142
 
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. |
143
+ | Parameter | Type | Description |
144
+ | --------- | --------------------- | ---------------------------------------------------------------------------------------- |
145
+ | `key` | `string` | The key to store the value under. |
146
+ | `value` | `any` | The value to store. Can be any JSON-serializable value. `undefined` is stored as `null`. |
147
+ | `options` | `Partial<SetOptions>` | Optional settings including TTL. |
149
148
 
150
149
  **Returns:** `Promise<boolean>` - `true` if the operation was successful.
151
150
 
@@ -179,7 +178,7 @@ setIfAbsent(key: string, value: any, options?: Partial<SetOptions>): Promise<boo
179
178
 
180
179
  ```typescript
181
180
  if (await client.setIfAbsent("lock:job:42", { by: "worker-1" }, { ttl: 30 })) {
182
- // we got the lock
181
+ // we got the lock
183
182
  }
184
183
  ```
185
184
 
@@ -210,22 +209,22 @@ decr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>
210
209
 
211
210
  **Parameters:**
212
211
 
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 |
212
+ | Parameter | Type | Default | Description |
213
+ | --------- | --------------------- | ------- | --------------------------------------------------------------- |
214
+ | `key` | `string` | — | The key to increment |
215
+ | `by` | `number` | `1` | Amount to add (or subtract for `decr`) |
216
+ | `options` | `Partial<SetOptions>` | — | TTL only applies on key creation — existing keys keep their TTL |
218
217
 
219
218
  **Returns:** the new value after the operation.
220
219
 
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.
220
+ **Errors:** throws `TypeError("KV value is not a number")` when the stored value is not a JSON number.
222
221
 
223
222
  **Example:**
224
223
 
225
224
  ```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
225
+ await client.incr("views"); // creates "views" = 1
226
+ await client.incr("views", 10); // now 11
227
+ await client.decr("views", 3); // now 8
229
228
 
230
229
  // Sliding window: TTL only applied on first hit
231
230
  await client.incr("rate:user:1", 1, { ttl: 60 });
@@ -245,14 +244,16 @@ cas(key: string, expected: any, next: any, options?: Partial<SetOptions>): Promi
245
244
 
246
245
  > Missing keys never match, even when `expected` is `null`.
247
246
 
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).
247
+ When `options.ttl` is supplied, the stored expiration is updated on success. When it is omitted, the existing TTL is preserved.
249
248
 
250
249
  **Example** (optimistic update):
251
250
 
252
251
  ```typescript
253
252
  const current = await client.get("counter");
254
253
  const swapped = await client.cas("counter", current, current + 1);
255
- if (!swapped) { /* retry or reconcile */ }
254
+ if (!swapped) {
255
+ /* retry or reconcile */
256
+ }
256
257
  ```
257
258
 
258
259
  ---
@@ -267,9 +268,9 @@ get(key: string): Promise<any>
267
268
 
268
269
  **Parameters:**
269
270
 
270
- | Parameter | Type | Description |
271
- |-----------|------|-------------|
272
- | `key` | `string` | The key to retrieve. |
271
+ | Parameter | Type | Description |
272
+ | --------- | -------- | -------------------- |
273
+ | `key` | `string` | The key to retrieve. |
273
274
 
274
275
  **Returns:** `Promise<any>` - The stored value, or `null` if the key doesn't exist or has expired.
275
276
 
@@ -278,7 +279,7 @@ get(key: string): Promise<any>
278
279
  ```typescript
279
280
  const user = await client.get("user:123");
280
281
  if (user) {
281
- console.log(user.name);
282
+ console.log(user.name);
282
283
  }
283
284
  ```
284
285
 
@@ -294,14 +295,12 @@ delete(key: string): Promise<boolean>
294
295
 
295
296
  **Parameters:**
296
297
 
297
- | Parameter | Type | Description |
298
- |-----------|------|-------------|
299
- | `key` | `string` | The key to delete. |
298
+ | Parameter | Type | Description |
299
+ | --------- | -------- | ------------------ |
300
+ | `key` | `string` | The key to delete. |
300
301
 
301
302
  **Returns:** `Promise<boolean>` - `true` if the key existed and was deleted, `false` if it didn't exist.
302
303
 
303
- > **Note:** Deno KV always returns `true`, even for non-existent keys.
304
-
305
304
  ---
306
305
 
307
306
  #### `exists(key)`
@@ -314,9 +313,9 @@ exists(key: string): Promise<boolean>
314
313
 
315
314
  **Parameters:**
316
315
 
317
- | Parameter | Type | Description |
318
- |-----------|------|-------------|
319
- | `key` | `string` | The key to check. |
316
+ | Parameter | Type | Description |
317
+ | --------- | -------- | ----------------- |
318
+ | `key` | `string` | The key to check. |
320
319
 
321
320
  **Returns:** `Promise<boolean>` - `true` if the key exists and hasn't expired.
322
321
 
@@ -334,15 +333,13 @@ expire(key: string, ttl: number): Promise<boolean>
334
333
 
335
334
  **Parameters:**
336
335
 
337
- | Parameter | Type | Description |
338
- |-----------|------|-------------|
339
- | `key` | `string` | The key to set expiration on. |
340
- | `ttl` | `number` | Time-to-live in seconds from now. |
336
+ | Parameter | Type | Description |
337
+ | --------- | -------- | --------------------------------- |
338
+ | `key` | `string` | The key to set expiration on. |
339
+ | `ttl` | `number` | Time-to-live in seconds from now. |
341
340
 
342
341
  **Returns:** `Promise<boolean>` - `true` if the expiration was set, `false` if the key doesn't exist.
343
342
 
344
- > **Note:** Not supported in Deno KV (always returns `false`).
345
-
346
343
  **Example:**
347
344
 
348
345
  ```typescript
@@ -367,25 +364,29 @@ type TtlResult =
367
364
 
368
365
  **Parameters:**
369
366
 
370
- | Parameter | Type | Description |
371
- |-----------|------|-------------|
372
- | `key` | `string` | The key to check. |
367
+ | Parameter | Type | Description |
368
+ | --------- | -------- | ----------------- |
369
+ | `key` | `string` | The key to check. |
373
370
 
374
371
  **Returns:** A `TtlResult`. Switch on `.state`:
375
372
  - `"missing"` — key doesn't exist (or has expired)
376
373
  - `"no-ttl"` — key exists with no expiration
377
374
  - `"expires"` — key exists and will expire at `.at`
378
375
 
379
- > **Note:** Deno KV cannot query TTL — existing keys always return `{ state: "no-ttl" }`; absent keys return `{ state: "missing" }`.
380
-
381
376
  **Example:**
382
377
 
383
378
  ```typescript
384
379
  const t = await client.ttl("session:abc");
385
380
  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;
381
+ case "expires":
382
+ console.log(`Expires at ${t.at.toISOString()}`);
383
+ break;
384
+ case "no-ttl":
385
+ console.log("No expiration set");
386
+ break;
387
+ case "missing":
388
+ console.log("Key does not exist");
389
+ break;
389
390
  }
390
391
  ```
391
392
 
@@ -424,8 +425,8 @@ Uses Redis-style wildcard patterns:
424
425
 
425
426
  **Parameters:**
426
427
 
427
- | Parameter | Type | Description |
428
- |-----------|------|-------------|
428
+ | Parameter | Type | Description |
429
+ | --------- | -------- | ---------------------------------------------------------------------- |
429
430
  | `pattern` | `string` | The pattern to match keys against (e.g., `"user:*"`, `"session:???"`). |
430
431
 
431
432
  **Returns:** `Promise<string[]>` - Array of matching keys (without namespace prefix), sorted alphabetically.
@@ -457,14 +458,14 @@ Ordering is not guaranteed across adapters — use `keys()` if you need sorted o
457
458
  **Per-adapter behavior:**
458
459
  - Redis: wraps `SCAN` (non-blocking).
459
460
  - 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
+ - SQLite: keyset pages of 500 keys (`key > last ORDER BY key`). Nothing stays open between pages, so an early break has nothing to release.
461
462
  - Memory: yields from the internal `Map`.
462
463
 
463
464
  **Example:**
464
465
 
465
466
  ```typescript
466
467
  for await (const k of client.keysIter("user:*")) {
467
- if (someCondition(k)) break; // safe — cursor is released
468
+ if (someCondition(k)) break; // safe — cursor is released
468
469
  }
469
470
  ```
470
471
 
@@ -482,8 +483,8 @@ Uses the same pattern syntax as `keys()`.
482
483
 
483
484
  **Parameters:**
484
485
 
485
- | Parameter | Type | Description |
486
- |-----------|------|-------------|
486
+ | Parameter | Type | Description |
487
+ | --------- | -------- | ---------------------------------- |
487
488
  | `pattern` | `string` | The pattern to match keys against. |
488
489
 
489
490
  **Returns:** `Promise<number>` - The number of keys deleted.
@@ -514,14 +515,14 @@ setMultiple(
514
515
 
515
516
  Accepts either the legacy tuple shape or an object shape that allows a **per-pair `ttl`** overriding `options.ttl`.
516
517
 
517
- More efficient than multiple individual `set` calls, especially for Redis, PostgreSQL, and Deno KV (the latter commits atomically).
518
+ More efficient than multiple individual `set` calls, especially for Redis and PostgreSQL.
518
519
 
519
520
  **Parameters:**
520
521
 
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`. |
522
+ | Parameter | Type | Description |
523
+ | --------- | --------------------------------------------- | ---------------------------------------------------- |
524
+ | `entries` | `[string, any][]` or `{ key, value, ttl? }[]` | Pairs to store. |
525
+ | `options` | `Partial<SetOptions>` | Fallback TTL used when a pair has no explicit `ttl`. |
525
526
 
526
527
  **Returns:** `Promise<boolean[]>` — one per entry.
527
528
 
@@ -529,11 +530,11 @@ More efficient than multiple individual `set` calls, especially for Redis, Postg
529
530
 
530
531
  ```typescript
531
532
  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 }
533
+ [
534
+ ["user:1", { name: "Alice" }], // uses options.ttl
535
+ { key: "user:2", value: { name: "Bob" }, ttl: 60 }, // overrides to 60s
536
+ ],
537
+ { ttl: 3600 },
537
538
  );
538
539
  ```
539
540
 
@@ -551,9 +552,9 @@ More efficient than multiple individual `get` calls.
551
552
 
552
553
  **Parameters:**
553
554
 
554
- | Parameter | Type | Description |
555
- |-----------|------|-------------|
556
- | `keys` | `string[]` | Array of keys to retrieve. |
555
+ | Parameter | Type | Description |
556
+ | --------- | ---------- | -------------------------- |
557
+ | `keys` | `string[]` | Array of keys to retrieve. |
557
558
 
558
559
  **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
560
 
@@ -581,19 +582,19 @@ transaction(operations: Operation[]): Promise<any[]>
581
582
 
582
583
  Atomicity per adapter:
583
584
 
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) |
585
+ | Adapter | Atomic | Notes |
586
+ | ---------- | :----: | -------------------------------------------------------------------- |
587
+ | Memory | ✓ | Single-threaded by nature |
588
+ | Redis | ✓ | Uses `MULTI`/`EXEC` |
589
+ | PostgreSQL | ✓ | Pins a single connection for `BEGIN`/…/`COMMIT`, even on a `pg.Pool` |
590
+ | SQLite | ✓ | `BEGIN IMMEDIATE`; a savepoint inside a caller-opened transaction |
590
591
 
591
- Per-operation `options.ttl` is honored by **all** adapters (Redis, PostgreSQL, Memory, Deno KV).
592
+ Per-operation `options.ttl` is honored by **all** adapters (Redis, PostgreSQL, SQLite, Memory).
592
593
 
593
594
  **Parameters:**
594
595
 
595
- | Parameter | Type | Description |
596
- |-----------|------|-------------|
596
+ | Parameter | Type | Description |
597
+ | ------------ | ------------- | ------------------------------- |
597
598
  | `operations` | `Operation[]` | Array of operations to execute. |
598
599
 
599
600
  **Returns:** `Promise<any[]>` - Array of results for each operation.
@@ -602,9 +603,9 @@ Per-operation `options.ttl` is honored by **all** adapters (Redis, PostgreSQL, M
602
603
 
603
604
  ```typescript
604
605
  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" },
606
+ { type: "set", key: "counter", value: 1, options: { ttl: 60 } },
607
+ { type: "get", key: "counter" },
608
+ { type: "delete", key: "old:key" },
608
609
  ]);
609
610
  // [true, 1, true]
610
611
  ```
@@ -619,8 +620,8 @@ Options for the `set` operation.
619
620
 
620
621
  ```typescript
621
622
  interface SetOptions {
622
- /** Time-to-live in seconds. After this time, the key will expire. */
623
- ttl: number;
623
+ /** Time-to-live in seconds. After this time, the key will expire. */
624
+ ttl: number;
624
625
  }
625
626
  ```
626
627
 
@@ -632,8 +633,8 @@ Information about the adapter instance.
632
633
 
633
634
  ```typescript
634
635
  interface AdapterInfo {
635
- /** The adapter type identifier. */
636
- type: string; // "redis" | "postgres" | "memory" | "deno-kv"
636
+ /** The adapter type identifier. */
637
+ type: string; // "redis" | "postgres" | "sqlite" | "memory"
637
638
  }
638
639
  ```
639
640
 
@@ -645,18 +646,18 @@ Base options shared by all adapter implementations.
645
646
 
646
647
  ```typescript
647
648
  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;
649
+ /** Default TTL in seconds applied to all set operations when not explicitly specified. Set to 0 to disable. */
650
+ defaultTtl: number;
651
+ /** Optional logger instance for debugging and error logging. */
652
+ logger?: Logger;
653
+ /**
654
+ * When true (default), keys are validated on every operation:
655
+ * - non-empty string
656
+ * - no `\0` characters
657
+ * - total `namespace + key` length ≤ 512
658
+ * Set to false to opt out.
659
+ */
660
+ validateKeys?: boolean;
660
661
  }
661
662
  ```
662
663
 
@@ -666,9 +667,9 @@ interface AdapterAbstractOptions {
666
667
 
667
668
  ```typescript
668
669
  type TtlResult =
669
- | { state: "missing" }
670
- | { state: "no-ttl" }
671
- | { state: "expires"; at: Date };
670
+ | { state: "missing" }
671
+ | { state: "no-ttl" }
672
+ | { state: "expires"; at: Date };
672
673
  ```
673
674
 
674
675
  Return shape of `ttl(key)`. See the `ttl()` method above.
@@ -678,39 +679,27 @@ Return shape of `ttl(key)`. See the `ttl()` method above.
678
679
  ### `SetMultipleEntry`
679
680
 
680
681
  ```typescript
681
- type SetMultipleEntry =
682
- | [string, any]
683
- | { key: string; value: any; ttl?: number };
682
+ type SetMultipleEntry = [string, any] | { key: string; value: any; ttl?: number };
684
683
  ```
685
684
 
686
685
  Input shape accepted by `setMultiple()`.
687
686
 
688
687
  ---
689
688
 
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
689
  ### `Operation`
701
690
 
702
691
  Represents a single operation within a transaction.
703
692
 
704
693
  ```typescript
705
694
  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>;
695
+ /** The type of operation to perform. */
696
+ type: "set" | "get" | "delete";
697
+ /** The key to operate on. */
698
+ key: string;
699
+ /** The value to set (only used for "set" operations). */
700
+ value?: any;
701
+ /** Optional settings for the operation (only used for "set" operations). */
702
+ options?: Partial<SetOptions>;
714
703
  }
715
704
  ```
716
705
 
@@ -722,12 +711,12 @@ interface Operation {
722
711
 
723
712
  ```typescript
724
713
  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;
714
+ /**
715
+ * Interval in seconds for automatic cleanup of expired keys.
716
+ * Set to 0 to disable automatic cleanup (expired keys will still be
717
+ * lazily removed on access).
718
+ */
719
+ ttlCleanupIntervalSec: number;
731
720
  }
732
721
  ```
733
722
 
@@ -737,16 +726,16 @@ interface AdapterMemoryOptions extends AdapterAbstractOptions {
737
726
 
738
727
  ```typescript
739
728
  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;
729
+ /**
730
+ * Redis client instance created via `createClient()` or `createClientPool()`.
731
+ * Pool support is experimental and not fully tested.
732
+ */
733
+ db: ReturnType<typeof createClient> | ReturnType<typeof createClientPool>;
734
+ /**
735
+ * Set to `true` if connecting to a Redis Cluster.
736
+ * Note: `keys()` and `clear()` operations are not supported in cluster mode.
737
+ */
738
+ isCluster: boolean;
750
739
  }
751
740
  ```
752
741
 
@@ -764,22 +753,22 @@ interface AdapterRedisOptions extends AdapterAbstractOptions {
764
753
 
765
754
  ```typescript
766
755
  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;
756
+ /** PostgreSQL connection instance - either `pg.Pool` or `pg.Client`. */
757
+ db: pg.Pool | pg.Client;
758
+ /**
759
+ * Name of the table to use for storing key-value pairs.
760
+ * The table will be created automatically if it doesn't exist.
761
+ * May be prefixed with a schema, e.g. "public.kv".
762
+ * Must match `^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$`
763
+ * (word characters, optionally with one `schema.` prefix).
764
+ * @default "__kv"
765
+ */
766
+ tableName: string;
767
+ /**
768
+ * Interval in seconds for automatic cleanup of expired keys.
769
+ * Set to 0 to disable automatic cleanup.
770
+ */
771
+ ttlCleanupIntervalSec: number;
783
772
  }
784
773
  ```
785
774
 
@@ -795,40 +784,53 @@ interface AdapterPostgresOptions extends AdapterAbstractOptions {
795
784
 
796
785
  ---
797
786
 
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;
787
+ ### `AdapterSqliteOptions`
788
+
789
+ ```typescript
790
+ interface AdapterSqliteOptions extends AdapterAbstractOptions {
791
+ /**
792
+ * An open `node:sqlite` database, e.g. `new DatabaseSync("kv.db")`. The caller owns
793
+ * it: `destroy()` never closes it, so one handle can be shared across adapters.
794
+ */
795
+ db: DatabaseSync;
796
+ /**
797
+ * Name of the table to use for storing key-value pairs.
798
+ * The table will be created automatically if it doesn't exist.
799
+ * Must match `^[A-Za-z_][A-Za-z0-9_]*$` (no `schema.` prefix).
800
+ * @default "__kv"
801
+ */
802
+ tableName: string;
803
+ /**
804
+ * Interval in seconds for automatic cleanup of expired keys.
805
+ * Set to 0 to disable automatic cleanup.
806
+ */
807
+ ttlCleanupIntervalSec: number;
821
808
  }
822
809
  ```
823
810
 
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.
811
+ **Connection ownership:** the adapter never opens, closes or reconfigures the handle — it
812
+ sets no pragmas. For several processes on one file, open it with a busy timeout
813
+ (`new DatabaseSync(path, { timeout: 5000 })`) so a locked write waits instead of failing,
814
+ and consider `PRAGMA journal_mode = WAL`.
815
+
816
+ **Atomicity:** `setIfAbsent`, `cas`, `expire` and `set` are single statements.
817
+ `getSet`, `incr`/`decr`, `setMultiple`, `clear` and `transaction` run in `BEGIN IMMEDIATE`,
818
+ which takes the write lock up front, so they stay atomic against other connections and
819
+ processes. Called inside a transaction you opened on the same handle (`db.isTransaction`),
820
+ they use a savepoint instead: their own failure rolls back only themselves, and your
821
+ `COMMIT`/`ROLLBACK` decides the rest.
822
+
823
+ **Synchronous driver:** `node:sqlite` blocks the event loop for the duration of each call.
824
+ Every method still returns a Promise, like the other adapters.
825
+
826
+ **Pattern matching** uses SQLite `GLOB`, which is case-sensitive and uses the primary-key
827
+ index for a literal prefix. `[` is escaped, so `keys()` / `clear()` follow the same
828
+ literal-except-`*`/`?` rules as every adapter.
829
+
830
+ **Table Schema:**
831
+ - `key` (TEXT) - Primary key
832
+ - `value` (TEXT) - Stored value as JSON text
833
+ - `expires_at` (INTEGER) - Expiration time as epoch milliseconds; `NULL` = no expiration
832
834
 
833
835
  ---
834
836
 
@@ -839,17 +841,14 @@ interface AdapterDenoKvOptions extends AdapterAbstractOptions {
839
841
  Delays execution for the specified number of milliseconds.
840
842
 
841
843
  ```typescript
842
- function sleep(
843
- timeout: number,
844
- __timeout_ref__?: { id: number }
845
- ): Promise<void>
844
+ function sleep(timeout: number, __timeout_ref__?: { id: number }): Promise<void>;
846
845
  ```
847
846
 
848
847
  **Parameters:**
849
848
 
850
- | Parameter | Type | Default | Description |
851
- |-----------|------|---------|-------------|
852
- | `timeout` | `number` | - | The delay in milliseconds. |
849
+ | Parameter | Type | Default | Description |
850
+ | ----------------- | ---------------- | ------------ | ---------------------------------------------------------------- |
851
+ | `timeout` | `number` | - | The delay in milliseconds. |
853
852
  | `__timeout_ref__` | `{ id: number }` | `{ id: -1 }` | Optional reference object to capture the timeout ID for cleanup. |
854
853
 
855
854
  **Example:**