@marianmeres/kv 2.1.0 → 2.3.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 +45 -13
- package/API.md +230 -26
- package/README.md +64 -4
- package/dist/adapter/abstract.d.ts +121 -24
- package/dist/adapter/abstract.js +111 -22
- package/dist/adapter/deno-kv.d.ts +41 -11
- package/dist/adapter/deno-kv.js +201 -48
- package/dist/adapter/memory.d.ts +16 -4
- package/dist/adapter/memory.js +137 -78
- package/dist/adapter/postgres.d.ts +16 -28
- package/dist/adapter/postgres.js +184 -56
- package/dist/adapter/redis.d.ts +16 -4
- package/dist/adapter/redis.js +167 -33
- package/dist/kv.d.ts +2 -2
- package/dist/kv.js +1 -1
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -6,7 +6,7 @@ Machine-friendly reference for AI agents working with this codebase.
|
|
|
6
6
|
|
|
7
7
|
- **Stack**: TypeScript, Deno (primary), Node.js (via npm build)
|
|
8
8
|
- **Run**: `deno task test` | **Build**: `deno task npm:build`
|
|
9
|
-
- **Version**: 2.
|
|
9
|
+
- **Version**: 2.1.0
|
|
10
10
|
|
|
11
11
|
## Purpose
|
|
12
12
|
|
|
@@ -41,9 +41,15 @@ tests/
|
|
|
41
41
|
3. TTL is in seconds; stored as absolute `Date` internally.
|
|
42
42
|
4. Pattern matching: Redis-style (`*` = any chars, `?` = single char). All other characters — including `.`, `(`, `[`, `%`, `_` — are matched **literally**.
|
|
43
43
|
5. TTL resolution: `options.ttl ?? defaultTtl`; `0` or negative disables expiration for that call (explicitly overrides `defaultTtl`).
|
|
44
|
-
6. All pattern-to-regex / pattern-to-LIKE conversion lives in `abstract.ts` — use `_globToRegex()
|
|
44
|
+
6. All pattern-to-regex / pattern-to-LIKE conversion lives in `abstract.ts` — use `_globToRegex()`, `_resolveTtl()`, `_normalizePairs()`; do not re-implement per-adapter.
|
|
45
45
|
7. Postgres `transaction()` must pin a single connection via `pool.connect()`; every nested query uses that client, not `this.options.db`.
|
|
46
46
|
8. Redis adapter owns the connection iff `initialize()` opened it (`#weOpened` flag).
|
|
47
|
+
9. Key validation lives in `_withNs()` — enforced when `options.validateKeys !== false`. Reject empty strings, keys with `\0`, and total `namespace + key` length > 512.
|
|
48
|
+
10. `ttl()` returns `TtlResult = { state: "missing" | "no-ttl" | "expires"; at? }` — discriminated union, not `Date | null | false`.
|
|
49
|
+
11. `incr`/`decr`/`getSet`/`cas`/`setIfAbsent` must be atomic: Redis = Lua or NX; Postgres = UPSERT/UPDATE with RETURNING; Deno KV = `#atomicUpdate` CAS retry loop; Memory = plain read-modify-write (single-threaded).
|
|
50
|
+
12. Non-numeric `incr`/`decr` target throws `TypeError("KV value is not a number")`. In Postgres, detect via error code `22P02`.
|
|
51
|
+
13. Deno KV atomic retries exhausted → throw `KvRaceError` (imported from `abstract.ts`).
|
|
52
|
+
14. `keysIter` must clean up on early consumer break — PG releases its server-side cursor in the generator's `finally`.
|
|
47
53
|
|
|
48
54
|
## Before Making Changes
|
|
49
55
|
|
|
@@ -71,20 +77,35 @@ createKVClient(namespace?: string, type?: AdapterType, options?: AdapterOptions)
|
|
|
71
77
|
### Client Methods
|
|
72
78
|
|
|
73
79
|
```
|
|
80
|
+
// lifecycle
|
|
74
81
|
initialize(): Promise<void>
|
|
75
82
|
destroy(hard?: boolean): Promise<void>
|
|
76
83
|
info(): AdapterInfo
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
84
|
+
|
|
85
|
+
// single-key
|
|
86
|
+
set(key, value, options?): Promise<boolean>
|
|
87
|
+
setIfAbsent(key, value, options?): Promise<boolean> // atomic
|
|
88
|
+
getSet(key, value, options?): Promise<any> // returns previous
|
|
89
|
+
incr(key, by?=1, options?): Promise<number> // atomic
|
|
90
|
+
decr(key, by?=1, options?): Promise<number> // atomic
|
|
91
|
+
cas(key, expected, next, options?): Promise<boolean> // atomic
|
|
92
|
+
get(key): Promise<any>
|
|
93
|
+
delete(key): Promise<boolean>
|
|
94
|
+
exists(key): Promise<boolean>
|
|
95
|
+
|
|
96
|
+
// patterns
|
|
97
|
+
keys(pattern): Promise<string[]> // sorted
|
|
98
|
+
keysIter(pattern): AsyncIterable<string> // streaming
|
|
99
|
+
clear(pattern): Promise<number>
|
|
100
|
+
|
|
101
|
+
// batch
|
|
102
|
+
setMultiple(entries: SetMultipleEntry[], options?): Promise<boolean[]>
|
|
103
|
+
getMultiple(keys): Promise<Record<string, any>>
|
|
85
104
|
transaction(operations: Operation[]): Promise<any[]>
|
|
86
|
-
|
|
87
|
-
|
|
105
|
+
|
|
106
|
+
// TTL
|
|
107
|
+
expire(key, ttl): Promise<boolean>
|
|
108
|
+
ttl(key): Promise<TtlResult>
|
|
88
109
|
```
|
|
89
110
|
|
|
90
111
|
## Key Types
|
|
@@ -92,8 +113,19 @@ ttl(key: string): Promise<Date | null | false>
|
|
|
92
113
|
```typescript
|
|
93
114
|
interface SetOptions { ttl: number }
|
|
94
115
|
interface AdapterInfo { type: string }
|
|
95
|
-
interface AdapterAbstractOptions { defaultTtl: number; logger?: Logger }
|
|
116
|
+
interface AdapterAbstractOptions { defaultTtl: number; logger?: Logger; validateKeys?: boolean }
|
|
96
117
|
interface Operation { type: "set" | "get" | "delete"; key: string; value?: any; options?: SetOptions }
|
|
118
|
+
|
|
119
|
+
type SetMultipleEntry =
|
|
120
|
+
| [string, any]
|
|
121
|
+
| { key: string; value: any; ttl?: number };
|
|
122
|
+
|
|
123
|
+
type TtlResult =
|
|
124
|
+
| { state: "missing" }
|
|
125
|
+
| { state: "no-ttl" }
|
|
126
|
+
| { state: "expires"; at: Date };
|
|
127
|
+
|
|
128
|
+
class KvRaceError extends Error {} // Deno KV CAS retry-exhaustion
|
|
97
129
|
```
|
|
98
130
|
|
|
99
131
|
## Commands
|
package/API.md
CHANGED
|
@@ -165,6 +165,98 @@ await client.set("pinned", 1, { ttl: 0 }); // never expires, even if defaultTtl
|
|
|
165
165
|
|
|
166
166
|
---
|
|
167
167
|
|
|
168
|
+
#### `setIfAbsent(key, value, options?)`
|
|
169
|
+
|
|
170
|
+
Stores a value only if the key does not already exist. Atomic.
|
|
171
|
+
|
|
172
|
+
```typescript
|
|
173
|
+
setIfAbsent(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
**Returns:** `true` if the value was stored, `false` if the key existed. Expired keys are treated as missing — `setIfAbsent` succeeds on them.
|
|
177
|
+
|
|
178
|
+
**Example** (lock pattern):
|
|
179
|
+
|
|
180
|
+
```typescript
|
|
181
|
+
if (await client.setIfAbsent("lock:job:42", { by: "worker-1" }, { ttl: 30 })) {
|
|
182
|
+
// we got the lock
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
#### `getSet(key, value, options?)`
|
|
189
|
+
|
|
190
|
+
Atomically replaces the stored value and returns the previous one.
|
|
191
|
+
|
|
192
|
+
```typescript
|
|
193
|
+
getSet(key: string, value: any, options?: Partial<SetOptions>): Promise<any>
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
**Returns:** the previous value, or `null` if the key did not exist.
|
|
197
|
+
|
|
198
|
+
Stored falsy values (`false`, `0`, `""`, `null`) round-trip correctly.
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
#### `incr(key, by?, options?)` / `decr(key, by?, options?)`
|
|
203
|
+
|
|
204
|
+
Atomically increments (or decrements) a numeric value.
|
|
205
|
+
|
|
206
|
+
```typescript
|
|
207
|
+
incr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>
|
|
208
|
+
decr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
**Parameters:**
|
|
212
|
+
|
|
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 |
|
|
218
|
+
|
|
219
|
+
**Returns:** the new value after the operation.
|
|
220
|
+
|
|
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.
|
|
222
|
+
|
|
223
|
+
**Example:**
|
|
224
|
+
|
|
225
|
+
```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
|
|
229
|
+
|
|
230
|
+
// Sliding window: TTL only applied on first hit
|
|
231
|
+
await client.incr("rate:user:1", 1, { ttl: 60 });
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
#### `cas(key, expected, next, options?)`
|
|
237
|
+
|
|
238
|
+
Atomic compare-and-set — replaces the stored value only when the current value deep-equals `expected`.
|
|
239
|
+
|
|
240
|
+
```typescript
|
|
241
|
+
cas(key: string, expected: any, next: any, options?: Partial<SetOptions>): Promise<boolean>
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
**Returns:** `true` if the swap happened, `false` otherwise (mismatch or missing key).
|
|
245
|
+
|
|
246
|
+
> Missing keys never match, even when `expected` is `null`.
|
|
247
|
+
|
|
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).
|
|
249
|
+
|
|
250
|
+
**Example** (optimistic update):
|
|
251
|
+
|
|
252
|
+
```typescript
|
|
253
|
+
const current = await client.get("counter");
|
|
254
|
+
const swapped = await client.cas("counter", current, current + 1);
|
|
255
|
+
if (!swapped) { /* retry or reconcile */ }
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
168
260
|
#### `get(key)`
|
|
169
261
|
|
|
170
262
|
Retrieves a value by its key.
|
|
@@ -262,10 +354,15 @@ await client.expire("session:abc", 1800); // Expire in 30 minutes
|
|
|
262
354
|
|
|
263
355
|
#### `ttl(key)`
|
|
264
356
|
|
|
265
|
-
Gets the expiration
|
|
357
|
+
Gets the expiration state of a key as a discriminated union.
|
|
266
358
|
|
|
267
359
|
```typescript
|
|
268
|
-
ttl(key: string): Promise<
|
|
360
|
+
ttl(key: string): Promise<TtlResult>
|
|
361
|
+
|
|
362
|
+
type TtlResult =
|
|
363
|
+
| { state: "missing" }
|
|
364
|
+
| { state: "no-ttl" }
|
|
365
|
+
| { state: "expires"; at: Date };
|
|
269
366
|
```
|
|
270
367
|
|
|
271
368
|
**Parameters:**
|
|
@@ -274,26 +371,40 @@ ttl(key: string): Promise<Date | null | false>
|
|
|
274
371
|
|-----------|------|-------------|
|
|
275
372
|
| `key` | `string` | The key to check. |
|
|
276
373
|
|
|
277
|
-
**Returns:**
|
|
278
|
-
- `
|
|
279
|
-
- `
|
|
280
|
-
- `
|
|
374
|
+
**Returns:** A `TtlResult`. Switch on `.state`:
|
|
375
|
+
- `"missing"` — key doesn't exist (or has expired)
|
|
376
|
+
- `"no-ttl"` — key exists with no expiration
|
|
377
|
+
- `"expires"` — key exists and will expire at `.at`
|
|
281
378
|
|
|
282
|
-
> **Note:** Deno KV always
|
|
379
|
+
> **Note:** Deno KV cannot query TTL — existing keys always return `{ state: "no-ttl" }`; absent keys return `{ state: "missing" }`.
|
|
283
380
|
|
|
284
381
|
**Example:**
|
|
285
382
|
|
|
286
383
|
```typescript
|
|
287
|
-
const
|
|
288
|
-
|
|
289
|
-
console.log(`Expires at
|
|
290
|
-
|
|
291
|
-
console.log("
|
|
292
|
-
} else {
|
|
293
|
-
console.log("Key does not exist");
|
|
384
|
+
const t = await client.ttl("session:abc");
|
|
385
|
+
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;
|
|
294
389
|
}
|
|
295
390
|
```
|
|
296
391
|
|
|
392
|
+
**Migrating from pre-3.0** (`Date | null | false`):
|
|
393
|
+
|
|
394
|
+
```typescript
|
|
395
|
+
// old
|
|
396
|
+
const t = await client.ttl(k);
|
|
397
|
+
if (t instanceof Date) use(t);
|
|
398
|
+
else if (t === null) // no ttl
|
|
399
|
+
else // missing
|
|
400
|
+
|
|
401
|
+
// new (equivalent)
|
|
402
|
+
const t = await client.ttl(k);
|
|
403
|
+
if (t.state === "expires") use(t.at);
|
|
404
|
+
else if (t.state === "no-ttl") // no ttl
|
|
405
|
+
else // missing
|
|
406
|
+
```
|
|
407
|
+
|
|
297
408
|
---
|
|
298
409
|
|
|
299
410
|
### Pattern-Based Operations
|
|
@@ -333,6 +444,32 @@ const dotted = await client.keys("config.yaml"); // matches ONLY "config.yaml"
|
|
|
333
444
|
|
|
334
445
|
---
|
|
335
446
|
|
|
447
|
+
#### `keysIter(pattern)`
|
|
448
|
+
|
|
449
|
+
Iterates matching keys without materializing the full list. Prefer this over `keys()` for unbounded or unknown-sized scans.
|
|
450
|
+
|
|
451
|
+
```typescript
|
|
452
|
+
keysIter(pattern: string): AsyncIterable<string>
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
Ordering is not guaranteed across adapters — use `keys()` if you need sorted output.
|
|
456
|
+
|
|
457
|
+
**Per-adapter behavior:**
|
|
458
|
+
- Redis: wraps `SCAN` (non-blocking).
|
|
459
|
+
- 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
|
+
- Memory: yields from the internal `Map`.
|
|
462
|
+
|
|
463
|
+
**Example:**
|
|
464
|
+
|
|
465
|
+
```typescript
|
|
466
|
+
for await (const k of client.keysIter("user:*")) {
|
|
467
|
+
if (someCondition(k)) break; // safe — cursor is released
|
|
468
|
+
}
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
---
|
|
472
|
+
|
|
336
473
|
#### `clear(pattern)`
|
|
337
474
|
|
|
338
475
|
Deletes all keys matching a pattern.
|
|
@@ -364,32 +501,40 @@ const clearedAll = await client.clear("*"); // Clear everything
|
|
|
364
501
|
|
|
365
502
|
### Batch Operations
|
|
366
503
|
|
|
367
|
-
#### `setMultiple(
|
|
504
|
+
#### `setMultiple(entries, options?)`
|
|
368
505
|
|
|
369
506
|
Stores multiple key-value pairs in a single batch operation.
|
|
370
507
|
|
|
371
508
|
```typescript
|
|
372
|
-
setMultiple(
|
|
509
|
+
setMultiple(
|
|
510
|
+
entries: [string, any][] | { key: string; value: any; ttl?: number }[],
|
|
511
|
+
options?: Partial<SetOptions>
|
|
512
|
+
): Promise<boolean[]>
|
|
373
513
|
```
|
|
374
514
|
|
|
375
|
-
|
|
515
|
+
Accepts either the legacy tuple shape or an object shape that allows a **per-pair `ttl`** overriding `options.ttl`.
|
|
516
|
+
|
|
517
|
+
More efficient than multiple individual `set` calls, especially for Redis, PostgreSQL, and Deno KV (the latter commits atomically).
|
|
376
518
|
|
|
377
519
|
**Parameters:**
|
|
378
520
|
|
|
379
521
|
| Parameter | Type | Description |
|
|
380
522
|
|-----------|------|-------------|
|
|
381
|
-
| `
|
|
382
|
-
| `options` | `Partial<SetOptions>` |
|
|
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`. |
|
|
383
525
|
|
|
384
|
-
**Returns:** `Promise<boolean[]>`
|
|
526
|
+
**Returns:** `Promise<boolean[]>` — one per entry.
|
|
385
527
|
|
|
386
528
|
**Example:**
|
|
387
529
|
|
|
388
530
|
```typescript
|
|
389
|
-
await client.setMultiple(
|
|
390
|
-
[
|
|
391
|
-
|
|
392
|
-
|
|
531
|
+
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 }
|
|
537
|
+
);
|
|
393
538
|
```
|
|
394
539
|
|
|
395
540
|
---
|
|
@@ -504,11 +649,54 @@ interface AdapterAbstractOptions {
|
|
|
504
649
|
defaultTtl: number;
|
|
505
650
|
/** Optional logger instance for debugging and error logging. */
|
|
506
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;
|
|
507
660
|
}
|
|
508
661
|
```
|
|
509
662
|
|
|
510
663
|
---
|
|
511
664
|
|
|
665
|
+
### `TtlResult`
|
|
666
|
+
|
|
667
|
+
```typescript
|
|
668
|
+
type TtlResult =
|
|
669
|
+
| { state: "missing" }
|
|
670
|
+
| { state: "no-ttl" }
|
|
671
|
+
| { state: "expires"; at: Date };
|
|
672
|
+
```
|
|
673
|
+
|
|
674
|
+
Return shape of `ttl(key)`. See the `ttl()` method above.
|
|
675
|
+
|
|
676
|
+
---
|
|
677
|
+
|
|
678
|
+
### `SetMultipleEntry`
|
|
679
|
+
|
|
680
|
+
```typescript
|
|
681
|
+
type SetMultipleEntry =
|
|
682
|
+
| [string, any]
|
|
683
|
+
| { key: string; value: any; ttl?: number };
|
|
684
|
+
```
|
|
685
|
+
|
|
686
|
+
Input shape accepted by `setMultiple()`.
|
|
687
|
+
|
|
688
|
+
---
|
|
689
|
+
|
|
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
|
+
|
|
512
700
|
### `Operation`
|
|
513
701
|
|
|
514
702
|
Represents a single operation within a transaction.
|
|
@@ -615,16 +803,32 @@ interface AdapterDenoKvOptions extends AdapterAbstractOptions {
|
|
|
615
803
|
* Deno.Kv instance obtained via `Deno.openKv()`.
|
|
616
804
|
*/
|
|
617
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;
|
|
618
821
|
}
|
|
619
822
|
```
|
|
620
823
|
|
|
621
824
|
**Limitations:**
|
|
622
825
|
- Only works in Deno runtime
|
|
623
|
-
- `delete()` always returns `true` (Deno.Kv limitation)
|
|
826
|
+
- `delete()` always returns `true` by default (Deno.Kv limitation) — opt-in to strict behavior via `strictDeleteResult: true`
|
|
624
827
|
- `expire()` is not supported (always returns `false`)
|
|
625
|
-
- `ttl()`
|
|
828
|
+
- `ttl()` returns `{ state: "no-ttl" }` for any existing key and `{ state: "missing" }` for absent ones — Deno.Kv cannot report the actual expiration
|
|
626
829
|
- TTL can be set during `set()` but cannot be queried afterward
|
|
627
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.
|
|
628
832
|
|
|
629
833
|
---
|
|
630
834
|
|
package/README.md
CHANGED
|
@@ -48,17 +48,44 @@ await client.keys('my:*'); // ['my:foo:key']
|
|
|
48
48
|
## API
|
|
49
49
|
|
|
50
50
|
```typescript
|
|
51
|
+
// single-key ops
|
|
51
52
|
client.set(key: string, value: any, options?): Promise<boolean>
|
|
53
|
+
client.setIfAbsent(key: string, value: any, options?): Promise<boolean>
|
|
52
54
|
client.get(key: string): Promise<any>
|
|
55
|
+
client.getSet(key: string, value: any, options?): Promise<any> // returns previous value
|
|
53
56
|
client.delete(key: string): Promise<boolean>
|
|
54
57
|
client.exists(key: string): Promise<boolean>
|
|
58
|
+
|
|
59
|
+
// atomic primitives
|
|
60
|
+
client.incr(key: string, by?: number, options?): Promise<number>
|
|
61
|
+
client.decr(key: string, by?: number, options?): Promise<number>
|
|
62
|
+
client.cas(key: string, expected: any, next: any, options?): Promise<boolean>
|
|
63
|
+
|
|
64
|
+
// patterns & iteration
|
|
55
65
|
client.keys(pattern: string): Promise<string[]>
|
|
66
|
+
client.keysIter(pattern: string): AsyncIterable<string>
|
|
56
67
|
client.clear(pattern: string): Promise<number>
|
|
57
|
-
|
|
68
|
+
|
|
69
|
+
// batch
|
|
70
|
+
client.setMultiple(
|
|
71
|
+
entries: [string, any][] | { key: string; value: any; ttl?: number }[],
|
|
72
|
+
options?
|
|
73
|
+
): Promise<boolean[]>
|
|
58
74
|
client.getMultiple(keys: string[]): Promise<Record<string, any>>
|
|
59
75
|
client.transaction(operations: Operation[]): Promise<any[]>
|
|
76
|
+
|
|
77
|
+
// TTL
|
|
60
78
|
client.expire(key: string, ttl: number): Promise<boolean>
|
|
61
|
-
client.ttl(key: string): Promise<
|
|
79
|
+
client.ttl(key: string): Promise<TtlResult>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### `TtlResult`
|
|
83
|
+
|
|
84
|
+
```typescript
|
|
85
|
+
type TtlResult =
|
|
86
|
+
| { state: "missing" }
|
|
87
|
+
| { state: "no-ttl" }
|
|
88
|
+
| { state: "expires"; at: Date };
|
|
62
89
|
```
|
|
63
90
|
|
|
64
91
|
## Pattern Syntax
|
|
@@ -75,11 +102,14 @@ client.ttl(key: string): Promise<Date | null | false>
|
|
|
75
102
|
|---|:-:|:-:|:-:|:-:|
|
|
76
103
|
| Persistent | ✗ | ✓ | ✓ | ✓ |
|
|
77
104
|
| TTL on `set()` | ✓ | ✓ | ✓ | ✓ |
|
|
78
|
-
| `ttl()`
|
|
105
|
+
| `ttl()` → `expires`/`no-ttl`/`missing` | ✓ | ✓ | ✓ | `no-ttl`/`missing` only |
|
|
79
106
|
| `expire()` | ✓ | ✓ | ✓ | always `false` |
|
|
107
|
+
| Atomic `setIfAbsent` / `incr` / `decr` / `cas` / `getSet` | ✓ | ✓ (Lua) | ✓ (UPSERT) | ✓ (CAS retry loop) |
|
|
80
108
|
| Sorted `keys()` | ✓ | ✓ | ✓ | ✓ |
|
|
109
|
+
| Streaming `keysIter()` | ✓ | ✓ (SCAN) | ✓ (cursor) | ✓ (native) |
|
|
110
|
+
| Per-pair TTL in `setMultiple` | ✓ | ✓ | ✓ | ✓ |
|
|
81
111
|
| Atomic `transaction()` | ✓ (single-threaded) | ✓ (MULTI) | ✓ (BEGIN/COMMIT) | ✓ when no `get` ops |
|
|
82
|
-
| `delete()` returns real existed-flag | ✓ | ✓ | ✓ |
|
|
112
|
+
| `delete()` returns real existed-flag | ✓ | ✓ | ✓ | opt-in via `strictDeleteResult` |
|
|
83
113
|
| Background TTL cleanup | optional | native (Redis does it) | optional | native (Deno.Kv does it) |
|
|
84
114
|
| `keys()` / `clear()` | ✓ | ✓ (non-cluster only) | ✓ | ✓ |
|
|
85
115
|
|
|
@@ -107,6 +137,36 @@ client.ttl(key: string): Promise<Date | null | false>
|
|
|
107
137
|
- Data is not persisted (in-memory only).
|
|
108
138
|
- Supports optional TTL cleanup via `ttlCleanupIntervalSec` option.
|
|
109
139
|
|
|
140
|
+
## Breaking Changes (2.1 / 3.0 candidate)
|
|
141
|
+
|
|
142
|
+
Since 2.0, the following changes are in this tree:
|
|
143
|
+
|
|
144
|
+
**v3.0 (breaking — bump major if you ship these as-is):**
|
|
145
|
+
- **`ttl(key)` now returns a discriminated `TtlResult`** — `{ state: "missing" | "no-ttl" | "expires", at? }` — instead of `Date | null | false`. Migration:
|
|
146
|
+
```ts
|
|
147
|
+
// before
|
|
148
|
+
const t = await client.ttl(k);
|
|
149
|
+
if (t instanceof Date) use(t);
|
|
150
|
+
else if (t === null) /* no ttl */
|
|
151
|
+
else /* missing */
|
|
152
|
+
|
|
153
|
+
// after
|
|
154
|
+
const t = await client.ttl(k);
|
|
155
|
+
switch (t.state) {
|
|
156
|
+
case "expires": use(t.at); break;
|
|
157
|
+
case "no-ttl": /* … */; break;
|
|
158
|
+
case "missing": /* … */; break;
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
- **Key validation is on by default.** Non-empty strings, no `\0`, total `namespace + key` length ≤ 512. Set `validateKeys: false` on the adapter options to opt out. Previous behavior silently accepted empty/overlong keys and let the backend error cryptically.
|
|
162
|
+
|
|
163
|
+
**v2.1 / v2.2 (additive):**
|
|
164
|
+
- New methods `setIfAbsent`, `incr`, `decr`, `getSet`, `cas`, `keysIter` on every adapter.
|
|
165
|
+
- `setMultiple` accepts `{ key, value, ttl? }[]` entries in addition to the legacy `[key, value][]` tuples. Per-pair `ttl` overrides batch `options.ttl`.
|
|
166
|
+
- Deno KV: new `strictDeleteResult: true` option pre-checks existence so `delete()` returns the real did-it-exist flag (default stays `true` for BC).
|
|
167
|
+
- Deno KV: new `atomicRetryAttempts` option (default 20) for CAS-based primitives under contention.
|
|
168
|
+
- Default `clear()` in Deno KV now batches into atomic commits (500 at a time).
|
|
169
|
+
|
|
110
170
|
## Breaking Changes (2.0.0)
|
|
111
171
|
|
|
112
172
|
This release fixes several correctness bugs. Most fixes are behavior-preserving,
|