@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.
@@ -4,7 +4,7 @@
4
4
  * Deno KV key-value storage adapter implementation.
5
5
  */
6
6
  import { createClog } from "@marianmeres/clog";
7
- import { AdapterAbstract, } from "./abstract.js";
7
+ import { AdapterAbstract, KvRaceError, } from "./abstract.js";
8
8
  /**
9
9
  * Deno KV key-value storage adapter.
10
10
  *
@@ -13,11 +13,14 @@ import { AdapterAbstract, } from "./abstract.js";
13
13
  *
14
14
  * @remarks
15
15
  * - Only works in Deno runtime (will throw error in Node.js)
16
- * - `delete()` always returns `true` (Deno.Kv limitation)
17
- * - `expire()` is not supported - always returns `false`
18
- * - `ttl()` is not supported - always returns `null`
19
- * - TTL can be set during `set()` but cannot be queried afterward
16
+ * - `delete()` returns `true` by default even for missing keys (Deno.Kv
17
+ * limitation); opt in to strict behavior via `strictDeleteResult: true`
18
+ * - `expire()` is not supported — always returns `false`
19
+ * - `ttl()` returns `{ state: "no-ttl" }` for present keys (TTL cannot be
20
+ * queried) and `{ state: "missing" }` for absent ones
20
21
  * - Uses `getMany()` for efficient batch reads
22
+ * - Atomic primitives (`incr`, `decr`, `getSet`, `cas`) use a CAS retry loop
23
+ * backed by Deno.Kv's native `atomic().check()`
21
24
  *
22
25
  * @example
23
26
  * ```typescript
@@ -34,6 +37,9 @@ export class AdapterDenoKv extends AdapterAbstract {
34
37
  defaultTtl: 0, // no ttl by default
35
38
  db: null, // will be set in constructor via options merge
36
39
  logger: createClog("KV/deno-kv"),
40
+ validateKeys: true,
41
+ strictDeleteResult: false,
42
+ atomicRetryAttempts: 20,
37
43
  };
38
44
  constructor(namespace = "", options = {}) {
39
45
  super();
@@ -55,6 +61,9 @@ export class AdapterDenoKv extends AdapterAbstract {
55
61
  return Promise.resolve();
56
62
  }
57
63
  #denoKvKey(key, full = true) {
64
+ // validate via base (no-op if validateKeys is false)
65
+ if (full)
66
+ this._withNs(key);
58
67
  const parts = key.split(":");
59
68
  const prefix = parts[0];
60
69
  const rest = parts.slice(1).join(":");
@@ -70,16 +79,29 @@ export class AdapterDenoKv extends AdapterAbstract {
70
79
  const ttl = this._resolveTtl(options);
71
80
  if (value === undefined)
72
81
  value = null;
73
- // Deno.Kv does not require this, but for the consistency with other adapters
74
- // let's just stringify (the toJSON may do magic, so we want consistent behavior
75
- // across adapters)
76
- value = JSON.stringify(value);
77
- await db.set(this.#denoKvKey(key), value, {
82
+ const serialized = JSON.stringify(value);
83
+ await db.set(this.#denoKvKey(key), serialized, {
78
84
  expireIn: ttl ? ttl * 1000 : undefined,
79
85
  });
80
86
  return true;
81
87
  }
82
- /** Will return the internal value */
88
+ /** @inheritdoc */
89
+ async setIfAbsent(key, value, options = {}) {
90
+ this._assertInitialized();
91
+ const { db } = this.options;
92
+ const ttl = this._resolveTtl(options);
93
+ if (value === undefined)
94
+ value = null;
95
+ const serialized = JSON.stringify(value);
96
+ const kvKey = this.#denoKvKey(key);
97
+ const res = await db
98
+ .atomic()
99
+ .check({ key: kvKey, versionstamp: null })
100
+ .set(kvKey, serialized, { expireIn: ttl ? ttl * 1000 : undefined })
101
+ .commit();
102
+ return !!res?.ok;
103
+ }
104
+ /** Parses a Deno.Kv entry's stored value back to its JSON form. */
83
105
  #parseValue(row) {
84
106
  try {
85
107
  return JSON.parse(`${row?.value ?? null}`);
@@ -88,6 +110,106 @@ export class AdapterDenoKv extends AdapterAbstract {
88
110
  return row?.value;
89
111
  }
90
112
  }
113
+ /**
114
+ * Runs a CAS-style update. The `mutate` fn takes the current value
115
+ * (or `undefined` when missing) and returns `{ next, ttlMs?, result }`.
116
+ * Retries on atomic-commit contention; throws `KvRaceError` on exhaustion.
117
+ */
118
+ async #atomicUpdate(key, mutate) {
119
+ const { db, atomicRetryAttempts = 20 } = this.options;
120
+ const kvKey = this.#denoKvKey(key);
121
+ for (let attempt = 0; attempt < atomicRetryAttempts; attempt++) {
122
+ const entry = await db.get(kvKey);
123
+ const exists = entry?.versionstamp !== null && entry?.versionstamp !== undefined;
124
+ const current = exists ? this.#parseValue(entry) : undefined;
125
+ const decision = mutate(current, exists);
126
+ if ("abort" in decision)
127
+ return decision.result;
128
+ const nextSerialized = JSON.stringify(decision.next === undefined ? null : decision.next);
129
+ const atomic = db.atomic();
130
+ atomic.check({
131
+ key: kvKey,
132
+ versionstamp: exists ? entry.versionstamp : null,
133
+ });
134
+ atomic.set(kvKey, nextSerialized, { expireIn: decision.expireInMs });
135
+ const res = await atomic.commit();
136
+ if (res?.ok)
137
+ return decision.result;
138
+ // Exponential backoff with jitter, capped at 50ms. Minimal blocking,
139
+ // enough to break symmetric contention between many parallel callers.
140
+ const backoffMs = Math.min(50, 2 ** Math.min(attempt, 6)) * (0.5 + Math.random());
141
+ await new Promise((r) => setTimeout(r, backoffMs));
142
+ }
143
+ throw new KvRaceError(`Deno.Kv atomic update retries exhausted (${atomicRetryAttempts}) for key "${key}"`);
144
+ }
145
+ /** @inheritdoc */
146
+ async getSet(key, value, options = {}) {
147
+ this._assertInitialized();
148
+ const ttl = this._resolveTtl(options);
149
+ const expireInMs = ttl ? ttl * 1000 : undefined;
150
+ const next = value === undefined ? null : value;
151
+ return this.#atomicUpdate(key, (current) => ({
152
+ next,
153
+ expireInMs,
154
+ result: current === undefined ? null : current,
155
+ }));
156
+ }
157
+ async #incrBy(key, delta, options = {}) {
158
+ this._assertInitialized();
159
+ const ttl = this._resolveTtl(options);
160
+ const expireInMs = ttl ? ttl * 1000 : undefined;
161
+ return this.#atomicUpdate(key, (current, exists) => {
162
+ let base = 0;
163
+ if (exists) {
164
+ if (typeof current !== "number") {
165
+ throw new TypeError("KV value is not a number");
166
+ }
167
+ base = current;
168
+ }
169
+ const next = base + delta;
170
+ return {
171
+ next,
172
+ // Only apply TTL on key creation; preserving TTL on existing
173
+ // keys is not natively possible in Deno.Kv (every atomic set
174
+ // resets expireIn), so we skip expireIn when the key existed.
175
+ expireInMs: exists ? undefined : expireInMs,
176
+ result: next,
177
+ };
178
+ });
179
+ }
180
+ /** @inheritdoc */
181
+ incr(key, by = 1, options = {}) {
182
+ return this.#incrBy(key, by, options);
183
+ }
184
+ /** @inheritdoc */
185
+ decr(key, by = 1, options = {}) {
186
+ return this.#incrBy(key, -by, options);
187
+ }
188
+ /** @inheritdoc */
189
+ async cas(key, expected, next, options = {}) {
190
+ this._assertInitialized();
191
+ const hasTtl = options.ttl !== undefined;
192
+ const ttl = hasTtl ? this._resolveTtl(options) : undefined;
193
+ const expireInMs = ttl ? ttl * 1000 : undefined;
194
+ const expectedCanonical = JSON.stringify(expected ?? null);
195
+ return this.#atomicUpdate(key, (current, exists) => {
196
+ if (!exists)
197
+ return { abort: true, result: false };
198
+ if (JSON.stringify(current ?? null) !== expectedCanonical) {
199
+ return { abort: true, result: false };
200
+ }
201
+ return {
202
+ next: next === undefined ? null : next,
203
+ // When no TTL option is provided, preserve existing TTL. Deno.Kv
204
+ // doesn't let us read/keep it, so this is best-effort: omit
205
+ // `expireIn` and the atomic set clears any existing expiration.
206
+ // Documented limitation — callers who want to preserve TTL must
207
+ // re-supply it.
208
+ expireInMs: hasTtl ? expireInMs : undefined,
209
+ result: true,
210
+ };
211
+ });
212
+ }
91
213
  /** @inheritdoc */
92
214
  async get(key) {
93
215
  this._assertInitialized();
@@ -99,81 +221,109 @@ export class AdapterDenoKv extends AdapterAbstract {
99
221
  async exists(key) {
100
222
  this._assertInitialized();
101
223
  const { db } = this.options;
102
- // Deno.Kv returns an entry with `versionstamp: null` for missing keys,
103
- // and a non-null versionstamp for present keys — even if the stored value is null.
104
224
  const entry = await db.get(this.#denoKvKey(key));
105
225
  return entry?.versionstamp !== null && entry?.versionstamp !== undefined;
106
226
  }
107
227
  /** @inheritdoc */
108
228
  async delete(key) {
109
229
  this._assertInitialized();
110
- const { db } = this.options;
111
- await db.delete(this.#denoKvKey(key));
112
- return Promise.resolve(true); // always true
230
+ const { db, strictDeleteResult } = this.options;
231
+ const kvKey = this.#denoKvKey(key);
232
+ if (strictDeleteResult) {
233
+ const entry = await db.get(kvKey);
234
+ const existed = entry?.versionstamp !== null && entry?.versionstamp !== undefined;
235
+ await db.delete(kvKey);
236
+ return existed;
237
+ }
238
+ await db.delete(kvKey);
239
+ return true;
113
240
  }
114
241
  /** @inheritdoc */
115
242
  async keys(pattern) {
243
+ this._assertInitialized();
244
+ const out = [];
245
+ for await (const k of this.keysIter(pattern))
246
+ out.push(k);
247
+ return out.toSorted();
248
+ }
249
+ /** @inheritdoc */
250
+ async *keysIter(pattern) {
116
251
  this._assertInitialized();
117
252
  const { db } = this.options;
118
253
  const [firstSeg] = this.#denoKvKey(pattern, false);
119
254
  const regex = this._globToRegex(pattern);
120
255
  // Only use the first key segment as a Deno.Kv prefix if it contains
121
- // no wildcards — otherwise we must scan the whole namespace and rely
122
- // on regex filtering.
256
+ // no wildcards — otherwise scan the whole namespace and regex-filter.
123
257
  const firstIsLiteral = firstSeg !== undefined && firstSeg !== "*" && !/[*?]/.test(firstSeg);
124
258
  const listPrefix = firstIsLiteral
125
259
  ? [this.namespace, firstSeg]
126
260
  : [this.namespace];
127
- const iter = db.list({ prefix: listPrefix });
128
- const out = [];
129
- for await (const res of iter) {
130
- // We must iterate entries (Deno.Kv has no keys-only API), but we
131
- // deliberately do not touch `res.value` — no JSON parse, no copy.
261
+ for await (const res of db.list({ prefix: listPrefix })) {
262
+ // Iterate entries (Deno.Kv has no keys-only API) but do not touch
263
+ // `res.value` — no JSON parse, no copy.
132
264
  const key = res.key.slice(1).join(":");
133
265
  if (pattern === "*" || regex.test(key)) {
134
- out.push(key);
266
+ yield key;
135
267
  }
136
268
  }
137
- return out.toSorted();
138
269
  }
139
270
  /** @inheritdoc */
140
271
  async clear(pattern) {
141
272
  this._assertInitialized();
142
- const keysToDelete = await this.keys(pattern);
273
+ const { db } = this.options;
143
274
  let deleteCount = 0;
144
- for (const key of keysToDelete) {
145
- await this.delete(key);
275
+ // Batch deletes via atomic to reduce round-trips — but Deno.Kv caps
276
+ // atomic operations, so chunk at 500.
277
+ const CHUNK = 500;
278
+ let atomic = db.atomic();
279
+ let inBatch = 0;
280
+ for await (const key of this.keysIter(pattern)) {
281
+ atomic.delete(this.#denoKvKey(key));
282
+ inBatch++;
146
283
  deleteCount++;
284
+ if (inBatch >= CHUNK) {
285
+ await atomic.commit();
286
+ atomic = db.atomic();
287
+ inBatch = 0;
288
+ }
147
289
  }
290
+ if (inBatch > 0)
291
+ await atomic.commit();
148
292
  return deleteCount;
149
293
  }
150
294
  /** @inheritdoc */
151
- async setMultiple(keyValuePairs, options = {}) {
295
+ async setMultiple(entries, options = {}) {
152
296
  this._assertInitialized();
153
- if (keyValuePairs.length === 0)
297
+ if (entries.length === 0)
154
298
  return [];
299
+ const normalized = this._normalizePairs(entries);
155
300
  const { db } = this.options;
156
- const ttl = this._resolveTtl(options);
157
- const expireIn = ttl ? ttl * 1000 : undefined;
158
- // batch into a single atomic commit (all-or-nothing)
301
+ // Atomic commit for all-or-nothing semantics.
159
302
  const atomic = db.atomic();
160
- for (const [key, value] of keyValuePairs) {
303
+ for (const { key, value, ttl: pairTtl } of normalized) {
304
+ const ttl = this._resolveTtl({ ttl: pairTtl ?? options.ttl });
161
305
  const v = value === undefined ? null : value;
162
- atomic.set(this.#denoKvKey(key), JSON.stringify(v), { expireIn });
306
+ atomic.set(this.#denoKvKey(key), JSON.stringify(v), {
307
+ expireIn: ttl ? ttl * 1000 : undefined,
308
+ });
163
309
  }
164
310
  const res = await atomic.commit();
165
311
  const ok = !!res?.ok;
166
- return keyValuePairs.map(() => ok);
312
+ return normalized.map(() => ok);
167
313
  }
168
314
  /** @inheritdoc */
169
315
  async getMultiple(keys) {
170
316
  this._assertInitialized();
171
317
  const { db } = this.options;
172
318
  const result = {};
319
+ if (keys.length === 0)
320
+ return result;
173
321
  const denoKvKeys = keys.map((k) => this.#denoKvKey(k));
174
322
  const results = await db.getMany(denoKvKeys);
175
323
  for (const [index, row] of results.entries()) {
176
- result[keys[index]] = this.#parseValue(row);
324
+ const origKey = keys[index];
325
+ const hasValue = row?.versionstamp !== null && row?.versionstamp !== undefined;
326
+ result[origKey] = hasValue ? this.#parseValue(row) : null;
177
327
  }
178
328
  return result;
179
329
  }
@@ -183,9 +333,8 @@ export class AdapterDenoKv extends AdapterAbstract {
183
333
  const { db } = this.options;
184
334
  // When the transaction contains only set/delete ops we can use Deno.Kv's
185
335
  // native atomic() for true all-or-nothing semantics. A `get` inside the
186
- // transaction breaks that — Deno.Kv has no atomic-read — so in that case
187
- // we fall back to sequential execution (consistent with pre-existing
188
- // behavior).
336
+ // transaction breaks that — Deno.Kv has no atomic-read — so in that
337
+ // case we fall back to sequential execution.
189
338
  const hasGet = operations.some((op) => op.type === "get");
190
339
  if (!hasGet && operations.length > 0) {
191
340
  const atomic = db.atomic();
@@ -202,9 +351,9 @@ export class AdapterDenoKv extends AdapterAbstract {
202
351
  }
203
352
  }
204
353
  const res = await atomic.commit();
205
- const ok = !!res?.ok;
206
- if (!ok)
354
+ if (!res?.ok) {
207
355
  throw new Error("Deno.Kv atomic transaction failed to commit");
356
+ }
208
357
  return operations.map(() => true);
209
358
  }
210
359
  // Sequential fallback — operations are NOT atomic.
@@ -225,19 +374,23 @@ export class AdapterDenoKv extends AdapterAbstract {
225
374
  return results;
226
375
  }
227
376
  /**
228
- * Not supported in Deno.Kv - always returns `false`.
377
+ * Not supported in Deno.Kv — always returns `false`.
229
378
  * @inheritdoc
230
379
  */
231
- expire(key, ttl) {
380
+ expire(_key, _ttl) {
232
381
  this._assertInitialized();
233
382
  return Promise.resolve(false);
234
383
  }
235
384
  /**
236
- * Not supported in Deno.Kv - always returns `null`.
237
- * @inheritdoc
385
+ * Deno.Kv cannot report TTL state. Returns `{ state: "no-ttl" }` for
386
+ * existing keys (whether or not they actually have an expireIn set)
387
+ * and `{ state: "missing" }` for absent keys.
238
388
  */
239
- ttl(key) {
389
+ async ttl(key) {
240
390
  this._assertInitialized();
241
- return Promise.resolve(null);
391
+ const { db } = this.options;
392
+ const entry = await db.get(this.#denoKvKey(key));
393
+ const exists = entry?.versionstamp !== null && entry?.versionstamp !== undefined;
394
+ return exists ? { state: "no-ttl" } : { state: "missing" };
242
395
  }
243
396
  }
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * In-memory key-value storage adapter implementation.
5
5
  */
6
- import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetOptions } from "./abstract.js";
6
+ import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult } from "./abstract.js";
7
7
  /**
8
8
  * Configuration options for the in-memory KV adapter.
9
9
  */
@@ -50,6 +50,16 @@ export declare class AdapterMemory extends AdapterAbstract {
50
50
  /** @inheritdoc */
51
51
  set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
52
52
  /** @inheritdoc */
53
+ setIfAbsent(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
54
+ /** @inheritdoc */
55
+ getSet(key: string, value: any, options?: Partial<SetOptions>): Promise<any>;
56
+ /** @inheritdoc */
57
+ incr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>;
58
+ /** @inheritdoc */
59
+ decr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>;
60
+ /** @inheritdoc */
61
+ cas(key: string, expected: any, next: any, options?: Partial<SetOptions>): Promise<boolean>;
62
+ /** @inheritdoc */
53
63
  get(key: string): Promise<any>;
54
64
  /** @inheritdoc */
55
65
  delete(key: string): Promise<boolean>;
@@ -58,19 +68,21 @@ export declare class AdapterMemory extends AdapterAbstract {
58
68
  /** @inheritdoc */
59
69
  keys(pattern: string): Promise<string[]>;
60
70
  /** @inheritdoc */
71
+ keysIter(pattern: string): AsyncIterable<string>;
72
+ /** @inheritdoc */
61
73
  clear(pattern: string): Promise<number>;
62
74
  /** @inheritdoc */
63
- setMultiple(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<boolean[]>;
75
+ setMultiple(entries: readonly SetMultipleEntry[], options?: Partial<SetOptions>): Promise<boolean[]>;
64
76
  /** @inheritdoc */
65
77
  getMultiple(keys: string[]): Promise<Record<string, any>>;
66
78
  /** @inheritdoc */
67
79
  expire(key: string, ttl: number): Promise<boolean>;
68
80
  /** @inheritdoc */
69
- ttl(key: string): Promise<Date | null | false>;
81
+ ttl(key: string): Promise<TtlResult>;
70
82
  /** @inheritdoc */
71
83
  transaction(operations: Operation[]): Promise<any[]>;
72
84
  __debug_dump(): Promise<Record<string, {
73
85
  value: unknown;
74
- ttl: Date | null | false;
86
+ ttl: Date | null;
75
87
  }>>;
76
88
  }