@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.
@@ -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
- 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 = this._resolveTtl(options);
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);
110
- return Promise.resolve(JSON.parse(value));
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
- 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);
@@ -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 (let key of keysToDelete) {
152
- key = this._withNs(key);
153
- this.#store.delete(key);
154
- 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);
155
222
  deleteCount++;
156
223
  }
157
224
  return deleteCount;
158
225
  }
159
226
  /** @inheritdoc */
160
- async setMultiple(keyValuePairs, options = {}) {
227
+ async setMultiple(entries, options = {}) {
161
228
  this._assertInitialized();
229
+ const normalized = this._normalizePairs(entries);
162
230
  const results = [];
163
- for (const [key, value] of keyValuePairs) {
164
- 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);
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
- key = this._withNs(key);
182
- if (!this.#store.has(key) || this.#isExpired(key)) {
183
- return Promise.resolve(false);
250
+ const nsKey = this._withNs(key);
251
+ if (!this.#store.has(nsKey) || this.#isExpired(nsKey)) {
252
+ return false;
184
253
  }
185
- this.#expirations.set(key, new Date(Date.now() + ttl * 1000));
186
- return Promise.resolve(true);
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
- key = this._withNs(key);
192
- // Key doesn't exist
193
- if (!this.#store.has(key))
194
- return Promise.resolve(false);
195
- // Key expired (and was cleaned up)
196
- if (this.#isExpired(key))
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 Promise.resolve(null);
202
- return Promise.resolve(expiresAt);
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
- try {
212
- for (const op of operations) {
213
- switch (op.type) {
214
- case "set":
215
- results.push(await this.set(op.key, op.value, op.options || {}));
216
- break;
217
- case "get":
218
- results.push(await this.get(op.key));
219
- break;
220
- case "delete":
221
- results.push(await this.delete(op.key));
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: await this.ttl(k),
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(keyValuePairs: [string, any][], options?: Partial<SetOptions>): Promise<boolean[]>;
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<Date | null | false>;
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 | false;
80
+ ttl: Date | null;
93
81
  }>>;
94
82
  }