@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/AGENTS.md +92 -54
- package/API.md +201 -202
- package/README.md +95 -42
- package/dist/adapter/abstract.d.ts +8 -19
- package/dist/adapter/abstract.js +12 -26
- package/dist/adapter/memory.d.ts +2 -3
- package/dist/adapter/memory.js +2 -5
- package/dist/adapter/postgres.d.ts +1 -2
- package/dist/adapter/postgres.js +5 -6
- package/dist/adapter/redis.d.ts +1 -2
- package/dist/adapter/redis.js +4 -7
- package/dist/adapter/sqlite.d.ts +102 -0
- package/dist/adapter/sqlite.js +410 -0
- package/dist/{mod.d.ts → index.d.ts} +2 -2
- package/dist/{mod.js → index.js} +1 -1
- package/dist/kv.d.ts +19 -20
- package/dist/kv.js +12 -17
- package/dist/utils/sleep.d.ts +1 -1
- package/dist/utils/sleep.js +2 -2
- package/package.json +71 -37
- package/CLAUDE.md +0 -3
- package/dist/adapter/deno-kv.d.ts +0 -107
- package/dist/adapter/deno-kv.js +0 -396
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
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
|
35
|
-
|
|
36
|
-
| `namespace` | `string`
|
|
37
|
-
| `type`
|
|
38
|
-
| `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
|
-
//
|
|
70
|
-
|
|
71
|
-
const
|
|
72
|
-
await
|
|
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
|
|
108
|
-
|
|
109
|
-
| `hard`
|
|
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", "
|
|
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
|
|
145
|
-
|
|
146
|
-
| `key`
|
|
147
|
-
| `value`
|
|
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
|
-
|
|
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
|
|
214
|
-
|
|
215
|
-
| `key`
|
|
216
|
-
| `by`
|
|
217
|
-
| `options` | `Partial<SetOptions>` | —
|
|
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.
|
|
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");
|
|
227
|
-
await client.incr("views", 10);
|
|
228
|
-
await client.decr("views", 3);
|
|
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
|
|
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) {
|
|
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
|
|
271
|
-
|
|
272
|
-
| `key`
|
|
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
|
-
|
|
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
|
|
298
|
-
|
|
299
|
-
| `key`
|
|
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
|
|
318
|
-
|
|
319
|
-
| `key`
|
|
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
|
|
338
|
-
|
|
339
|
-
| `key`
|
|
340
|
-
| `ttl`
|
|
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
|
|
371
|
-
|
|
372
|
-
| `key`
|
|
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
|
-
|
|
387
|
-
|
|
388
|
-
|
|
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
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
|
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
|
|
518
|
+
More efficient than multiple individual `set` calls, especially for Redis and PostgreSQL.
|
|
518
519
|
|
|
519
520
|
**Parameters:**
|
|
520
521
|
|
|
521
|
-
| Parameter | Type
|
|
522
|
-
|
|
523
|
-
| `entries` | `[string, any][]` or `{ key, value, ttl? }[]` | Pairs to store.
|
|
524
|
-
| `options` | `Partial<SetOptions>`
|
|
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
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
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
|
|
555
|
-
|
|
556
|
-
| `keys`
|
|
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
|
|
585
|
-
|
|
586
|
-
| Memory
|
|
587
|
-
| Redis
|
|
588
|
-
| PostgreSQL |
|
|
589
|
-
|
|
|
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,
|
|
592
|
+
Per-operation `options.ttl` is honored by **all** adapters (Redis, PostgreSQL, SQLite, Memory).
|
|
592
593
|
|
|
593
594
|
**Parameters:**
|
|
594
595
|
|
|
595
|
-
| Parameter
|
|
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
|
-
|
|
606
|
-
|
|
607
|
-
|
|
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
|
-
|
|
623
|
-
|
|
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
|
-
|
|
636
|
-
|
|
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
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
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
|
-
|
|
670
|
-
|
|
671
|
-
|
|
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
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
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
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
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
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
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
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
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
|
-
### `
|
|
799
|
-
|
|
800
|
-
```typescript
|
|
801
|
-
interface
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
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
|
-
**
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
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
|
|
851
|
-
|
|
852
|
-
| `timeout`
|
|
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:**
|