@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.
@@ -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
- key = this._withNs(key);
97
+ const nsKey = this._withNs(key);
89
98
  // to be consistent across adapters, keeping internally the strigified version...
90
- this.#store.set(key, JSON.stringify(value));
91
- const ttl = options.ttl || this.options.defaultTtl;
92
- if (ttl) {
93
- this.#expirations.set(key, new Date(Date.now() + ttl * 1_000));
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
- else {
96
- this.#expirations.delete(key);
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
- return Promise.resolve(true);
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
- get(key) {
149
+ async cas(key, expected, next, options = {}) {
102
150
  this._assertInitialized();
103
- key = this._withNs(key);
104
- if (this.#isExpired(key))
105
- return Promise.resolve(null);
106
- const value = this.#store.get(key);
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 Promise.resolve(null);
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
- key = this._withNs(key);
116
- const existed = this.#store.has(key);
117
- this.#store.delete(key);
118
- this.#expirations.delete(key);
119
- return Promise.resolve(existed);
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
- key = this._withNs(key);
125
- if (this.#isExpired(key))
126
- return Promise.resolve(false);
127
- return Promise.resolve(this.#store.has(key));
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
- // convert Redis-style pattern to regex
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 (let key of keysToDelete) {
154
- key = this._withNs(key);
155
- this.#store.delete(key);
156
- this.#expirations.delete(key);
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(keyValuePairs, options = {}) {
227
+ async setMultiple(entries, options = {}) {
163
228
  this._assertInitialized();
229
+ const normalized = this._normalizePairs(entries);
164
230
  const results = [];
165
- for (const [key, value] of keyValuePairs) {
166
- await this.set(key, value, options);
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
- key = this._withNs(key);
184
- if (!this.#store.has(key) || this.#isExpired(key)) {
185
- return Promise.resolve(false);
250
+ const nsKey = this._withNs(key);
251
+ if (!this.#store.has(nsKey) || this.#isExpired(nsKey)) {
252
+ return false;
186
253
  }
187
- this.#expirations.set(key, new Date(Date.now() + ttl * 1000));
188
- return Promise.resolve(true);
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
- key = this._withNs(key);
194
- // Key doesn't exist
195
- if (!this.#store.has(key))
196
- return Promise.resolve(false);
197
- // Key expired (and was cleaned up)
198
- if (this.#isExpired(key))
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 Promise.resolve(null);
204
- return Promise.resolve(expiresAt);
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
- try {
214
- for (const op of operations) {
215
- switch (op.type) {
216
- case "set":
217
- results.push(await this.set(op.key, op.value, op.options || {}));
218
- break;
219
- case "get":
220
- results.push(await this.get(op.key));
221
- break;
222
- case "delete":
223
- results.push(await this.delete(op.key));
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: await this.ttl(k),
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(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<boolean[]>;
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<Date | null | false>;
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 | false;
80
+ ttl: Date | null;
88
81
  }>>;
89
82
  }