@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.
- package/AGENTS.md +54 -18
- package/API.md +273 -31
- package/CLAUDE.md +3 -0
- package/README.md +126 -9
- package/dist/adapter/abstract.d.ts +140 -24
- package/dist/adapter/abstract.js +141 -23
- package/dist/adapter/deno-kv.d.ts +41 -11
- package/dist/adapter/deno-kv.js +251 -62
- package/dist/adapter/memory.d.ts +16 -4
- package/dist/adapter/memory.js +137 -80
- package/dist/adapter/postgres.d.ts +18 -25
- package/dist/adapter/postgres.js +294 -117
- package/dist/adapter/redis.d.ts +17 -4
- package/dist/adapter/redis.js +213 -40
- package/dist/kv.d.ts +2 -2
- package/dist/kv.js +1 -1
- package/package.json +14 -5
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();
|
|
@@ -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
|
-
|
|
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
|
-
|
|
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 =
|
|
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 {
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
310
|
+
async setMultiple(entries, options = {}) {
|
|
152
311
|
this._assertInitialized();
|
|
153
312
|
const { db } = this.options;
|
|
154
|
-
const
|
|
313
|
+
const normalized = this._normalizePairs(entries);
|
|
155
314
|
const pipeline = db.multi();
|
|
156
|
-
for (
|
|
157
|
-
|
|
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
|
-
|
|
168
|
-
const values = await db.mGet(
|
|
326
|
+
const nsKeys = keys.map((k) => this._withNs(k));
|
|
327
|
+
const values = await db.mGet(nsKeys);
|
|
169
328
|
const result = {};
|
|
170
|
-
keys.forEach((
|
|
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[
|
|
333
|
+
result[origKey] = JSON.parse(`${value}`);
|
|
176
334
|
}
|
|
177
335
|
catch (_err) {
|
|
178
|
-
result[
|
|
336
|
+
result[origKey] = value;
|
|
179
337
|
}
|
|
180
338
|
}
|
|
181
339
|
else {
|
|
182
|
-
result[
|
|
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
|
|
358
|
+
return { state: "missing" };
|
|
201
359
|
// No expiration set
|
|
202
360
|
if (ttl === -1)
|
|
203
|
-
return
|
|
361
|
+
return { state: "no-ttl" };
|
|
204
362
|
// Positive number: TTL in seconds remaining
|
|
205
|
-
return
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
256
|
-
const
|
|
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:
|
|
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": "
|
|
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.
|
|
17
|
-
"@types/pg": "^8.
|
|
25
|
+
"@marianmeres/clog": "^3.17.0",
|
|
26
|
+
"@types/pg": "^8.20.0",
|
|
18
27
|
"@types/redis": "^4.0.10",
|
|
19
|
-
"pg": "^8.
|
|
20
|
-
"redis": "^5.
|
|
28
|
+
"pg": "^8.20.0",
|
|
29
|
+
"redis": "^5.12.1"
|
|
21
30
|
},
|
|
22
31
|
"repository": {
|
|
23
32
|
"type": "git",
|