@marianmeres/kv 2.1.0 → 2.2.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 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.0.0
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()` and `_resolveTtl()` helpers; do not re-implement per-adapter.
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
- set(key: string, value: any, options?: SetOptions): Promise<boolean>
78
- get(key: string): Promise<any>
79
- delete(key: string): Promise<boolean>
80
- exists(key: string): Promise<boolean>
81
- keys(pattern: string): Promise<string[]>
82
- clear(pattern: string): Promise<number>
83
- setMultiple(pairs: [string, any][], options?: SetOptions): Promise<boolean[]>
84
- getMultiple(keys: string[]): Promise<Record<string, any>>
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
- expire(key: string, ttl: number): Promise<boolean>
87
- ttl(key: string): Promise<Date | null | false>
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 time of a key.
357
+ Gets the expiration state of a key as a discriminated union.
266
358
 
267
359
  ```typescript
268
- ttl(key: string): Promise<Date | null | false>
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
- - `Date` - The expiration date if TTL is set
279
- - `null` - If the key exists but has no expiration
280
- - `false` - If the key doesn't exist or has expired
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 returns `null` (TTL query not supported).
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 expiry = await client.ttl("session:abc");
288
- if (expiry instanceof Date) {
289
- console.log(`Expires at: ${expiry.toISOString()}`);
290
- } else if (expiry === null) {
291
- console.log("No expiration set");
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(keyValuePairs, options?)`
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(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<boolean[]>
509
+ setMultiple(
510
+ entries: [string, any][] | { key: string; value: any; ttl?: number }[],
511
+ options?: Partial<SetOptions>
512
+ ): Promise<boolean[]>
373
513
  ```
374
514
 
375
- More efficient than multiple individual `set` calls, especially for Redis and PostgreSQL.
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
- | `keyValuePairs` | `[string, any][]` | Array of `[key, value]` tuples to store. |
382
- | `options` | `Partial<SetOptions>` | Optional settings applied to all pairs (e.g., TTL). |
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[]>` - Array of boolean results for each operation.
526
+ **Returns:** `Promise<boolean[]>` — one per entry.
385
527
 
386
528
  **Example:**
387
529
 
388
530
  ```typescript
389
- await client.setMultiple([
390
- ["user:1", { name: "Alice" }],
391
- ["user:2", { name: "Bob" }],
392
- ], { ttl: 3600 });
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()` is not supported (always returns `null`)
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
- client.setMultiple(keyValuePairs: [string, any][], options?): Promise<any[]>
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<Date | null | false>
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()` query | ✓ | ✓ | ✓ | always `null` |
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 | ✓ | ✓ | ✓ | always `true` |
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,