@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/AGENTS.md +85 -54
- package/API.md +151 -209
- package/README.md +69 -42
- package/dist/adapter/abstract.d.ts +6 -17
- package/dist/adapter/abstract.js +10 -24
- 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/{mod.d.ts → index.d.ts} +1 -2
- package/dist/{mod.js → index.js} +0 -1
- package/dist/kv.d.ts +9 -22
- package/dist/kv.js +3 -18
- package/dist/utils/sleep.d.ts +1 -1
- package/dist/utils/sleep.js +2 -2
- package/package.json +70 -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"` | `"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
|
|
108
|
-
|
|
109
|
-
| `hard`
|
|
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",
|
|
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
|
|
145
|
-
|
|
146
|
-
| `key`
|
|
147
|
-
| `value`
|
|
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
|
-
|
|
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
|
|
214
|
-
|
|
215
|
-
| `key`
|
|
216
|
-
| `by`
|
|
217
|
-
| `options` | `Partial<SetOptions>` | —
|
|
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.
|
|
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");
|
|
227
|
-
await client.incr("views", 10);
|
|
228
|
-
await client.decr("views", 3);
|
|
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
|
|
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) {
|
|
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
|
|
271
|
-
|
|
272
|
-
| `key`
|
|
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
|
-
|
|
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
|
|
298
|
-
|
|
299
|
-
| `key`
|
|
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
|
|
318
|
-
|
|
319
|
-
| `key`
|
|
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
|
|
338
|
-
|
|
339
|
-
| `key`
|
|
340
|
-
| `ttl`
|
|
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
|
|
371
|
-
|
|
372
|
-
| `key`
|
|
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
|
-
|
|
387
|
-
|
|
388
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
512
|
+
More efficient than multiple individual `set` calls, especially for Redis and PostgreSQL.
|
|
518
513
|
|
|
519
514
|
**Parameters:**
|
|
520
515
|
|
|
521
|
-
| Parameter | Type
|
|
522
|
-
|
|
523
|
-
| `entries` | `[string, any][]` or `{ key, value, ttl? }[]` | Pairs to store.
|
|
524
|
-
| `options` | `Partial<SetOptions>`
|
|
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
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
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
|
|
555
|
-
|
|
556
|
-
| `keys`
|
|
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
|
|
585
|
-
|
|
586
|
-
| Memory
|
|
587
|
-
| Redis
|
|
588
|
-
| PostgreSQL |
|
|
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
|
|
585
|
+
Per-operation `options.ttl` is honored by **all** adapters (Redis, PostgreSQL, Memory).
|
|
592
586
|
|
|
593
587
|
**Parameters:**
|
|
594
588
|
|
|
595
|
-
| Parameter
|
|
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
|
-
|
|
606
|
-
|
|
607
|
-
|
|
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
|
-
|
|
623
|
-
|
|
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
|
-
|
|
636
|
-
|
|
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
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
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
|
-
|
|
670
|
-
|
|
671
|
-
|
|
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
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
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
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
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
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
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
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
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
|
|
851
|
-
|
|
852
|
-
| `timeout`
|
|
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:**
|