@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.
@@ -1,396 +0,0 @@
1
- /**
2
- * @module
3
- *
4
- * Deno KV key-value storage adapter implementation.
5
- */
6
- import { createClog } from "@marianmeres/clog";
7
- import { AdapterAbstract, KvRaceError, } from "./abstract.js";
8
- /**
9
- * Deno KV key-value storage adapter.
10
- *
11
- * Provides persistent key-value storage using Deno's built-in KV store.
12
- * Only available when running in the Deno runtime.
13
- *
14
- * @remarks
15
- * - Only works in Deno runtime (will throw error in Node.js)
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
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()`
24
- *
25
- * @example
26
- * ```typescript
27
- * const kv = await Deno.openKv();
28
- * const client = createKVClient("myapp:", "deno-kv", { db: kv });
29
- * await client.initialize();
30
- * await client.set("user:123", { name: "John" }, { ttl: 3600 });
31
- * ```
32
- */
33
- export class AdapterDenoKv extends AdapterAbstract {
34
- namespace;
35
- _type = "deno-kv";
36
- options = {
37
- defaultTtl: 0, // no ttl by default
38
- db: null, // will be set in constructor via options merge
39
- logger: createClog("KV/deno-kv"),
40
- validateKeys: true,
41
- strictDeleteResult: false,
42
- atomicRetryAttempts: 20,
43
- };
44
- constructor(namespace = "", options = {}) {
45
- super();
46
- this.namespace = namespace;
47
- this._assertValidNamespace();
48
- this.options = Object.freeze({ ...this.options, ...(options || {}) });
49
- if (!this.options.db) {
50
- throw new Error("Missing Deno.Kv instance");
51
- }
52
- }
53
- /** @inheritdoc */
54
- initialize() {
55
- this._initialized = true;
56
- return Promise.resolve();
57
- }
58
- /** @inheritdoc */
59
- destroy(_hard) {
60
- this._initialized = false;
61
- return Promise.resolve();
62
- }
63
- #denoKvKey(key, full = true) {
64
- // validate via base (no-op if validateKeys is false)
65
- if (full)
66
- this._withNs(key);
67
- const parts = key.split(":");
68
- const prefix = parts[0];
69
- const rest = parts.slice(1).join(":");
70
- let out = [prefix, rest].filter(Boolean);
71
- if (full)
72
- out = [this.namespace, ...out];
73
- return out;
74
- }
75
- /** @inheritdoc */
76
- async set(key, value, options = {}) {
77
- this._assertInitialized();
78
- const { db } = this.options;
79
- const ttl = this._resolveTtl(options);
80
- if (value === undefined)
81
- value = null;
82
- const serialized = JSON.stringify(value);
83
- await db.set(this.#denoKvKey(key), serialized, {
84
- expireIn: ttl ? ttl * 1000 : undefined,
85
- });
86
- return true;
87
- }
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. */
105
- #parseValue(row) {
106
- try {
107
- return JSON.parse(`${row?.value ?? null}`);
108
- }
109
- catch (_err) {
110
- return row?.value;
111
- }
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
- }
213
- /** @inheritdoc */
214
- async get(key) {
215
- this._assertInitialized();
216
- const { db } = this.options;
217
- const row = await db.get(this.#denoKvKey(key));
218
- return this.#parseValue(row);
219
- }
220
- /** @inheritdoc */
221
- async exists(key) {
222
- this._assertInitialized();
223
- const { db } = this.options;
224
- const entry = await db.get(this.#denoKvKey(key));
225
- return entry?.versionstamp !== null && entry?.versionstamp !== undefined;
226
- }
227
- /** @inheritdoc */
228
- async delete(key) {
229
- this._assertInitialized();
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;
240
- }
241
- /** @inheritdoc */
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) {
251
- this._assertInitialized();
252
- const { db } = this.options;
253
- const [firstSeg] = this.#denoKvKey(pattern, false);
254
- const regex = this._globToRegex(pattern);
255
- // Only use the first key segment as a Deno.Kv prefix if it contains
256
- // no wildcards — otherwise scan the whole namespace and regex-filter.
257
- const firstIsLiteral = firstSeg !== undefined && firstSeg !== "*" && !/[*?]/.test(firstSeg);
258
- const listPrefix = firstIsLiteral
259
- ? [this.namespace, firstSeg]
260
- : [this.namespace];
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.
264
- const key = res.key.slice(1).join(":");
265
- if (pattern === "*" || regex.test(key)) {
266
- yield key;
267
- }
268
- }
269
- }
270
- /** @inheritdoc */
271
- async clear(pattern) {
272
- this._assertInitialized();
273
- const { db } = this.options;
274
- let deleteCount = 0;
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++;
283
- deleteCount++;
284
- if (inBatch >= CHUNK) {
285
- await atomic.commit();
286
- atomic = db.atomic();
287
- inBatch = 0;
288
- }
289
- }
290
- if (inBatch > 0)
291
- await atomic.commit();
292
- return deleteCount;
293
- }
294
- /** @inheritdoc */
295
- async setMultiple(entries, options = {}) {
296
- this._assertInitialized();
297
- if (entries.length === 0)
298
- return [];
299
- const normalized = this._normalizePairs(entries);
300
- const { db } = this.options;
301
- // Atomic commit for all-or-nothing semantics.
302
- const atomic = db.atomic();
303
- for (const { key, value, ttl: pairTtl } of normalized) {
304
- const ttl = this._resolveTtl({ ttl: pairTtl ?? options.ttl });
305
- const v = value === undefined ? null : value;
306
- atomic.set(this.#denoKvKey(key), JSON.stringify(v), {
307
- expireIn: ttl ? ttl * 1000 : undefined,
308
- });
309
- }
310
- const res = await atomic.commit();
311
- const ok = !!res?.ok;
312
- return normalized.map(() => ok);
313
- }
314
- /** @inheritdoc */
315
- async getMultiple(keys) {
316
- this._assertInitialized();
317
- const { db } = this.options;
318
- const result = {};
319
- if (keys.length === 0)
320
- return result;
321
- const denoKvKeys = keys.map((k) => this.#denoKvKey(k));
322
- const results = await db.getMany(denoKvKeys);
323
- for (const [index, row] of results.entries()) {
324
- const origKey = keys[index];
325
- const hasValue = row?.versionstamp !== null && row?.versionstamp !== undefined;
326
- result[origKey] = hasValue ? this.#parseValue(row) : null;
327
- }
328
- return result;
329
- }
330
- /** @inheritdoc */
331
- async transaction(operations) {
332
- this._assertInitialized();
333
- const { db } = this.options;
334
- // When the transaction contains only set/delete ops we can use Deno.Kv's
335
- // native atomic() for true all-or-nothing semantics. A `get` inside the
336
- // transaction breaks that — Deno.Kv has no atomic-read — so in that
337
- // case we fall back to sequential execution.
338
- const hasGet = operations.some((op) => op.type === "get");
339
- if (!hasGet && operations.length > 0) {
340
- const atomic = db.atomic();
341
- for (const op of operations) {
342
- if (op.type === "set") {
343
- const ttl = this._resolveTtl(op.options);
344
- const v = op.value === undefined ? null : op.value;
345
- atomic.set(this.#denoKvKey(op.key), JSON.stringify(v), {
346
- expireIn: ttl ? ttl * 1000 : undefined,
347
- });
348
- }
349
- else if (op.type === "delete") {
350
- atomic.delete(this.#denoKvKey(op.key));
351
- }
352
- }
353
- const res = await atomic.commit();
354
- if (!res?.ok) {
355
- throw new Error("Deno.Kv atomic transaction failed to commit");
356
- }
357
- return operations.map(() => true);
358
- }
359
- // Sequential fallback — operations are NOT atomic.
360
- const results = [];
361
- for (const op of operations) {
362
- switch (op.type) {
363
- case "set":
364
- results.push(await this.set(op.key, op.value, op.options || {}));
365
- break;
366
- case "get":
367
- results.push(await this.get(op.key));
368
- break;
369
- case "delete":
370
- results.push(await this.delete(op.key));
371
- break;
372
- }
373
- }
374
- return results;
375
- }
376
- /**
377
- * Not supported in Deno.Kv — always returns `false`.
378
- * @inheritdoc
379
- */
380
- expire(_key, _ttl) {
381
- this._assertInitialized();
382
- return Promise.resolve(false);
383
- }
384
- /**
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.
388
- */
389
- async ttl(key) {
390
- this._assertInitialized();
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" };
395
- }
396
- }