@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/memory.js
CHANGED
|
@@ -34,6 +34,7 @@ export class AdapterMemory extends AdapterAbstract {
|
|
|
34
34
|
defaultTtl: 0, // no ttl by default
|
|
35
35
|
ttlCleanupIntervalSec: 0,
|
|
36
36
|
logger: createClog("KV/memory"),
|
|
37
|
+
validateKeys: true,
|
|
37
38
|
};
|
|
38
39
|
#store = new Map();
|
|
39
40
|
#expirations = new Map();
|
|
@@ -82,88 +83,154 @@ export class AdapterMemory extends AdapterAbstract {
|
|
|
82
83
|
}
|
|
83
84
|
return false;
|
|
84
85
|
}
|
|
86
|
+
#applyTtl(nsKey, ttlSeconds) {
|
|
87
|
+
if (ttlSeconds) {
|
|
88
|
+
this.#expirations.set(nsKey, new Date(Date.now() + ttlSeconds * 1_000));
|
|
89
|
+
}
|
|
90
|
+
else {
|
|
91
|
+
this.#expirations.delete(nsKey);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
85
94
|
/** @inheritdoc */
|
|
86
|
-
set(key, value, options = {}) {
|
|
95
|
+
async set(key, value, options = {}) {
|
|
87
96
|
this._assertInitialized();
|
|
88
|
-
|
|
97
|
+
const nsKey = this._withNs(key);
|
|
89
98
|
// to be consistent across adapters, keeping internally the strigified version...
|
|
90
|
-
this.#store.set(
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
99
|
+
this.#store.set(nsKey, JSON.stringify(value));
|
|
100
|
+
this.#applyTtl(nsKey, this._resolveTtl(options));
|
|
101
|
+
return true;
|
|
102
|
+
}
|
|
103
|
+
/** @inheritdoc */
|
|
104
|
+
async setIfAbsent(key, value, options = {}) {
|
|
105
|
+
this._assertInitialized();
|
|
106
|
+
const nsKey = this._withNs(key);
|
|
107
|
+
if (this.#store.has(nsKey) && !this.#isExpired(nsKey)) {
|
|
108
|
+
return false;
|
|
94
109
|
}
|
|
95
|
-
|
|
96
|
-
|
|
110
|
+
this.#store.set(nsKey, JSON.stringify(value));
|
|
111
|
+
this.#applyTtl(nsKey, this._resolveTtl(options));
|
|
112
|
+
return true;
|
|
113
|
+
}
|
|
114
|
+
/** @inheritdoc */
|
|
115
|
+
async getSet(key, value, options = {}) {
|
|
116
|
+
this._assertInitialized();
|
|
117
|
+
const previous = await this.get(key);
|
|
118
|
+
await this.set(key, value, options);
|
|
119
|
+
return previous;
|
|
120
|
+
}
|
|
121
|
+
#incrBy(key, delta, options = {}) {
|
|
122
|
+
this._assertInitialized();
|
|
123
|
+
const nsKey = this._withNs(key);
|
|
124
|
+
const existed = this.#store.has(nsKey) && !this.#isExpired(nsKey);
|
|
125
|
+
let current = 0;
|
|
126
|
+
if (existed) {
|
|
127
|
+
const raw = JSON.parse(this.#store.get(nsKey));
|
|
128
|
+
if (typeof raw !== "number") {
|
|
129
|
+
throw new TypeError("KV value is not a number");
|
|
130
|
+
}
|
|
131
|
+
current = raw;
|
|
97
132
|
}
|
|
98
|
-
|
|
133
|
+
const next = current + delta;
|
|
134
|
+
this.#store.set(nsKey, JSON.stringify(next));
|
|
135
|
+
// only set TTL when the key was newly created
|
|
136
|
+
if (!existed)
|
|
137
|
+
this.#applyTtl(nsKey, this._resolveTtl(options));
|
|
138
|
+
return next;
|
|
139
|
+
}
|
|
140
|
+
/** @inheritdoc */
|
|
141
|
+
async incr(key, by = 1, options = {}) {
|
|
142
|
+
return this.#incrBy(key, by, options);
|
|
143
|
+
}
|
|
144
|
+
/** @inheritdoc */
|
|
145
|
+
async decr(key, by = 1, options = {}) {
|
|
146
|
+
return this.#incrBy(key, -by, options);
|
|
99
147
|
}
|
|
100
148
|
/** @inheritdoc */
|
|
101
|
-
|
|
149
|
+
async cas(key, expected, next, options = {}) {
|
|
102
150
|
this._assertInitialized();
|
|
103
|
-
|
|
104
|
-
if (this.#isExpired(
|
|
105
|
-
return
|
|
106
|
-
|
|
151
|
+
const nsKey = this._withNs(key);
|
|
152
|
+
if (!this.#store.has(nsKey) || this.#isExpired(nsKey)) {
|
|
153
|
+
return false;
|
|
154
|
+
}
|
|
155
|
+
const currentRaw = JSON.parse(this.#store.get(nsKey));
|
|
156
|
+
if (JSON.stringify(currentRaw) !== JSON.stringify(expected)) {
|
|
157
|
+
return false;
|
|
158
|
+
}
|
|
159
|
+
this.#store.set(nsKey, JSON.stringify(next));
|
|
160
|
+
// CAS preserves existing TTL unless options.ttl is provided
|
|
161
|
+
if (options.ttl !== undefined) {
|
|
162
|
+
this.#applyTtl(nsKey, this._resolveTtl(options));
|
|
163
|
+
}
|
|
164
|
+
return true;
|
|
165
|
+
}
|
|
166
|
+
/** @inheritdoc */
|
|
167
|
+
async get(key) {
|
|
168
|
+
this._assertInitialized();
|
|
169
|
+
const nsKey = this._withNs(key);
|
|
170
|
+
if (this.#isExpired(nsKey))
|
|
171
|
+
return null;
|
|
172
|
+
const value = this.#store.get(nsKey);
|
|
107
173
|
// NOTE: even if the saved value was `undefined` it is always returned as `null`
|
|
108
174
|
if (value === undefined)
|
|
109
|
-
return
|
|
175
|
+
return null;
|
|
110
176
|
return JSON.parse(value);
|
|
111
177
|
}
|
|
112
178
|
/** @inheritdoc */
|
|
113
|
-
delete(key) {
|
|
179
|
+
async delete(key) {
|
|
114
180
|
this._assertInitialized();
|
|
115
|
-
|
|
116
|
-
const existed = this.#store.has(
|
|
117
|
-
this.#store.delete(
|
|
118
|
-
this.#expirations.delete(
|
|
119
|
-
return
|
|
181
|
+
const nsKey = this._withNs(key);
|
|
182
|
+
const existed = this.#store.has(nsKey);
|
|
183
|
+
this.#store.delete(nsKey);
|
|
184
|
+
this.#expirations.delete(nsKey);
|
|
185
|
+
return existed;
|
|
120
186
|
}
|
|
121
187
|
/** @inheritdoc */
|
|
122
|
-
exists(key) {
|
|
188
|
+
async exists(key) {
|
|
123
189
|
this._assertInitialized();
|
|
124
|
-
|
|
125
|
-
if (this.#isExpired(
|
|
126
|
-
return
|
|
127
|
-
return
|
|
190
|
+
const nsKey = this._withNs(key);
|
|
191
|
+
if (this.#isExpired(nsKey))
|
|
192
|
+
return false;
|
|
193
|
+
return this.#store.has(nsKey);
|
|
128
194
|
}
|
|
129
195
|
/** @inheritdoc */
|
|
130
196
|
keys(pattern) {
|
|
131
197
|
this._assertInitialized();
|
|
132
198
|
const all = Array.from(this.#store.keys())
|
|
133
199
|
.filter((key) => !this.#isExpired(key))
|
|
134
|
-
.map((k) =>
|
|
135
|
-
// strip namespace if exists
|
|
136
|
-
if (this.namespace)
|
|
137
|
-
k = k.slice(this.namespace.length);
|
|
138
|
-
return k;
|
|
139
|
-
})
|
|
200
|
+
.map((k) => (this.namespace ? k.slice(this.namespace.length) : k))
|
|
140
201
|
.toSorted();
|
|
141
202
|
if (pattern === "*")
|
|
142
203
|
return Promise.resolve(all);
|
|
143
|
-
|
|
144
|
-
const regexPattern = pattern.replace(/\*/g, ".*").replace(/\?/g, ".");
|
|
145
|
-
const regex = new RegExp(`^${regexPattern}$`);
|
|
204
|
+
const regex = this._globToRegex(pattern);
|
|
146
205
|
return Promise.resolve(all.filter((key) => regex.test(key)));
|
|
147
206
|
}
|
|
148
207
|
/** @inheritdoc */
|
|
208
|
+
async *keysIter(pattern) {
|
|
209
|
+
const all = await this.keys(pattern);
|
|
210
|
+
for (const k of all)
|
|
211
|
+
yield k;
|
|
212
|
+
}
|
|
213
|
+
/** @inheritdoc */
|
|
149
214
|
async clear(pattern) {
|
|
150
215
|
this._assertInitialized();
|
|
151
216
|
const keysToDelete = await this.keys(pattern);
|
|
152
217
|
let deleteCount = 0;
|
|
153
|
-
for (
|
|
154
|
-
|
|
155
|
-
this.#store.delete(
|
|
156
|
-
this.#expirations.delete(
|
|
218
|
+
for (const key of keysToDelete) {
|
|
219
|
+
const nsKey = this.namespace + key;
|
|
220
|
+
this.#store.delete(nsKey);
|
|
221
|
+
this.#expirations.delete(nsKey);
|
|
157
222
|
deleteCount++;
|
|
158
223
|
}
|
|
159
224
|
return deleteCount;
|
|
160
225
|
}
|
|
161
226
|
/** @inheritdoc */
|
|
162
|
-
async setMultiple(
|
|
227
|
+
async setMultiple(entries, options = {}) {
|
|
163
228
|
this._assertInitialized();
|
|
229
|
+
const normalized = this._normalizePairs(entries);
|
|
164
230
|
const results = [];
|
|
165
|
-
for (const
|
|
166
|
-
|
|
231
|
+
for (const { key, value, ttl } of normalized) {
|
|
232
|
+
const opts = ttl !== undefined ? { ...options, ttl } : options;
|
|
233
|
+
await this.set(key, value, opts);
|
|
167
234
|
results.push(true);
|
|
168
235
|
}
|
|
169
236
|
return results;
|
|
@@ -178,57 +245,46 @@ export class AdapterMemory extends AdapterAbstract {
|
|
|
178
245
|
return result;
|
|
179
246
|
}
|
|
180
247
|
/** @inheritdoc */
|
|
181
|
-
expire(key, ttl) {
|
|
248
|
+
async expire(key, ttl) {
|
|
182
249
|
this._assertInitialized();
|
|
183
|
-
|
|
184
|
-
if (!this.#store.has(
|
|
185
|
-
return
|
|
250
|
+
const nsKey = this._withNs(key);
|
|
251
|
+
if (!this.#store.has(nsKey) || this.#isExpired(nsKey)) {
|
|
252
|
+
return false;
|
|
186
253
|
}
|
|
187
|
-
this.#expirations.set(
|
|
188
|
-
return
|
|
254
|
+
this.#expirations.set(nsKey, new Date(Date.now() + ttl * 1000));
|
|
255
|
+
return true;
|
|
189
256
|
}
|
|
190
257
|
/** @inheritdoc */
|
|
191
|
-
ttl(key) {
|
|
258
|
+
async ttl(key) {
|
|
192
259
|
this._assertInitialized();
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
return Promise.resolve(false);
|
|
200
|
-
const expiresAt = this.#expirations.get(key);
|
|
201
|
-
// No expiration set
|
|
260
|
+
const nsKey = this._withNs(key);
|
|
261
|
+
if (!this.#store.has(nsKey))
|
|
262
|
+
return { state: "missing" };
|
|
263
|
+
if (this.#isExpired(nsKey))
|
|
264
|
+
return { state: "missing" };
|
|
265
|
+
const expiresAt = this.#expirations.get(nsKey);
|
|
202
266
|
if (!expiresAt)
|
|
203
|
-
return
|
|
204
|
-
return
|
|
205
|
-
// const remaining = Math.max(0, expiresAt.valueOf() - Date.now());
|
|
206
|
-
// return Promise.resolve(new Date(Date.now() + Math.ceil(remaining)));
|
|
267
|
+
return { state: "no-ttl" };
|
|
268
|
+
return { state: "expires", at: expiresAt };
|
|
207
269
|
}
|
|
208
270
|
/** @inheritdoc */
|
|
209
271
|
async transaction(operations) {
|
|
210
272
|
this._assertInitialized();
|
|
211
273
|
// note: memory operations are atomic by nature
|
|
212
274
|
const results = [];
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
break;
|
|
225
|
-
}
|
|
275
|
+
for (const op of operations) {
|
|
276
|
+
switch (op.type) {
|
|
277
|
+
case "set":
|
|
278
|
+
results.push(await this.set(op.key, op.value, op.options || {}));
|
|
279
|
+
break;
|
|
280
|
+
case "get":
|
|
281
|
+
results.push(await this.get(op.key));
|
|
282
|
+
break;
|
|
283
|
+
case "delete":
|
|
284
|
+
results.push(await this.delete(op.key));
|
|
285
|
+
break;
|
|
226
286
|
}
|
|
227
287
|
}
|
|
228
|
-
catch (err) {
|
|
229
|
-
// rollback here in a real db-based adapter
|
|
230
|
-
throw err;
|
|
231
|
-
}
|
|
232
288
|
return results;
|
|
233
289
|
}
|
|
234
290
|
async __debug_dump() {
|
|
@@ -238,9 +294,10 @@ export class AdapterMemory extends AdapterAbstract {
|
|
|
238
294
|
// need to strip the namespace from the key
|
|
239
295
|
if (this.namespace)
|
|
240
296
|
k = k.slice(this.namespace.length);
|
|
297
|
+
const t = await this.ttl(k);
|
|
241
298
|
out[k] = {
|
|
242
299
|
value: await this.get(k),
|
|
243
|
-
ttl:
|
|
300
|
+
ttl: t.state === "expires" ? t.at : null,
|
|
244
301
|
};
|
|
245
302
|
}
|
|
246
303
|
return Promise.resolve(out);
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*
|
|
4
4
|
* PostgreSQL key-value storage adapter implementation.
|
|
5
5
|
*/
|
|
6
|
-
import { AdapterAbstract, type Operation, type SetOptions, type AdapterAbstractOptions } from "./abstract.js";
|
|
6
|
+
import { AdapterAbstract, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult, type AdapterAbstractOptions } from "./abstract.js";
|
|
7
7
|
import type pg from "pg";
|
|
8
8
|
/**
|
|
9
9
|
* Configuration options for the PostgreSQL KV adapter.
|
|
@@ -14,6 +14,8 @@ export interface AdapterPostgresOptions extends AdapterAbstractOptions {
|
|
|
14
14
|
/**
|
|
15
15
|
* Name of the table to use for storing key-value pairs.
|
|
16
16
|
* The table will be created automatically if it doesn't exist.
|
|
17
|
+
* May be prefixed with a schema, e.g. `"public.kv"`.
|
|
18
|
+
* Only word characters and a single dot are allowed.
|
|
17
19
|
* @default "__kv"
|
|
18
20
|
*/
|
|
19
21
|
tableName: string;
|
|
@@ -28,27 +30,6 @@ export interface AdapterPostgresOptions extends AdapterAbstractOptions {
|
|
|
28
30
|
*
|
|
29
31
|
* Provides persistent key-value storage using PostgreSQL with JSONB values.
|
|
30
32
|
* Automatically creates the required table and indexes on initialization.
|
|
31
|
-
*
|
|
32
|
-
* @remarks
|
|
33
|
-
* - Uses UPSERT (INSERT ... ON CONFLICT) for atomic set operations
|
|
34
|
-
* - Uses PostgreSQL transactions for the `transaction()` method
|
|
35
|
-
* - Values are stored as JSONB for efficient querying
|
|
36
|
-
* - Supports automatic TTL cleanup via background timer
|
|
37
|
-
* - Table schema: key (VARCHAR), value (JSONB), expires_at, created_at, updated_at
|
|
38
|
-
*
|
|
39
|
-
* @example
|
|
40
|
-
* ```typescript
|
|
41
|
-
* import pg from 'pg';
|
|
42
|
-
*
|
|
43
|
-
* const pool = new pg.Pool({ connectionString: 'postgres://...' });
|
|
44
|
-
* const client = createKVClient("myapp:", "postgres", {
|
|
45
|
-
* db: pool,
|
|
46
|
-
* tableName: "kv_store",
|
|
47
|
-
* ttlCleanupIntervalSec: 300, // Clean expired keys every 5 minutes
|
|
48
|
-
* });
|
|
49
|
-
* await client.initialize();
|
|
50
|
-
* await client.set("config:theme", { dark: true });
|
|
51
|
-
* ```
|
|
52
33
|
*/
|
|
53
34
|
export declare class AdapterPostgres extends AdapterAbstract {
|
|
54
35
|
#private;
|
|
@@ -63,6 +44,16 @@ export declare class AdapterPostgres extends AdapterAbstract {
|
|
|
63
44
|
/** @inheritdoc */
|
|
64
45
|
set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
65
46
|
/** @inheritdoc */
|
|
47
|
+
setIfAbsent(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
48
|
+
/** @inheritdoc */
|
|
49
|
+
getSet(key: string, value: any, options?: Partial<SetOptions>): Promise<any>;
|
|
50
|
+
/** @inheritdoc */
|
|
51
|
+
incr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>;
|
|
52
|
+
/** @inheritdoc */
|
|
53
|
+
decr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>;
|
|
54
|
+
/** @inheritdoc */
|
|
55
|
+
cas(key: string, expected: any, next: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
56
|
+
/** @inheritdoc */
|
|
66
57
|
get(key: string): Promise<any>;
|
|
67
58
|
/** @inheritdoc */
|
|
68
59
|
delete(key: string): Promise<boolean>;
|
|
@@ -71,19 +62,21 @@ export declare class AdapterPostgres extends AdapterAbstract {
|
|
|
71
62
|
/** @inheritdoc */
|
|
72
63
|
keys(pattern: string): Promise<string[]>;
|
|
73
64
|
/** @inheritdoc */
|
|
65
|
+
keysIter(pattern: string): AsyncIterable<string>;
|
|
66
|
+
/** @inheritdoc */
|
|
74
67
|
clear(pattern: string): Promise<number>;
|
|
75
68
|
/** @inheritdoc */
|
|
76
|
-
setMultiple(
|
|
69
|
+
setMultiple(entries: readonly SetMultipleEntry[], options?: Partial<SetOptions>): Promise<boolean[]>;
|
|
77
70
|
/** @inheritdoc */
|
|
78
71
|
getMultiple(keys: string[]): Promise<Record<string, any>>;
|
|
79
72
|
/** @inheritdoc */
|
|
80
73
|
expire(key: string, ttl: number): Promise<boolean>;
|
|
81
74
|
/** @inheritdoc */
|
|
82
|
-
ttl(key: string): Promise<
|
|
75
|
+
ttl(key: string): Promise<TtlResult>;
|
|
83
76
|
/** @inheritdoc */
|
|
84
77
|
transaction(operations: Operation[]): Promise<any[]>;
|
|
85
78
|
__debug_dump(): Promise<Record<string, {
|
|
86
79
|
value: any;
|
|
87
|
-
ttl: Date | null
|
|
80
|
+
ttl: Date | null;
|
|
88
81
|
}>>;
|
|
89
82
|
}
|