@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.
- package/AGENTS.md +45 -13
- package/API.md +230 -26
- package/README.md +64 -4
- package/dist/adapter/abstract.d.ts +121 -24
- package/dist/adapter/abstract.js +111 -22
- package/dist/adapter/deno-kv.d.ts +41 -11
- package/dist/adapter/deno-kv.js +201 -48
- package/dist/adapter/memory.d.ts +16 -4
- package/dist/adapter/memory.js +137 -78
- package/dist/adapter/postgres.d.ts +16 -28
- package/dist/adapter/postgres.js +184 -56
- package/dist/adapter/redis.d.ts +16 -4
- package/dist/adapter/redis.js +167 -33
- package/dist/kv.d.ts +2 -2
- package/dist/kv.js +1 -1
- package/package.json +1 -1
package/dist/adapter/postgres.js
CHANGED
|
@@ -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 '\'
|
|
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
|
-
|
|
202
|
-
|
|
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(
|
|
358
|
+
async setMultiple(entries, options = {}) {
|
|
224
359
|
this._assertInitialized();
|
|
225
|
-
if (
|
|
360
|
+
if (entries.length === 0)
|
|
226
361
|
return [];
|
|
362
|
+
const normalized = this._normalizePairs(entries);
|
|
227
363
|
const { db, tableName } = this.options;
|
|
228
|
-
const
|
|
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
|
-
|
|
235
|
-
|
|
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
|
|
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
|
|
427
|
+
return { state: "missing" };
|
|
294
428
|
const expiresAt = rows[0].expires_at;
|
|
295
|
-
// No expiration set
|
|
296
429
|
if (!expiresAt)
|
|
297
|
-
return
|
|
298
|
-
|
|
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
|
}, {});
|
package/dist/adapter/redis.d.ts
CHANGED
|
@@ -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(
|
|
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<
|
|
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
|
|
94
|
+
ttl: Date | null;
|
|
83
95
|
}>>;
|
|
84
96
|
}
|
package/dist/adapter/redis.js
CHANGED
|
@@ -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
|
-
|
|
61
|
-
|
|
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
|
-
|
|
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 {
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
310
|
+
async setMultiple(entries, options = {}) {
|
|
180
311
|
this._assertInitialized();
|
|
181
312
|
const { db } = this.options;
|
|
182
|
-
const
|
|
313
|
+
const normalized = this._normalizePairs(entries);
|
|
183
314
|
const pipeline = db.multi();
|
|
184
|
-
for (
|
|
185
|
-
|
|
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
|
-
|
|
196
|
-
const values = await db.mGet(
|
|
326
|
+
const nsKeys = keys.map((k) => this._withNs(k));
|
|
327
|
+
const values = await db.mGet(nsKeys);
|
|
197
328
|
const result = {};
|
|
198
|
-
keys.forEach((
|
|
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[
|
|
333
|
+
result[origKey] = JSON.parse(`${value}`);
|
|
204
334
|
}
|
|
205
335
|
catch (_err) {
|
|
206
|
-
result[
|
|
336
|
+
result[origKey] = value;
|
|
207
337
|
}
|
|
208
338
|
}
|
|
209
339
|
else {
|
|
210
|
-
result[
|
|
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
|
|
358
|
+
return { state: "missing" };
|
|
229
359
|
// No expiration set
|
|
230
360
|
if (ttl === -1)
|
|
231
|
-
return
|
|
361
|
+
return { state: "no-ttl" };
|
|
232
362
|
// Positive number: TTL in seconds remaining
|
|
233
|
-
return
|
|
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:
|
|
432
|
+
ttl: t.state === "expires" ? t.at : null,
|
|
299
433
|
};
|
|
300
434
|
}
|
|
301
435
|
return out;
|