@marianmeres/kv 1.3.2 → 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.
@@ -38,6 +38,7 @@ export class AdapterRedis extends AdapterAbstract {
38
38
  logger: createClog("KV/redis"),
39
39
  db: null, // will be set in constructor via options merge
40
40
  isCluster: false,
41
+ validateKeys: true,
41
42
  };
42
43
  constructor(namespace = "", options = {}) {
43
44
  super();
@@ -51,33 +52,187 @@ export class AdapterRedis extends AdapterAbstract {
51
52
  throw new Error("Missing redis db client instance");
52
53
  }
53
54
  }
55
+ #errorListener;
56
+ #listenerDb;
57
+ #weOpened = false;
54
58
  /** @inheritdoc */
55
59
  async initialize() {
56
60
  const { db, logger } = this.options;
57
- db.on("error", (err) => logger?.error?.(err));
61
+ // avoid stacking listeners across repeated initialize() calls
62
+ // (also handles a hot-swapped db instance, though not a documented path)
63
+ if (this.#errorListener && this.#listenerDb) {
64
+ this.#listenerDb.off?.("error", this.#errorListener);
65
+ }
66
+ this.#errorListener = (err) => logger?.error?.(err);
67
+ this.#listenerDb = db;
68
+ db.on("error", this.#errorListener);
58
69
  // the pool instance doesn't have connect, so being defensive...
59
- if (!db.isOpen)
70
+ if (!db.isOpen) {
60
71
  await db?.connect();
72
+ this.#weOpened = true;
73
+ }
61
74
  this._initialized = true;
62
75
  }
63
76
  /** @inheritdoc */
64
- destroy(_hard) {
77
+ async destroy(_hard) {
65
78
  this._initialized = false;
66
- return Promise.resolve();
79
+ const { db } = this.options;
80
+ if (this.#errorListener && this.#listenerDb) {
81
+ this.#listenerDb.off?.("error", this.#errorListener);
82
+ this.#errorListener = undefined;
83
+ this.#listenerDb = undefined;
84
+ }
85
+ // Only close a connection we opened ourselves — if the caller opened the
86
+ // client before passing it in, they own the lifecycle. `quit` is the
87
+ // graceful path; it is missing on the pool, so be defensive.
88
+ if (this.#weOpened && db?.isOpen) {
89
+ const quit = db.quit ?? db.close;
90
+ if (typeof quit === "function") {
91
+ try {
92
+ await quit.call(db);
93
+ }
94
+ catch {
95
+ // ignore — caller may have already closed it
96
+ }
97
+ }
98
+ this.#weOpened = false;
99
+ }
67
100
  }
68
101
  /** @inheritdoc */
69
102
  async set(key, value, options = {}) {
70
103
  this._assertInitialized();
71
104
  key = this._withNs(key);
72
105
  const { db } = this.options;
73
- const ttl = options.ttl || this.options.defaultTtl || undefined;
106
+ const ttl = this._resolveTtl(options);
74
107
  if (value === undefined)
75
108
  value = null; // redis does not accept undefined
76
109
  value = JSON.stringify(value);
77
- const r = await db.set(key, value, { EX: ttl });
110
+ const r = await db.set(key, value, ttl ? { EX: ttl } : {});
78
111
  return r === "OK";
79
112
  }
80
113
  /** @inheritdoc */
114
+ async setIfAbsent(key, value, options = {}) {
115
+ this._assertInitialized();
116
+ key = this._withNs(key);
117
+ const { db } = this.options;
118
+ const ttl = this._resolveTtl(options);
119
+ if (value === undefined)
120
+ value = null;
121
+ const serialized = JSON.stringify(value);
122
+ const setOptions = { NX: true };
123
+ if (ttl)
124
+ setOptions.EX = ttl;
125
+ const r = await db.set(key, serialized, setOptions);
126
+ return r === "OK";
127
+ }
128
+ // Lua: GET prev, SET new (optionally EX). Returns previous value (nil = missing).
129
+ #GET_SET_SCRIPT = `
130
+ local prev = redis.call('GET', KEYS[1])
131
+ if ARGV[2] == '0' then
132
+ redis.call('SET', KEYS[1], ARGV[1])
133
+ else
134
+ redis.call('SET', KEYS[1], ARGV[1], 'EX', tonumber(ARGV[2]))
135
+ end
136
+ return prev
137
+ `;
138
+ /** @inheritdoc */
139
+ async getSet(key, value, options = {}) {
140
+ this._assertInitialized();
141
+ const nsKey = this._withNs(key);
142
+ const { db } = this.options;
143
+ const ttl = this._resolveTtl(options);
144
+ if (value === undefined)
145
+ value = null;
146
+ const serialized = JSON.stringify(value);
147
+ const prev = await db.eval(this.#GET_SET_SCRIPT, {
148
+ keys: [nsKey],
149
+ arguments: [serialized, String(ttl ?? 0)],
150
+ });
151
+ if (prev === null || prev === undefined)
152
+ return null;
153
+ try {
154
+ return JSON.parse(`${prev}`);
155
+ }
156
+ catch {
157
+ return prev;
158
+ }
159
+ }
160
+ // Lua: conditional EXPIRE only when the key is newly created by INCRBY.
161
+ #INCR_SCRIPT = `
162
+ local existed = redis.call('EXISTS', KEYS[1]) == 1
163
+ if not existed then
164
+ redis.call('SET', KEYS[1], '0')
165
+ end
166
+ local v = redis.call('INCRBY', KEYS[1], ARGV[1])
167
+ if not existed and tonumber(ARGV[2]) > 0 then
168
+ redis.call('EXPIRE', KEYS[1], tonumber(ARGV[2]))
169
+ end
170
+ return v
171
+ `;
172
+ async #incrBy(key, delta, options = {}) {
173
+ this._assertInitialized();
174
+ const nsKey = this._withNs(key);
175
+ const { db } = this.options;
176
+ const ttl = this._resolveTtl(options);
177
+ // Validate *before* the INCRBY: if the key holds a JSON non-number
178
+ // (e.g. `"foo"`), INCRBY would reject with "not an integer" anyway,
179
+ // but a stored JSON number like `1` is `"1"` in Redis — compatible.
180
+ // Booleans / objects get rejected downstream with a Redis error.
181
+ try {
182
+ const result = await db.eval(this.#INCR_SCRIPT, {
183
+ keys: [nsKey],
184
+ arguments: [String(delta), String(ttl ?? 0)],
185
+ });
186
+ return Number(result);
187
+ }
188
+ catch (err) {
189
+ const msg = `${err?.message ?? err}`;
190
+ if (/not an integer|is not a number/i.test(msg)) {
191
+ throw new TypeError("KV value is not a number");
192
+ }
193
+ throw err;
194
+ }
195
+ }
196
+ /** @inheritdoc */
197
+ incr(key, by = 1, options = {}) {
198
+ return this.#incrBy(key, by, options);
199
+ }
200
+ /** @inheritdoc */
201
+ decr(key, by = 1, options = {}) {
202
+ return this.#incrBy(key, -by, options);
203
+ }
204
+ // Lua: compare current (stringified) value to expected; swap on match.
205
+ // Returns 1 on swap, 0 otherwise. Missing key → 0 (GET returns nil which
206
+ // never equals a non-empty expected string).
207
+ #CAS_SCRIPT = `
208
+ local current = redis.call('GET', KEYS[1])
209
+ if current == ARGV[1] then
210
+ if ARGV[3] == '0' then
211
+ redis.call('SET', KEYS[1], ARGV[2])
212
+ else
213
+ redis.call('SET', KEYS[1], ARGV[2], 'EX', tonumber(ARGV[3]))
214
+ end
215
+ return 1
216
+ end
217
+ return 0
218
+ `;
219
+ /** @inheritdoc */
220
+ async cas(key, expected, next, options = {}) {
221
+ this._assertInitialized();
222
+ const nsKey = this._withNs(key);
223
+ const { db } = this.options;
224
+ const ttl = this._resolveTtl(options);
225
+ if (next === undefined)
226
+ next = null;
227
+ const expectedSerialized = JSON.stringify(expected === undefined ? null : expected);
228
+ const nextSerialized = JSON.stringify(next);
229
+ const r = await db.eval(this.#CAS_SCRIPT, {
230
+ keys: [nsKey],
231
+ arguments: [expectedSerialized, nextSerialized, String(ttl ?? 0)],
232
+ });
233
+ return Number(r) === 1;
234
+ }
235
+ /** @inheritdoc */
81
236
  async get(key) {
82
237
  this._assertInitialized();
83
238
  key = this._withNs(key);
@@ -109,13 +264,23 @@ export class AdapterRedis extends AdapterAbstract {
109
264
  /** @inheritdoc */
110
265
  async keys(pattern) {
111
266
  this._assertInitialized();
112
- const { db, isCluster } = this.options;
267
+ const { isCluster } = this.options;
113
268
  if (isCluster) {
114
269
  throw new Error("keys() is not supported in Redis Cluster mode");
115
270
  }
116
- // Use SCAN instead of KEYS for non-blocking iteration
271
+ const out = [];
272
+ for await (const k of this.keysIter(pattern))
273
+ out.push(k);
274
+ return out.toSorted();
275
+ }
276
+ /** @inheritdoc */
277
+ async *keysIter(pattern) {
278
+ this._assertInitialized();
279
+ const { db, isCluster } = this.options;
280
+ if (isCluster) {
281
+ throw new Error("keysIter() is not supported in Redis Cluster mode");
282
+ }
117
283
  const fullPattern = this.namespace + pattern;
118
- const keys = [];
119
284
  let cursor = "0";
120
285
  do {
121
286
  const result = await db.scan(cursor, {
@@ -123,16 +288,10 @@ export class AdapterRedis extends AdapterAbstract {
123
288
  COUNT: 100,
124
289
  });
125
290
  cursor = `${result.cursor}`;
126
- keys.push(...result.keys.map((k) => String(k)));
291
+ for (const k of result.keys) {
292
+ yield this._withoutNs(String(k));
293
+ }
127
294
  } while (cursor !== "0");
128
- return keys
129
- .map((k) => {
130
- // strip namespace if exists
131
- if (this.namespace)
132
- k = k.slice(this.namespace.length);
133
- return k;
134
- })
135
- .toSorted();
136
295
  }
137
296
  /** @inheritdoc */
138
297
  async clear(pattern) {
@@ -148,14 +307,14 @@ export class AdapterRedis extends AdapterAbstract {
148
307
  return Number(await db.unlink(keys.map((k) => this._withNs(k))));
149
308
  }
150
309
  /** @inheritdoc */
151
- async setMultiple(keyValuePairs, options = {}) {
310
+ async setMultiple(entries, options = {}) {
152
311
  this._assertInitialized();
153
312
  const { db } = this.options;
154
- const ttl = options.ttl || this.options.defaultTtl || undefined;
313
+ const normalized = this._normalizePairs(entries);
155
314
  const pipeline = db.multi();
156
- for (let [key, value] of keyValuePairs) {
157
- key = this._withNs(key);
158
- pipeline.set(key, JSON.stringify(value), { EX: ttl });
315
+ for (const { key, value, ttl: pairTtl } of normalized) {
316
+ const ttl = this._resolveTtl({ ttl: pairTtl ?? options.ttl });
317
+ pipeline.set(this._withNs(key), JSON.stringify(value === undefined ? null : value), ttl ? { EX: ttl } : {});
159
318
  }
160
319
  const res = await pipeline.exec();
161
320
  return res.map((v) => String(v) === "OK");
@@ -164,22 +323,21 @@ export class AdapterRedis extends AdapterAbstract {
164
323
  async getMultiple(keys) {
165
324
  this._assertInitialized();
166
325
  const { db } = this.options;
167
- keys = keys.map((k) => this._withNs(k));
168
- const values = await db.mGet(keys);
326
+ const nsKeys = keys.map((k) => this._withNs(k));
327
+ const values = await db.mGet(nsKeys);
169
328
  const result = {};
170
- keys.forEach((key, index) => {
171
- key = this._withoutNs(key);
329
+ keys.forEach((origKey, index) => {
172
330
  const value = values[index];
173
331
  if (value !== null) {
174
332
  try {
175
- result[key] = JSON.parse(`${value}`);
333
+ result[origKey] = JSON.parse(`${value}`);
176
334
  }
177
335
  catch (_err) {
178
- result[key] = value;
336
+ result[origKey] = value;
179
337
  }
180
338
  }
181
339
  else {
182
- result[key] = null;
340
+ result[origKey] = null;
183
341
  }
184
342
  });
185
343
  return result;
@@ -197,12 +355,15 @@ export class AdapterRedis extends AdapterAbstract {
197
355
  const ttl = await this.options.db.ttl(key);
198
356
  // Key doesn't exist
199
357
  if (ttl === -2)
200
- return false;
358
+ return { state: "missing" };
201
359
  // No expiration set
202
360
  if (ttl === -1)
203
- return null;
361
+ return { state: "no-ttl" };
204
362
  // Positive number: TTL in seconds remaining
205
- return new Date(Date.now() + parseInt(`${ttl}`) * 1_000);
363
+ return {
364
+ state: "expires",
365
+ at: new Date(Date.now() + parseInt(`${ttl}`) * 1_000),
366
+ };
206
367
  }
207
368
  /** @inheritdoc */
208
369
  async transaction(operations) {
@@ -212,9 +373,12 @@ export class AdapterRedis extends AdapterAbstract {
212
373
  for (const op of operations) {
213
374
  const key = this._withNs(op.key);
214
375
  switch (op.type) {
215
- case "set":
216
- multi.set(key, JSON.stringify(op.value));
376
+ case "set": {
377
+ const ttl = this._resolveTtl(op.options);
378
+ const val = op.value === undefined ? null : op.value;
379
+ multi.set(key, JSON.stringify(val), ttl ? { EX: ttl } : {});
217
380
  break;
381
+ }
218
382
  case "get":
219
383
  multi.get(key);
220
384
  break;
@@ -223,7 +387,7 @@ export class AdapterRedis extends AdapterAbstract {
223
387
  break;
224
388
  }
225
389
  }
226
- const res = await multi.exec();
390
+ const res = (await multi.exec());
227
391
  // fix results types
228
392
  for (const [i, op] of operations.entries()) {
229
393
  switch (op.type) {
@@ -250,13 +414,22 @@ export class AdapterRedis extends AdapterAbstract {
250
414
  async __debug_dump() {
251
415
  this._assertInitialized();
252
416
  const { db } = this.options;
253
- const keys = (await db.keys("*")).toSorted();
417
+ // SCAN scoped to this namespace — do not touch foreign tenants
418
+ const match = this.namespace + "*";
419
+ const nsKeys = [];
420
+ let cursor = "0";
421
+ do {
422
+ const r = await db.scan(cursor, { MATCH: match, COUNT: 500 });
423
+ cursor = `${r.cursor}`;
424
+ nsKeys.push(...r.keys.map((k) => String(k)));
425
+ } while (cursor !== "0");
426
+ const keys = nsKeys.map((k) => this._withoutNs(k)).toSorted();
254
427
  const out = {};
255
- for (const _key of keys) {
256
- const key = this._withoutNs(String(_key));
428
+ for (const key of keys) {
429
+ const t = await this.ttl(key);
257
430
  out[key] = {
258
431
  value: await this.get(key),
259
- ttl: await this.ttl(key),
432
+ ttl: t.state === "expires" ? t.at : null,
260
433
  };
261
434
  }
262
435
  return out;
package/dist/kv.d.ts CHANGED
@@ -10,8 +10,8 @@ import { AdapterDenoKv, type AdapterDenoKvOptions } from "./adapter/deno-kv.js";
10
10
  import { AdapterMemory, type AdapterMemoryOptions } from "./adapter/memory.js";
11
11
  import { AdapterPostgres, type AdapterPostgresOptions } from "./adapter/postgres.js";
12
12
  import { AdapterRedis, type AdapterRedisOptions } from "./adapter/redis.js";
13
- export type { SetOptions, AdapterInfo, AdapterAbstractOptions, Operation } from "./adapter/abstract.js";
14
- export { AdapterAbstract } from "./adapter/abstract.js";
13
+ export type { SetOptions, AdapterInfo, AdapterAbstractOptions, Operation, TtlResult, SetMultipleEntry, } from "./adapter/abstract.js";
14
+ export { AdapterAbstract, KvRaceError } from "./adapter/abstract.js";
15
15
  export { AdapterMemory, type AdapterMemoryOptions } from "./adapter/memory.js";
16
16
  export { AdapterRedis, type AdapterRedisOptions } from "./adapter/redis.js";
17
17
  export { AdapterPostgres, type AdapterPostgresOptions } from "./adapter/postgres.js";
package/dist/kv.js CHANGED
@@ -10,7 +10,7 @@ import { AdapterDenoKv } from "./adapter/deno-kv.js";
10
10
  import { AdapterMemory } from "./adapter/memory.js";
11
11
  import { AdapterPostgres, } from "./adapter/postgres.js";
12
12
  import { AdapterRedis } from "./adapter/redis.js";
13
- export { AdapterAbstract } from "./adapter/abstract.js";
13
+ export { AdapterAbstract, KvRaceError } from "./adapter/abstract.js";
14
14
  export { AdapterMemory } from "./adapter/memory.js";
15
15
  export { AdapterRedis } from "./adapter/redis.js";
16
16
  export { AdapterPostgres } from "./adapter/postgres.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marianmeres/kv",
3
- "version": "1.3.2",
3
+ "version": "2.2.0",
4
4
  "type": "module",
5
5
  "main": "dist/mod.js",
6
6
  "types": "dist/mod.d.ts",
@@ -10,14 +10,23 @@
10
10
  "import": "./dist/mod.js"
11
11
  }
12
12
  },
13
+ "files": [
14
+ "dist",
15
+ "LICENSE",
16
+ "README.md",
17
+ "API.md",
18
+ "AGENTS.md",
19
+ "CLAUDE.md",
20
+ "docs"
21
+ ],
13
22
  "author": "Marian Meres",
14
23
  "license": "MIT",
15
24
  "dependencies": {
16
- "@marianmeres/clog": "^3.15.2",
17
- "@types/pg": "^8.16.0",
25
+ "@marianmeres/clog": "^3.17.0",
26
+ "@types/pg": "^8.20.0",
18
27
  "@types/redis": "^4.0.10",
19
- "pg": "^8.18.0",
20
- "redis": "^5.10.0"
28
+ "pg": "^8.20.0",
29
+ "redis": "^5.12.1"
21
30
  },
22
31
  "repository": {
23
32
  "type": "git",