@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.
@@ -10,30 +10,6 @@ import { createClog } from "@marianmeres/clog";
10
10
  *
11
11
  * Provides persistent key-value storage using PostgreSQL with JSONB values.
12
12
  * Automatically creates the required table and indexes on initialization.
13
- *
14
- * @remarks
15
- * - Uses UPSERT (INSERT ... ON CONFLICT) for atomic set operations
16
- * - Uses PostgreSQL transactions for the `transaction()` method — when `db`
17
- * is a `pg.Pool`, a single client is checked out for the duration of the
18
- * transaction so BEGIN/COMMIT/ROLLBACK and all contained queries run on
19
- * the same physical connection
20
- * - Values are stored as JSONB for efficient querying
21
- * - Supports automatic TTL cleanup via background timer
22
- * - Table schema: key (VARCHAR), value (JSONB), expires_at, created_at, updated_at
23
- *
24
- * @example
25
- * ```typescript
26
- * import pg from 'pg';
27
- *
28
- * const pool = new pg.Pool({ connectionString: 'postgres://...' });
29
- * const client = createKVClient("myapp:", "postgres", {
30
- * db: pool,
31
- * tableName: "kv_store",
32
- * ttlCleanupIntervalSec: 300, // Clean expired keys every 5 minutes
33
- * });
34
- * await client.initialize();
35
- * await client.set("config:theme", { dark: true });
36
- * ```
37
13
  */
38
14
  export class AdapterPostgres extends AdapterAbstract {
39
15
  namespace;
@@ -44,6 +20,7 @@ export class AdapterPostgres extends AdapterAbstract {
44
20
  db: null, // will be set in constructor via options merge
45
21
  tableName: "__kv",
46
22
  ttlCleanupIntervalSec: 0,
23
+ validateKeys: true,
47
24
  };
48
25
  #cleanupTimer;
49
26
  constructor(namespace = "", options = {}) {
@@ -120,7 +97,7 @@ export class AdapterPostgres extends AdapterAbstract {
120
97
  /**
121
98
  * Convert Redis-style glob to a PostgreSQL LIKE pattern.
122
99
  * Literal `%`, `_`, and `\` are escaped with `\`; `*`/`?` become `%`/`_`.
123
- * LIKE queries using this output must include `ESCAPE '\'` — see {@link #likeEscapeClause}.
100
+ * LIKE queries using this output must include `ESCAPE '\'`.
124
101
  */
125
102
  #likePattern(pattern) {
126
103
  return pattern
@@ -145,7 +122,6 @@ export class AdapterPostgres extends AdapterAbstract {
145
122
  const { tableName } = this.options;
146
123
  const ttl = this._resolveTtl(options);
147
124
  const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
148
- // a.k.a. UPSERT
149
125
  await exec.query(`INSERT INTO ${tableName} (key, value, expires_at, updated_at)
150
126
  VALUES ($1, $2, $3, NOW())
151
127
  ON CONFLICT (key) DO UPDATE SET
@@ -155,6 +131,118 @@ export class AdapterPostgres extends AdapterAbstract {
155
131
  return true;
156
132
  }
157
133
  /** @inheritdoc */
134
+ async setIfAbsent(key, value, options = {}) {
135
+ this._assertInitialized();
136
+ const nsKey = this._withNs(key);
137
+ const { db, tableName } = this.options;
138
+ const ttl = this._resolveTtl(options);
139
+ const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
140
+ // INSERT on new keys; UPDATE only when the existing row is expired.
141
+ // (Live keys stay untouched — the hallmark of setIfAbsent.)
142
+ const { rowCount } = await db.query(`INSERT INTO ${tableName} (key, value, expires_at, updated_at)
143
+ VALUES ($1, $2, $3, NOW())
144
+ ON CONFLICT (key) DO UPDATE SET
145
+ value = EXCLUDED.value,
146
+ expires_at = EXCLUDED.expires_at,
147
+ updated_at = NOW()
148
+ WHERE ${tableName}.expires_at IS NOT NULL AND ${tableName}.expires_at <= NOW()`, [nsKey, JSON.stringify(value ?? null), expiresAt]);
149
+ return (rowCount ?? 0) > 0;
150
+ }
151
+ /** @inheritdoc */
152
+ async getSet(key, value, options = {}) {
153
+ this._assertInitialized();
154
+ const nsKey = this._withNs(key);
155
+ const { db, tableName } = this.options;
156
+ const ttl = this._resolveTtl(options);
157
+ const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
158
+ // CTE captures pre-write state; UPSERT writes; RETURNING surfaces the prev.
159
+ const { rows } = await db.query(`WITH prev AS (
160
+ SELECT value FROM ${tableName}
161
+ WHERE key = $1 AND (expires_at IS NULL OR expires_at > NOW())
162
+ ), upserted AS (
163
+ INSERT INTO ${tableName} (key, value, expires_at, updated_at)
164
+ VALUES ($1, $2, $3, NOW())
165
+ ON CONFLICT (key) DO UPDATE SET
166
+ value = EXCLUDED.value,
167
+ expires_at = EXCLUDED.expires_at,
168
+ updated_at = NOW()
169
+ RETURNING 1
170
+ )
171
+ SELECT (SELECT value FROM prev) AS prev`, [nsKey, JSON.stringify(value ?? null), expiresAt]);
172
+ return rows[0]?.prev ?? null;
173
+ }
174
+ async #incrBy(key, delta, options = {}) {
175
+ this._assertInitialized();
176
+ const nsKey = this._withNs(key);
177
+ const { db, tableName } = this.options;
178
+ const ttl = this._resolveTtl(options);
179
+ const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
180
+ // - New key OR expired key: value = delta, expires_at = $ttl
181
+ // - Live key: value = old + delta, preserve existing expires_at
182
+ // The nested cast `value::text::numeric` throws 22P02 when the stored
183
+ // value is not a JSON number — we translate that to TypeError.
184
+ try {
185
+ const { rows } = await db.query(`INSERT INTO ${tableName} (key, value, expires_at, updated_at)
186
+ VALUES ($1, to_jsonb($2::numeric), $3, NOW())
187
+ ON CONFLICT (key) DO UPDATE SET
188
+ value = CASE
189
+ WHEN ${tableName}.expires_at IS NOT NULL AND ${tableName}.expires_at <= NOW()
190
+ THEN to_jsonb($2::numeric)
191
+ ELSE to_jsonb(${tableName}.value::text::numeric + $2::numeric)
192
+ END,
193
+ expires_at = CASE
194
+ WHEN ${tableName}.expires_at IS NOT NULL AND ${tableName}.expires_at <= NOW()
195
+ THEN EXCLUDED.expires_at
196
+ ELSE ${tableName}.expires_at
197
+ END,
198
+ updated_at = NOW()
199
+ RETURNING value`, [nsKey, delta, expiresAt]);
200
+ return Number(rows[0].value);
201
+ }
202
+ catch (err) {
203
+ if (err?.code === "22P02" ||
204
+ /invalid input syntax for type numeric/i.test(err?.message ?? "")) {
205
+ throw new TypeError("KV value is not a number");
206
+ }
207
+ throw err;
208
+ }
209
+ }
210
+ /** @inheritdoc */
211
+ incr(key, by = 1, options = {}) {
212
+ return this.#incrBy(key, by, options);
213
+ }
214
+ /** @inheritdoc */
215
+ decr(key, by = 1, options = {}) {
216
+ return this.#incrBy(key, -by, options);
217
+ }
218
+ /** @inheritdoc */
219
+ async cas(key, expected, next, options = {}) {
220
+ this._assertInitialized();
221
+ const nsKey = this._withNs(key);
222
+ const { db, tableName } = this.options;
223
+ const hasTtl = options.ttl !== undefined;
224
+ const ttl = hasTtl ? this._resolveTtl(options) : undefined;
225
+ const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
226
+ const expectedJson = JSON.stringify(expected ?? null);
227
+ const nextJson = JSON.stringify(next ?? null);
228
+ const sql = hasTtl
229
+ ? `UPDATE ${tableName}
230
+ SET value = $2::jsonb, expires_at = $4, updated_at = NOW()
231
+ WHERE key = $1
232
+ AND value = $3::jsonb
233
+ AND (expires_at IS NULL OR expires_at > NOW())`
234
+ : `UPDATE ${tableName}
235
+ SET value = $2::jsonb, updated_at = NOW()
236
+ WHERE key = $1
237
+ AND value = $3::jsonb
238
+ AND (expires_at IS NULL OR expires_at > NOW())`;
239
+ const params = [nsKey, nextJson, expectedJson];
240
+ if (hasTtl)
241
+ params.push(expiresAt);
242
+ const { rowCount } = await db.query(sql, params);
243
+ return (rowCount ?? 0) > 0;
244
+ }
245
+ /** @inheritdoc */
158
246
  get(key) {
159
247
  return this.#getOn(this.options.db, key);
160
248
  }
@@ -197,9 +285,56 @@ export class AdapterPostgres extends AdapterAbstract {
197
285
  WHERE key LIKE $1${this.#likeEscape}
198
286
  AND (expires_at IS NULL OR expires_at > NOW())
199
287
  ORDER BY key`, [this.#withNsLike(pattern)]);
200
- return rows
201
- .map((row) => this._withoutNs(row.key))
202
- .toSorted();
288
+ return rows.map((row) => this._withoutNs(row.key)).toSorted();
289
+ }
290
+ /** @inheritdoc */
291
+ async *keysIter(pattern) {
292
+ this._assertInitialized();
293
+ const { tableName } = this.options;
294
+ const { client, release } = await this.#acquireClient();
295
+ // Use a per-call cursor name so multiple iterators on the same PG
296
+ // client can't collide. `toString(36)` only emits [0-9a-z].
297
+ const cursorName = `kv_iter_${Math.random().toString(36).slice(2)}`;
298
+ let inTxn = false;
299
+ try {
300
+ await client.query("BEGIN");
301
+ inTxn = true;
302
+ await client.query(`DECLARE ${cursorName} NO SCROLL CURSOR FOR
303
+ SELECT key FROM ${tableName}
304
+ WHERE key LIKE $1${this.#likeEscape}
305
+ AND (expires_at IS NULL OR expires_at > NOW())
306
+ ORDER BY key`, [this.#withNsLike(pattern)]);
307
+ while (true) {
308
+ const { rows } = await client.query(`FETCH 500 FROM ${cursorName}`);
309
+ if (rows.length === 0)
310
+ break;
311
+ for (const row of rows) {
312
+ yield this._withoutNs(row.key);
313
+ }
314
+ }
315
+ }
316
+ finally {
317
+ if (inTxn) {
318
+ try {
319
+ await client.query(`CLOSE ${cursorName}`);
320
+ }
321
+ catch {
322
+ // cursor may already be gone if the txn aborted
323
+ }
324
+ try {
325
+ await client.query("COMMIT");
326
+ }
327
+ catch {
328
+ try {
329
+ await client.query("ROLLBACK");
330
+ }
331
+ catch {
332
+ // ignore — caller will see the original error
333
+ }
334
+ }
335
+ }
336
+ release();
337
+ }
203
338
  }
204
339
  /** @inheritdoc */
205
340
  async clear(pattern) {
@@ -220,31 +355,31 @@ export class AdapterPostgres extends AdapterAbstract {
220
355
  return totalDeleted;
221
356
  }
222
357
  /** @inheritdoc */
223
- async setMultiple(keyValuePairs, options = {}) {
358
+ async setMultiple(entries, options = {}) {
224
359
  this._assertInitialized();
225
- if (keyValuePairs.length === 0)
360
+ if (entries.length === 0)
226
361
  return [];
362
+ const normalized = this._normalizePairs(entries);
227
363
  const { db, tableName } = this.options;
228
- const ttl = this._resolveTtl(options);
229
- const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
230
- const placeholders = keyValuePairs
231
- .map((_, i) => `($${i * 3 + 1}, $${i * 3 + 2}, $${i * 3 + 3})`)
232
- .join(", ");
364
+ const placeholders = [];
233
365
  const params = [];
234
- for (const [k, v] of keyValuePairs) {
235
- params.push(this._withNs(k), JSON.stringify(v ?? null), expiresAt);
366
+ let idx = 1;
367
+ for (const { key, value, ttl: pairTtl } of normalized) {
368
+ const ttl = this._resolveTtl({ ttl: pairTtl ?? options.ttl });
369
+ const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
370
+ placeholders.push(`($${idx++}, $${idx++}, $${idx++})`);
371
+ params.push(this._withNs(key), JSON.stringify(value ?? null), expiresAt);
236
372
  }
237
- // a.k.a UPSERT
238
373
  const sql = `
239
374
  INSERT INTO ${tableName} (key, value, expires_at)
240
- VALUES ${placeholders}
375
+ VALUES ${placeholders.join(", ")}
241
376
  ON CONFLICT (key) DO UPDATE SET
242
377
  value = EXCLUDED.value,
243
378
  expires_at = EXCLUDED.expires_at,
244
379
  updated_at = NOW()
245
380
  `;
246
381
  await db.query(sql, params);
247
- return keyValuePairs.map(() => true);
382
+ return normalized.map(() => true);
248
383
  }
249
384
  /** @inheritdoc */
250
385
  async getMultiple(keys) {
@@ -288,25 +423,22 @@ export class AdapterPostgres extends AdapterAbstract {
288
423
  key = this._withNs(key);
289
424
  const { db, tableName } = this.options;
290
425
  const { rows } = await db.query(`SELECT expires_at FROM ${tableName} WHERE key = $1`, [key]);
291
- // Key doesn't exist
292
426
  if (rows.length === 0)
293
- return false;
427
+ return { state: "missing" };
294
428
  const expiresAt = rows[0].expires_at;
295
- // No expiration set
296
429
  if (!expiresAt)
297
- return null;
298
- return new Date(expiresAt);
430
+ return { state: "no-ttl" };
431
+ // expired-but-not-yet-cleaned counts as missing (matches get() filter)
432
+ const at = new Date(expiresAt);
433
+ if (at.valueOf() <= Date.now())
434
+ return { state: "missing" };
435
+ return { state: "expires", at };
299
436
  }
300
437
  /**
301
438
  * Acquire a single pinned connection for a transaction.
302
- *
303
- * If `db` is a `pg.Pool`, a client is checked out and a `release` callback
304
- * is returned. If `db` is already a `pg.Client`, it is used directly and
305
- * `release` is a no-op.
306
439
  */
307
440
  async #acquireClient() {
308
441
  const { db } = this.options;
309
- // pg.Pool exposes `totalCount`; pg.Client does not.
310
442
  if (typeof db.totalCount === "number" && typeof db.connect === "function") {
311
443
  const client = await db.connect();
312
444
  return { client, release: () => client.release() };
@@ -342,12 +474,8 @@ export class AdapterPostgres extends AdapterAbstract {
342
474
  await client.query("ROLLBACK");
343
475
  }
344
476
  catch (rollbackErr) {
345
- // Rollback failure is a real problem — surface it even though
346
- // we re-throw the original error below.
347
477
  logger?.error?.(`Rollback failed: ${rollbackErr}`);
348
478
  }
349
- // Do NOT log `err` here — we're re-throwing it; the caller will
350
- // see it. Double-logging is just noise.
351
479
  throw err;
352
480
  }
353
481
  }
@@ -363,7 +491,7 @@ export class AdapterPostgres extends AdapterAbstract {
363
491
  return rows.reduce((m, row) => {
364
492
  m[this._withoutNs(row.key)] = {
365
493
  value: row.value,
366
- ttl: row.expires_at,
494
+ ttl: row.expires_at ? new Date(row.expires_at) : null,
367
495
  };
368
496
  return m;
369
497
  }, {});
@@ -4,7 +4,7 @@
4
4
  * Redis key-value storage adapter implementation.
5
5
  */
6
6
  import type { createClient, createClientPool } from "redis";
7
- import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetOptions } from "./abstract.js";
7
+ import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult } from "./abstract.js";
8
8
  /**
9
9
  * Configuration options for the Redis KV adapter.
10
10
  */
@@ -58,6 +58,16 @@ export declare class AdapterRedis extends AdapterAbstract {
58
58
  /** @inheritdoc */
59
59
  set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
60
60
  /** @inheritdoc */
61
+ setIfAbsent(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
62
+ /** @inheritdoc */
63
+ getSet(key: string, value: any, options?: Partial<SetOptions>): Promise<any>;
64
+ /** @inheritdoc */
65
+ incr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>;
66
+ /** @inheritdoc */
67
+ decr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>;
68
+ /** @inheritdoc */
69
+ cas(key: string, expected: any, next: any, options?: Partial<SetOptions>): Promise<boolean>;
70
+ /** @inheritdoc */
61
71
  get(key: string): Promise<any>;
62
72
  /** @inheritdoc */
63
73
  delete(key: string): Promise<boolean>;
@@ -66,19 +76,21 @@ export declare class AdapterRedis extends AdapterAbstract {
66
76
  /** @inheritdoc */
67
77
  keys(pattern: string): Promise<string[]>;
68
78
  /** @inheritdoc */
79
+ keysIter(pattern: string): AsyncIterable<string>;
80
+ /** @inheritdoc */
69
81
  clear(pattern: string): Promise<number>;
70
82
  /** @inheritdoc */
71
- setMultiple(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<boolean[]>;
83
+ setMultiple(entries: readonly SetMultipleEntry[], options?: Partial<SetOptions>): Promise<boolean[]>;
72
84
  /** @inheritdoc */
73
85
  getMultiple(keys: string[]): Promise<Record<string, any>>;
74
86
  /** @inheritdoc */
75
87
  expire(key: string, ttl: number): Promise<boolean>;
76
88
  /** @inheritdoc */
77
- ttl(key: string): Promise<Date | null | false>;
89
+ ttl(key: string): Promise<TtlResult>;
78
90
  /** @inheritdoc */
79
91
  transaction(operations: Operation[]): Promise<any[]>;
80
92
  __debug_dump(): Promise<Record<string, {
81
93
  value: any;
82
- ttl: Date | null | false;
94
+ ttl: Date | null;
83
95
  }>>;
84
96
  }
@@ -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();
@@ -52,15 +53,18 @@ export class AdapterRedis extends AdapterAbstract {
52
53
  }
53
54
  }
54
55
  #errorListener;
56
+ #listenerDb;
55
57
  #weOpened = false;
56
58
  /** @inheritdoc */
57
59
  async initialize() {
58
60
  const { db, logger } = this.options;
59
61
  // avoid stacking listeners across repeated initialize() calls
60
- if (this.#errorListener) {
61
- db.off?.("error", this.#errorListener);
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);
62
65
  }
63
66
  this.#errorListener = (err) => logger?.error?.(err);
67
+ this.#listenerDb = db;
64
68
  db.on("error", this.#errorListener);
65
69
  // the pool instance doesn't have connect, so being defensive...
66
70
  if (!db.isOpen) {
@@ -73,9 +77,10 @@ export class AdapterRedis extends AdapterAbstract {
73
77
  async destroy(_hard) {
74
78
  this._initialized = false;
75
79
  const { db } = this.options;
76
- if (this.#errorListener) {
77
- db.off?.("error", this.#errorListener);
80
+ if (this.#errorListener && this.#listenerDb) {
81
+ this.#listenerDb.off?.("error", this.#errorListener);
78
82
  this.#errorListener = undefined;
83
+ this.#listenerDb = undefined;
79
84
  }
80
85
  // Only close a connection we opened ourselves — if the caller opened the
81
86
  // client before passing it in, they own the lifecycle. `quit` is the
@@ -106,6 +111,128 @@ export class AdapterRedis extends AdapterAbstract {
106
111
  return r === "OK";
107
112
  }
108
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 */
109
236
  async get(key) {
110
237
  this._assertInitialized();
111
238
  key = this._withNs(key);
@@ -137,13 +264,23 @@ export class AdapterRedis extends AdapterAbstract {
137
264
  /** @inheritdoc */
138
265
  async keys(pattern) {
139
266
  this._assertInitialized();
140
- const { db, isCluster } = this.options;
267
+ const { isCluster } = this.options;
141
268
  if (isCluster) {
142
269
  throw new Error("keys() is not supported in Redis Cluster mode");
143
270
  }
144
- // 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
+ }
145
283
  const fullPattern = this.namespace + pattern;
146
- const keys = [];
147
284
  let cursor = "0";
148
285
  do {
149
286
  const result = await db.scan(cursor, {
@@ -151,16 +288,10 @@ export class AdapterRedis extends AdapterAbstract {
151
288
  COUNT: 100,
152
289
  });
153
290
  cursor = `${result.cursor}`;
154
- keys.push(...result.keys.map((k) => String(k)));
291
+ for (const k of result.keys) {
292
+ yield this._withoutNs(String(k));
293
+ }
155
294
  } while (cursor !== "0");
156
- return keys
157
- .map((k) => {
158
- // strip namespace if exists
159
- if (this.namespace)
160
- k = k.slice(this.namespace.length);
161
- return k;
162
- })
163
- .toSorted();
164
295
  }
165
296
  /** @inheritdoc */
166
297
  async clear(pattern) {
@@ -176,14 +307,14 @@ export class AdapterRedis extends AdapterAbstract {
176
307
  return Number(await db.unlink(keys.map((k) => this._withNs(k))));
177
308
  }
178
309
  /** @inheritdoc */
179
- async setMultiple(keyValuePairs, options = {}) {
310
+ async setMultiple(entries, options = {}) {
180
311
  this._assertInitialized();
181
312
  const { db } = this.options;
182
- const ttl = this._resolveTtl(options);
313
+ const normalized = this._normalizePairs(entries);
183
314
  const pipeline = db.multi();
184
- for (let [key, value] of keyValuePairs) {
185
- key = this._withNs(key);
186
- pipeline.set(key, JSON.stringify(value), ttl ? { 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 } : {});
187
318
  }
188
319
  const res = await pipeline.exec();
189
320
  return res.map((v) => String(v) === "OK");
@@ -192,22 +323,21 @@ export class AdapterRedis extends AdapterAbstract {
192
323
  async getMultiple(keys) {
193
324
  this._assertInitialized();
194
325
  const { db } = this.options;
195
- keys = keys.map((k) => this._withNs(k));
196
- const values = await db.mGet(keys);
326
+ const nsKeys = keys.map((k) => this._withNs(k));
327
+ const values = await db.mGet(nsKeys);
197
328
  const result = {};
198
- keys.forEach((key, index) => {
199
- key = this._withoutNs(key);
329
+ keys.forEach((origKey, index) => {
200
330
  const value = values[index];
201
331
  if (value !== null) {
202
332
  try {
203
- result[key] = JSON.parse(`${value}`);
333
+ result[origKey] = JSON.parse(`${value}`);
204
334
  }
205
335
  catch (_err) {
206
- result[key] = value;
336
+ result[origKey] = value;
207
337
  }
208
338
  }
209
339
  else {
210
- result[key] = null;
340
+ result[origKey] = null;
211
341
  }
212
342
  });
213
343
  return result;
@@ -225,12 +355,15 @@ export class AdapterRedis extends AdapterAbstract {
225
355
  const ttl = await this.options.db.ttl(key);
226
356
  // Key doesn't exist
227
357
  if (ttl === -2)
228
- return false;
358
+ return { state: "missing" };
229
359
  // No expiration set
230
360
  if (ttl === -1)
231
- return null;
361
+ return { state: "no-ttl" };
232
362
  // Positive number: TTL in seconds remaining
233
- 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
+ };
234
367
  }
235
368
  /** @inheritdoc */
236
369
  async transaction(operations) {
@@ -254,7 +387,7 @@ export class AdapterRedis extends AdapterAbstract {
254
387
  break;
255
388
  }
256
389
  }
257
- const res = await multi.exec();
390
+ const res = (await multi.exec());
258
391
  // fix results types
259
392
  for (const [i, op] of operations.entries()) {
260
393
  switch (op.type) {
@@ -293,9 +426,10 @@ export class AdapterRedis extends AdapterAbstract {
293
426
  const keys = nsKeys.map((k) => this._withoutNs(k)).toSorted();
294
427
  const out = {};
295
428
  for (const key of keys) {
429
+ const t = await this.ttl(key);
296
430
  out[key] = {
297
431
  value: await this.get(key),
298
- ttl: await this.ttl(key),
432
+ ttl: t.state === "expires" ? t.at : null,
299
433
  };
300
434
  }
301
435
  return out;