@marianmeres/kv 2.1.0 → 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 +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/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,61 +83,121 @@ 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
|
|
110
|
-
return
|
|
175
|
+
return null;
|
|
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);
|
|
@@ -144,24 +205,32 @@ export class AdapterMemory extends AdapterAbstract {
|
|
|
144
205
|
return Promise.resolve(all.filter((key) => regex.test(key)));
|
|
145
206
|
}
|
|
146
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 */
|
|
147
214
|
async clear(pattern) {
|
|
148
215
|
this._assertInitialized();
|
|
149
216
|
const keysToDelete = await this.keys(pattern);
|
|
150
217
|
let deleteCount = 0;
|
|
151
|
-
for (
|
|
152
|
-
|
|
153
|
-
this.#store.delete(
|
|
154
|
-
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);
|
|
155
222
|
deleteCount++;
|
|
156
223
|
}
|
|
157
224
|
return deleteCount;
|
|
158
225
|
}
|
|
159
226
|
/** @inheritdoc */
|
|
160
|
-
async setMultiple(
|
|
227
|
+
async setMultiple(entries, options = {}) {
|
|
161
228
|
this._assertInitialized();
|
|
229
|
+
const normalized = this._normalizePairs(entries);
|
|
162
230
|
const results = [];
|
|
163
|
-
for (const
|
|
164
|
-
|
|
231
|
+
for (const { key, value, ttl } of normalized) {
|
|
232
|
+
const opts = ttl !== undefined ? { ...options, ttl } : options;
|
|
233
|
+
await this.set(key, value, opts);
|
|
165
234
|
results.push(true);
|
|
166
235
|
}
|
|
167
236
|
return results;
|
|
@@ -176,57 +245,46 @@ export class AdapterMemory extends AdapterAbstract {
|
|
|
176
245
|
return result;
|
|
177
246
|
}
|
|
178
247
|
/** @inheritdoc */
|
|
179
|
-
expire(key, ttl) {
|
|
248
|
+
async expire(key, ttl) {
|
|
180
249
|
this._assertInitialized();
|
|
181
|
-
|
|
182
|
-
if (!this.#store.has(
|
|
183
|
-
return
|
|
250
|
+
const nsKey = this._withNs(key);
|
|
251
|
+
if (!this.#store.has(nsKey) || this.#isExpired(nsKey)) {
|
|
252
|
+
return false;
|
|
184
253
|
}
|
|
185
|
-
this.#expirations.set(
|
|
186
|
-
return
|
|
254
|
+
this.#expirations.set(nsKey, new Date(Date.now() + ttl * 1000));
|
|
255
|
+
return true;
|
|
187
256
|
}
|
|
188
257
|
/** @inheritdoc */
|
|
189
|
-
ttl(key) {
|
|
258
|
+
async ttl(key) {
|
|
190
259
|
this._assertInitialized();
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
return Promise.resolve(false);
|
|
198
|
-
const expiresAt = this.#expirations.get(key);
|
|
199
|
-
// 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);
|
|
200
266
|
if (!expiresAt)
|
|
201
|
-
return
|
|
202
|
-
return
|
|
203
|
-
// const remaining = Math.max(0, expiresAt.valueOf() - Date.now());
|
|
204
|
-
// return Promise.resolve(new Date(Date.now() + Math.ceil(remaining)));
|
|
267
|
+
return { state: "no-ttl" };
|
|
268
|
+
return { state: "expires", at: expiresAt };
|
|
205
269
|
}
|
|
206
270
|
/** @inheritdoc */
|
|
207
271
|
async transaction(operations) {
|
|
208
272
|
this._assertInitialized();
|
|
209
273
|
// note: memory operations are atomic by nature
|
|
210
274
|
const results = [];
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
break;
|
|
223
|
-
}
|
|
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;
|
|
224
286
|
}
|
|
225
287
|
}
|
|
226
|
-
catch (err) {
|
|
227
|
-
// rollback here in a real db-based adapter
|
|
228
|
-
throw err;
|
|
229
|
-
}
|
|
230
288
|
return results;
|
|
231
289
|
}
|
|
232
290
|
async __debug_dump() {
|
|
@@ -236,9 +294,10 @@ export class AdapterMemory extends AdapterAbstract {
|
|
|
236
294
|
// need to strip the namespace from the key
|
|
237
295
|
if (this.namespace)
|
|
238
296
|
k = k.slice(this.namespace.length);
|
|
297
|
+
const t = await this.ttl(k);
|
|
239
298
|
out[k] = {
|
|
240
299
|
value: await this.get(k),
|
|
241
|
-
ttl:
|
|
300
|
+
ttl: t.state === "expires" ? t.at : null,
|
|
242
301
|
};
|
|
243
302
|
}
|
|
244
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.
|
|
@@ -30,30 +30,6 @@ export interface AdapterPostgresOptions extends AdapterAbstractOptions {
|
|
|
30
30
|
*
|
|
31
31
|
* Provides persistent key-value storage using PostgreSQL with JSONB values.
|
|
32
32
|
* Automatically creates the required table and indexes on initialization.
|
|
33
|
-
*
|
|
34
|
-
* @remarks
|
|
35
|
-
* - Uses UPSERT (INSERT ... ON CONFLICT) for atomic set operations
|
|
36
|
-
* - Uses PostgreSQL transactions for the `transaction()` method — when `db`
|
|
37
|
-
* is a `pg.Pool`, a single client is checked out for the duration of the
|
|
38
|
-
* transaction so BEGIN/COMMIT/ROLLBACK and all contained queries run on
|
|
39
|
-
* the same physical connection
|
|
40
|
-
* - Values are stored as JSONB for efficient querying
|
|
41
|
-
* - Supports automatic TTL cleanup via background timer
|
|
42
|
-
* - Table schema: key (VARCHAR), value (JSONB), expires_at, created_at, updated_at
|
|
43
|
-
*
|
|
44
|
-
* @example
|
|
45
|
-
* ```typescript
|
|
46
|
-
* import pg from 'pg';
|
|
47
|
-
*
|
|
48
|
-
* const pool = new pg.Pool({ connectionString: 'postgres://...' });
|
|
49
|
-
* const client = createKVClient("myapp:", "postgres", {
|
|
50
|
-
* db: pool,
|
|
51
|
-
* tableName: "kv_store",
|
|
52
|
-
* ttlCleanupIntervalSec: 300, // Clean expired keys every 5 minutes
|
|
53
|
-
* });
|
|
54
|
-
* await client.initialize();
|
|
55
|
-
* await client.set("config:theme", { dark: true });
|
|
56
|
-
* ```
|
|
57
33
|
*/
|
|
58
34
|
export declare class AdapterPostgres extends AdapterAbstract {
|
|
59
35
|
#private;
|
|
@@ -68,6 +44,16 @@ export declare class AdapterPostgres extends AdapterAbstract {
|
|
|
68
44
|
/** @inheritdoc */
|
|
69
45
|
set(key: string, value: any, options?: Partial<SetOptions>): Promise<boolean>;
|
|
70
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 */
|
|
71
57
|
get(key: string): Promise<any>;
|
|
72
58
|
/** @inheritdoc */
|
|
73
59
|
delete(key: string): Promise<boolean>;
|
|
@@ -76,19 +62,21 @@ export declare class AdapterPostgres extends AdapterAbstract {
|
|
|
76
62
|
/** @inheritdoc */
|
|
77
63
|
keys(pattern: string): Promise<string[]>;
|
|
78
64
|
/** @inheritdoc */
|
|
65
|
+
keysIter(pattern: string): AsyncIterable<string>;
|
|
66
|
+
/** @inheritdoc */
|
|
79
67
|
clear(pattern: string): Promise<number>;
|
|
80
68
|
/** @inheritdoc */
|
|
81
|
-
setMultiple(
|
|
69
|
+
setMultiple(entries: readonly SetMultipleEntry[], options?: Partial<SetOptions>): Promise<boolean[]>;
|
|
82
70
|
/** @inheritdoc */
|
|
83
71
|
getMultiple(keys: string[]): Promise<Record<string, any>>;
|
|
84
72
|
/** @inheritdoc */
|
|
85
73
|
expire(key: string, ttl: number): Promise<boolean>;
|
|
86
74
|
/** @inheritdoc */
|
|
87
|
-
ttl(key: string): Promise<
|
|
75
|
+
ttl(key: string): Promise<TtlResult>;
|
|
88
76
|
/** @inheritdoc */
|
|
89
77
|
transaction(operations: Operation[]): Promise<any[]>;
|
|
90
78
|
__debug_dump(): Promise<Record<string, {
|
|
91
79
|
value: any;
|
|
92
|
-
ttl: Date | null
|
|
80
|
+
ttl: Date | null;
|
|
93
81
|
}>>;
|
|
94
82
|
}
|