@marianmeres/kv 1.3.1 → 2.1.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 CHANGED
@@ -1,50 +1,65 @@
1
- # @marianmeres/kv - Agent Reference
1
+ # @marianmeres/kv — Agent Guide
2
2
 
3
3
  Machine-friendly reference for AI agents working with this codebase.
4
4
 
5
- ## Package Identity
5
+ ## Quick Reference
6
6
 
7
- - **Name**: `@marianmeres/kv`
8
- - **Version**: 1.2.2
9
- - **License**: MIT
10
- - **Runtime**: Deno (primary), Node.js (via npm build)
11
- - **Language**: TypeScript
7
+ - **Stack**: TypeScript, Deno (primary), Node.js (via npm build)
8
+ - **Run**: `deno task test` | **Build**: `deno task npm:build`
9
+ - **Version**: 2.0.0
12
10
 
13
11
  ## Purpose
14
12
 
15
13
  Key-value storage abstraction layer providing a unified Redis-inspired API across multiple storage backends.
16
14
 
17
- ## Supported Adapters
18
-
19
- | Adapter | Type String | Required Options | Limitations |
20
- |---------|-------------|------------------|-------------|
21
- | Memory | `"memory"` | None | Not persisted |
22
- | Redis | `"redis"` | `db` (Redis client) | Namespace required; `keys()`/`clear()` unavailable in cluster mode |
23
- | PostgreSQL | `"postgres"` | `db` (pg.Pool/Client) | None |
24
- | Deno KV | `"deno-kv"` | `db` (Deno.Kv) | Deno runtime only; `delete()` always true; `expire()`/`ttl()` not supported |
25
-
26
- ## File Structure
15
+ ## Project Structure
27
16
 
28
17
  ```
29
18
  src/
30
- ├── mod.ts # Main entry point, re-exports kv.ts
31
- ├── kv.ts # Factory function and all exports
19
+ ├── mod.ts — Main entry point (re-exports kv.ts)
20
+ ├── kv.ts — Factory function and all exports
32
21
  ├── adapter/
33
- │ ├── abstract.ts # Base class + shared types
34
- │ ├── memory.ts # In-memory adapter
35
- │ ├── redis.ts # Redis adapter
36
- │ ├── postgres.ts # PostgreSQL adapter
37
- │ └── deno-kv.ts # Deno KV adapter
22
+ │ ├── abstract.ts — Base class + shared types
23
+ │ ├── memory.ts — In-memory adapter
24
+ │ ├── redis.ts — Redis adapter
25
+ │ ├── postgres.ts — PostgreSQL adapter
26
+ │ └── deno-kv.ts — Deno KV adapter
38
27
  └── utils/
39
- └── sleep.ts # Sleep utility function
28
+ └── sleep.ts — Sleep utility function
40
29
 
41
30
  tests/
42
- ├── kv.test.ts # Main test file
43
- ├── _tests-runner.ts # Test harness
44
- ├── _redis.ts # Redis test helper
45
- └── _pg.ts # PostgreSQL test helper
31
+ ├── kv.test.ts — Main test file
32
+ ├── _tests-runner.ts — Test harness
33
+ ├── _redis.ts — Redis test helper
34
+ └── _pg.ts — PostgreSQL test helper
46
35
  ```
47
36
 
37
+ ## Critical Conventions
38
+
39
+ 1. Namespace must end with `:` or be empty string.
40
+ 2. Values are JSON-stringified internally.
41
+ 3. TTL is in seconds; stored as absolute `Date` internally.
42
+ 4. Pattern matching: Redis-style (`*` = any chars, `?` = single char). All other characters — including `.`, `(`, `[`, `%`, `_` — are matched **literally**.
43
+ 5. TTL resolution: `options.ttl ?? defaultTtl`; `0` or negative disables expiration for that call (explicitly overrides `defaultTtl`).
44
+ 6. All pattern-to-regex / pattern-to-LIKE conversion lives in `abstract.ts` — use `_globToRegex()` and `_resolveTtl()` helpers; do not re-implement per-adapter.
45
+ 7. Postgres `transaction()` must pin a single connection via `pool.connect()`; every nested query uses that client, not `this.options.db`.
46
+ 8. Redis adapter owns the connection iff `initialize()` opened it (`#weOpened` flag).
47
+
48
+ ## Before Making Changes
49
+
50
+ - [ ] Check existing patterns in adapter implementations
51
+ - [ ] Run tests: `deno test --unstable-kv -A --env-file`
52
+ - [ ] Verify adapter limitations are documented
53
+
54
+ ## Supported Adapters
55
+
56
+ | Adapter | Type String | Required Options | Limitations |
57
+ |---------|-------------|------------------|-------------|
58
+ | Memory | `"memory"` | None | Not persisted |
59
+ | Redis | `"redis"` | `db` (Redis client) | Namespace required; `keys()`/`clear()` unavailable in cluster mode |
60
+ | PostgreSQL | `"postgres"` | `db` (pg.Pool/Client) | `tableName` limited to `[A-Za-z0-9_]` + optional `schema.` prefix |
61
+ | Deno KV | `"deno-kv"` | `db` (Deno.Kv) | Deno runtime only; `delete()` always `true`; `expire()`/`ttl()` unsupported; `transaction()` atomic only when no `get` ops |
62
+
48
63
  ## Core API
49
64
 
50
65
  ### Factory
@@ -92,9 +107,6 @@ deno test --unstable-kv -A --env-file --watch
92
107
 
93
108
  # Build npm package
94
109
  deno run -A scripts/build-npm.ts
95
-
96
- # Publish to npm
97
- deno run -A scripts/build-npm.ts && cd ./.npm-dist && npm publish --access=public
98
110
  ```
99
111
 
100
112
  ## Test Environment Variables
@@ -108,20 +120,6 @@ TEST_PG_PASSWORD=<required>
108
120
  TEST_REDIS_URL=redis://localhost:6379
109
121
  ```
110
122
 
111
- ## Implementation Notes
112
-
113
- 1. **Namespace**: Must end with `:` or be empty string
114
- 2. **Value Serialization**: All values JSON-stringified internally
115
- 3. **TTL**: In seconds; stored as absolute Date internally
116
- 4. **Pattern Matching**: Redis-style (`*` = any chars, `?` = single char)
117
- 5. **Transactions**: Atomic for Redis/PostgreSQL; sequential for memory/Deno KV
118
-
119
- ## Dependencies
120
-
121
- - `@marianmeres/clog` - Logging
122
- - `pg` - PostgreSQL driver
123
- - `redis` - Redis client
124
-
125
123
  ## Extending
126
124
 
127
125
  To add a new adapter:
@@ -131,3 +129,8 @@ To add a new adapter:
131
129
  4. Add to `KnownTypes` in `src/kv.ts`
132
130
  5. Add case in `createKVClient` factory
133
131
  6. Export from `src/kv.ts`
132
+
133
+ ## Documentation Index
134
+
135
+ - [API Reference](./API.md) — Complete API documentation
136
+ - [README](./README.md) — Quick start and installation
package/API.md CHANGED
@@ -149,11 +149,18 @@ Values are automatically serialized to JSON. If the key already exists, it will
149
149
 
150
150
  **Returns:** `Promise<boolean>` - `true` if the operation was successful.
151
151
 
152
+ **TTL resolution:**
153
+
154
+ - If `options.ttl` is omitted, the adapter's `defaultTtl` is used.
155
+ - If `options.ttl` is a positive number, it overrides `defaultTtl` for this call.
156
+ - If `options.ttl` is `0` or negative, **no expiration** is applied — this explicitly overrides a non-zero `defaultTtl`.
157
+
152
158
  **Example:**
153
159
 
154
160
  ```typescript
155
161
  await client.set("user:123", { name: "John" });
156
162
  await client.set("session:abc", { token: "xyz" }, { ttl: 3600 }); // expires in 1 hour
163
+ await client.set("pinned", 1, { ttl: 0 }); // never expires, even if defaultTtl > 0
157
164
  ```
158
165
 
159
166
  ---
@@ -221,6 +228,8 @@ exists(key: string): Promise<boolean>
221
228
 
222
229
  **Returns:** `Promise<boolean>` - `true` if the key exists and hasn't expired.
223
230
 
231
+ > A key with a stored value of `null` is considered to exist. `exists()` only returns `false` when the key is missing or has expired.
232
+
224
233
  ---
225
234
 
226
235
  #### `expire(key, ttl)`
@@ -300,6 +309,7 @@ keys(pattern: string): Promise<string[]>
300
309
  Uses Redis-style wildcard patterns:
301
310
  - `*` matches any number of characters
302
311
  - `?` matches exactly one character
312
+ - **Every other character is a literal match**, including regex metacharacters (`.`, `(`, `[`, `+`, `^`, `$`, `|`) and SQL LIKE metacharacters (`%`, `_`, `\`).
303
313
 
304
314
  **Parameters:**
305
315
 
@@ -316,6 +326,9 @@ Uses Redis-style wildcard patterns:
316
326
  ```typescript
317
327
  const userKeys = await client.keys("user:*");
318
328
  const allKeys = await client.keys("*");
329
+
330
+ // literal dot, not "any char"
331
+ const dotted = await client.keys("config.yaml"); // matches ONLY "config.yaml"
319
332
  ```
320
333
 
321
334
  ---
@@ -397,13 +410,16 @@ More efficient than multiple individual `get` calls.
397
410
  |-----------|------|-------------|
398
411
  | `keys` | `string[]` | Array of keys to retrieve. |
399
412
 
400
- **Returns:** `Promise<Record<string, any>>` - Object mapping keys to their values. Missing or expired keys will have a value of `null`.
413
+ **Returns:** `Promise<Record<string, any>>` - Object mapping keys to their values. Only **missing** or expired keys are reported as `null`; stored falsy values (`false`, `0`, `""`, `null`) are returned verbatim.
401
414
 
402
415
  **Example:**
403
416
 
404
417
  ```typescript
405
- const users = await client.getMultiple(["user:1", "user:2", "user:3"]);
406
- // { "user:1": { name: "Alice" }, "user:2": null, "user:3": { name: "Charlie" } }
418
+ await client.set("flag", false);
419
+ await client.set("count", 0);
420
+
421
+ const got = await client.getMultiple(["flag", "count", "missing"]);
422
+ // { flag: false, count: 0, missing: null }
407
423
  ```
408
424
 
409
425
  ---
@@ -418,7 +434,16 @@ Executes multiple operations within a single transaction.
418
434
  transaction(operations: Operation[]): Promise<any[]>
419
435
  ```
420
436
 
421
- For adapters that support it (Redis, PostgreSQL), operations are atomic. For memory and Deno KV, operations are executed sequentially.
437
+ Atomicity per adapter:
438
+
439
+ | Adapter | Atomic | Notes |
440
+ |---------|:-:|---|
441
+ | Memory | ✓ | Single-threaded by nature |
442
+ | Redis | ✓ | Uses `MULTI`/`EXEC` |
443
+ | PostgreSQL | ✓ | Pins a single connection for `BEGIN`/…/`COMMIT`, even on a `pg.Pool` |
444
+ | Deno KV | Conditional | Atomic via `Deno.Kv.atomic()` when the transaction contains **no** `get` ops; falls back to sequential (non-atomic) when a `get` is present (Deno.Kv has no atomic-read) |
445
+
446
+ Per-operation `options.ttl` is honored by **all** adapters (Redis, PostgreSQL, Memory, Deno KV).
422
447
 
423
448
  **Parameters:**
424
449
 
@@ -432,7 +457,7 @@ For adapters that support it (Redis, PostgreSQL), operations are atomic. For mem
432
457
 
433
458
  ```typescript
434
459
  const results = await client.transaction([
435
- { type: "set", key: "counter", value: 1 },
460
+ { type: "set", key: "counter", value: 1, options: { ttl: 60 } },
436
461
  { type: "get", key: "counter" },
437
462
  { type: "delete", key: "old:key" },
438
463
  ]);
@@ -539,6 +564,12 @@ interface AdapterRedisOptions extends AdapterAbstractOptions {
539
564
 
540
565
  **Important:** Namespace is required for Redis adapter (cannot be empty string).
541
566
 
567
+ **Connection ownership:**
568
+
569
+ - If the client passed via `db` is **not yet open** when `initialize()` runs, the adapter connects it **and** will close it on `destroy()`.
570
+ - If the client is **already open** when `initialize()` runs, the adapter leaves the connection untouched on `destroy()` — the caller owns the lifecycle. This is the path for sharing one client across multiple adapters with different namespaces.
571
+ - `initialize()` is idempotent — repeated calls do not stack `error` listeners.
572
+
542
573
  ---
543
574
 
544
575
  ### `AdapterPostgresOptions`
@@ -550,6 +581,9 @@ interface AdapterPostgresOptions extends AdapterAbstractOptions {
550
581
  /**
551
582
  * Name of the table to use for storing key-value pairs.
552
583
  * The table will be created automatically if it doesn't exist.
584
+ * May be prefixed with a schema, e.g. "public.kv".
585
+ * Must match `^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$`
586
+ * (word characters, optionally with one `schema.` prefix).
553
587
  * @default "__kv"
554
588
  */
555
589
  tableName: string;
@@ -561,6 +595,9 @@ interface AdapterPostgresOptions extends AdapterAbstractOptions {
561
595
  }
562
596
  ```
563
597
 
598
+ **Transactions on a Pool:**
599
+ `transaction()` checks out a single client from the pool (via `pool.connect()`) for the entire `BEGIN`/`COMMIT`/`ROLLBACK` block, so atomicity holds even when multiple transactions run concurrently against the same `pg.Pool`. On a `pg.Client`, no checkout happens.
600
+
564
601
  **Table Schema:**
565
602
  - `key` (VARCHAR 512) - Primary key
566
603
  - `value` (JSONB) - Stored value
@@ -587,6 +624,7 @@ interface AdapterDenoKvOptions extends AdapterAbstractOptions {
587
624
  - `expire()` is not supported (always returns `false`)
588
625
  - `ttl()` is not supported (always returns `null`)
589
626
  - TTL can be set during `set()` but cannot be queried afterward
627
+ - `transaction()` is atomic (via `Deno.Kv.atomic()`) **only** when the transaction contains no `get` operations — a mixed transaction falls back to sequential, non-atomic execution
590
628
 
591
629
  ---
592
630
 
package/CLAUDE.md ADDED
@@ -0,0 +1,3 @@
1
+ # Project Instructions
2
+
3
+ See [AGENTS.md](./AGENTS.md) for complete project documentation and AI agent instructions.
package/README.md CHANGED
@@ -61,26 +61,87 @@ client.expire(key: string, ttl: number): Promise<boolean>
61
61
  client.ttl(key: string): Promise<Date | null | false>
62
62
  ```
63
63
 
64
+ ## Pattern Syntax
65
+
66
+ `keys()` and `clear()` use Redis-style glob patterns:
67
+
68
+ - `*` — match any number of characters
69
+ - `?` — match exactly one character
70
+ - all other characters (including `.`, `%`, `_`, `(`, `)`, `[`, `]`) are treated **literally**
71
+
72
+ ## Adapter Feature Matrix
73
+
74
+ | Feature | Memory | Redis | PostgreSQL | Deno KV |
75
+ |---|:-:|:-:|:-:|:-:|
76
+ | Persistent | ✗ | ✓ | ✓ | ✓ |
77
+ | TTL on `set()` | ✓ | ✓ | ✓ | ✓ |
78
+ | `ttl()` query | ✓ | ✓ | ✓ | always `null` |
79
+ | `expire()` | ✓ | ✓ | ✓ | always `false` |
80
+ | Sorted `keys()` | ✓ | ✓ | ✓ | ✓ |
81
+ | Atomic `transaction()` | ✓ (single-threaded) | ✓ (MULTI) | ✓ (BEGIN/COMMIT) | ✓ when no `get` ops |
82
+ | `delete()` returns real existed-flag | ✓ | ✓ | ✓ | always `true` |
83
+ | Background TTL cleanup | optional | native (Redis does it) | optional | native (Deno.Kv does it) |
84
+ | `keys()` / `clear()` | ✓ | ✓ (non-cluster only) | ✓ | ✓ |
85
+
64
86
  ## Adapter-Specific Limitations
65
87
 
66
88
  ### Deno KV
67
89
  - **`delete()`**: Always returns `true`, even for non-existent keys (Deno.Kv limitation)
68
- - **`expire()`**: Not supported - always returns `false`
69
- - **`ttl()`**: Not supported - always returns `null`
70
- - **Note**: TTL can be set during `set()` operation, but cannot be queried or modified after
90
+ - **`expire()`**: Not supported — always returns `false`
91
+ - **`ttl()`**: Not supported — always returns `null`
92
+ - **`transaction()`**: Atomic via `Deno.Kv.atomic()` **only** when the transaction contains no `get` operations. A transaction that mixes `get` with `set`/`delete` falls back to sequential (non-atomic) execution.
93
+ - **Note**: TTL can be set during `set()`, but cannot be queried or modified after.
71
94
 
72
95
  ### Redis
73
96
  - **`keys()` and `clear()`**: Not supported in cluster mode (throws error)
74
97
  - **Namespace**: Required (cannot be empty string)
98
+ - **Connection ownership**: If you pass a not-yet-open client to the adapter, `initialize()` opens it and `destroy()` closes it. If you pass an already-open client, the adapter leaves the connection lifecycle to you — safe to share a single client across adapters with different namespaces.
75
99
 
76
100
  ### PostgreSQL
77
- - Creates a table (default: `__kv`) in your database
78
- - Supports optional TTL cleanup via `ttlCleanupIntervalSec` option
101
+ - Creates a table (default: `__kv`) in your database.
102
+ - `tableName` must match `^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$` (word chars plus an optional `schema.` prefix).
103
+ - `transaction()` pins a single connection from the Pool for the whole BEGIN/…/COMMIT block — safe to call against a `pg.Pool`.
104
+ - Supports optional TTL cleanup via `ttlCleanupIntervalSec` option.
79
105
 
80
106
  ### Memory
81
- - Data is not persisted (in-memory only)
82
- - Supports optional TTL cleanup via `ttlCleanupIntervalSec` option
107
+ - Data is not persisted (in-memory only).
108
+ - Supports optional TTL cleanup via `ttlCleanupIntervalSec` option.
109
+
110
+ ## Breaking Changes (2.0.0)
111
+
112
+ This release fixes several correctness bugs. Most fixes are behavior-preserving,
113
+ but a few change semantics in ways that could affect existing code:
114
+
115
+ - **`set(key, value, { ttl: 0 })` now explicitly disables expiration for the
116
+ call, overriding any non-zero `defaultTtl`.** Before: `ttl: 0` was silently
117
+ ignored and `defaultTtl` was used. If you relied on the old behavior, omit
118
+ the `ttl` option instead of passing `0`.
119
+ - **Redis adapter: `destroy()` now closes connections that `initialize()` opened.**
120
+ Connections that were already open when you passed them to the adapter remain
121
+ under your control (unchanged). If your test harness used to close the
122
+ underlying client twice, remove the redundant close.
123
+ - **Redis adapter: `__debug_dump()` is scoped to the adapter's namespace.**
124
+ Before: it dumped every key in the selected DB (across tenants). After:
125
+ only keys under this adapter's namespace.
126
+ - **`getMultiple()` preserves stored falsy values (`false`, `0`, `""`, `null`).**
127
+ Before: all of these were coerced to `null`, indistinguishable from "key
128
+ missing". After: stored falsy values round-trip; only missing keys map to
129
+ `null`.
130
+ - **Deno KV: `exists(key)` returns `true` when the stored value is `null`.**
131
+ Before: `null` values were reported as non-existent.
132
+ - **Deno KV: `keys()` is sorted.**
133
+ - **`keys()` and `clear()` now treat non-wildcard regex/LIKE metacharacters
134
+ as literals.** Before: Memory/Deno KV adapters leaked `.`/`(`/`[` through to
135
+ regex, and the PostgreSQL adapter leaked `%`/`_` through to LIKE. After:
136
+ only `*` and `?` are wildcards; everything else matches literally.
137
+ - **PostgreSQL: `tableName` is validated.** Invalid names (anything outside
138
+ `[A-Za-z0-9_.]`) now throw in the constructor instead of producing confusing
139
+ SQL errors at runtime.
83
140
 
84
141
  ## Full API Reference
85
142
 
86
143
  For complete API documentation including all methods, types, and adapter-specific options, see [API.md](API.md).
144
+
145
+ ## License
146
+
147
+ [MIT](LICENSE)
@@ -73,6 +73,25 @@ export declare abstract class AdapterAbstract {
73
73
  protected _assertValidNamespace(): void;
74
74
  protected _withNs(key: string): string;
75
75
  protected _withoutNs(key: string): string;
76
+ /**
77
+ * Resolves the effective TTL (in seconds) for a set operation.
78
+ *
79
+ * Uses `options.ttl` when provided, otherwise falls back to `defaultTtl`.
80
+ * Non-positive values (0 or less) mean "no expiration" and return `undefined`.
81
+ *
82
+ * Note: `{ ttl: 0 }` explicitly overrides a non-zero `defaultTtl` to mean
83
+ * "no expiration for this call".
84
+ */
85
+ protected _resolveTtl(opts?: Partial<SetOptions>): number | undefined;
86
+ /**
87
+ * Converts a Redis-style glob pattern to a regular expression.
88
+ * Escapes regex metacharacters before translating `*`/`?`.
89
+ *
90
+ * Glob syntax: `*` matches any chars, `?` matches a single char.
91
+ * All other characters — including `.`, `(`, `)`, `[`, `]`, `+` — are
92
+ * matched literally.
93
+ */
94
+ protected _globToRegex(pattern: string): RegExp;
76
95
  /**
77
96
  * Initializes the adapter and connects to the underlying storage.
78
97
  *
@@ -39,7 +39,10 @@ export class AdapterAbstract {
39
39
  constructor(namespace = "", options = {}) {
40
40
  this.namespace = namespace;
41
41
  this.options = { ...this.options, ...(options || {}) };
42
- this._assertValidNamespace();
42
+ // NOTE: subclasses re-declare `namespace` with a field initializer, so
43
+ // validation runs in each subclass constructor AFTER `super()` completes.
44
+ // Calling `_assertValidNamespace()` here would see the base default (empty)
45
+ // and provide no safety.
43
46
  }
44
47
  _assertInitialized() {
45
48
  if (!this._initialized) {
@@ -59,6 +62,32 @@ export class AdapterAbstract {
59
62
  key = key.slice(this.namespace.length);
60
63
  return key;
61
64
  }
65
+ /**
66
+ * Resolves the effective TTL (in seconds) for a set operation.
67
+ *
68
+ * Uses `options.ttl` when provided, otherwise falls back to `defaultTtl`.
69
+ * Non-positive values (0 or less) mean "no expiration" and return `undefined`.
70
+ *
71
+ * Note: `{ ttl: 0 }` explicitly overrides a non-zero `defaultTtl` to mean
72
+ * "no expiration for this call".
73
+ */
74
+ _resolveTtl(opts) {
75
+ const raw = opts?.ttl ?? this.options.defaultTtl;
76
+ return raw && raw > 0 ? raw : undefined;
77
+ }
78
+ /**
79
+ * Converts a Redis-style glob pattern to a regular expression.
80
+ * Escapes regex metacharacters before translating `*`/`?`.
81
+ *
82
+ * Glob syntax: `*` matches any chars, `?` matches a single char.
83
+ * All other characters — including `.`, `(`, `)`, `[`, `]`, `+` — are
84
+ * matched literally.
85
+ */
86
+ _globToRegex(pattern) {
87
+ const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
88
+ const body = escaped.replace(/\*/g, ".*").replace(/\?/g, ".");
89
+ return new RegExp(`^${body}$`);
90
+ }
62
91
  /**
63
92
  * Stores a key-value pair in the storage.
64
93
  *
@@ -67,7 +67,7 @@ export class AdapterDenoKv extends AdapterAbstract {
67
67
  async set(key, value, options = {}) {
68
68
  this._assertInitialized();
69
69
  const { db } = this.options;
70
- const ttl = options.ttl || this.options.defaultTtl || undefined;
70
+ const ttl = this._resolveTtl(options);
71
71
  if (value === undefined)
72
72
  value = null;
73
73
  // Deno.Kv does not require this, but for the consistency with other adapters
@@ -98,7 +98,11 @@ export class AdapterDenoKv extends AdapterAbstract {
98
98
  /** @inheritdoc */
99
99
  async exists(key) {
100
100
  this._assertInitialized();
101
- return null !== (await this.get(key));
101
+ const { db } = this.options;
102
+ // Deno.Kv returns an entry with `versionstamp: null` for missing keys,
103
+ // and a non-null versionstamp for present keys — even if the stored value is null.
104
+ const entry = await db.get(this.#denoKvKey(key));
105
+ return entry?.versionstamp !== null && entry?.versionstamp !== undefined;
102
106
  }
103
107
  /** @inheritdoc */
104
108
  async delete(key) {
@@ -111,22 +115,26 @@ export class AdapterDenoKv extends AdapterAbstract {
111
115
  async keys(pattern) {
112
116
  this._assertInitialized();
113
117
  const { db } = this.options;
114
- const [prefix, search] = this.#denoKvKey(pattern, false);
115
- // convert Redis-style pattern to regex
116
- const regexPattern = pattern.replace(/\*/g, ".*").replace(/\?/g, ".");
117
- const regex = new RegExp(`^${regexPattern}$`);
118
- const iter = db.list({
119
- prefix: [this.namespace, prefix === "*" ? undefined : prefix].filter(Boolean),
120
- });
118
+ const [firstSeg] = this.#denoKvKey(pattern, false);
119
+ const regex = this._globToRegex(pattern);
120
+ // Only use the first key segment as a Deno.Kv prefix if it contains
121
+ // no wildcards — otherwise we must scan the whole namespace and rely
122
+ // on regex filtering.
123
+ const firstIsLiteral = firstSeg !== undefined && firstSeg !== "*" && !/[*?]/.test(firstSeg);
124
+ const listPrefix = firstIsLiteral
125
+ ? [this.namespace, firstSeg]
126
+ : [this.namespace];
127
+ const iter = db.list({ prefix: listPrefix });
121
128
  const out = [];
122
129
  for await (const res of iter) {
123
- // note: here we have full data available, not just keys, so this is pure waste
130
+ // We must iterate entries (Deno.Kv has no keys-only API), but we
131
+ // deliberately do not touch `res.value` — no JSON parse, no copy.
124
132
  const key = res.key.slice(1).join(":");
125
- if (prefix === "*" || search === "*" || regex.test(key)) {
133
+ if (pattern === "*" || regex.test(key)) {
126
134
  out.push(key);
127
135
  }
128
136
  }
129
- return out;
137
+ return out.toSorted();
130
138
  }
131
139
  /** @inheritdoc */
132
140
  async clear(pattern) {
@@ -142,12 +150,20 @@ export class AdapterDenoKv extends AdapterAbstract {
142
150
  /** @inheritdoc */
143
151
  async setMultiple(keyValuePairs, options = {}) {
144
152
  this._assertInitialized();
145
- const results = [];
153
+ if (keyValuePairs.length === 0)
154
+ return [];
155
+ const { db } = this.options;
156
+ const ttl = this._resolveTtl(options);
157
+ const expireIn = ttl ? ttl * 1000 : undefined;
158
+ // batch into a single atomic commit (all-or-nothing)
159
+ const atomic = db.atomic();
146
160
  for (const [key, value] of keyValuePairs) {
147
- await this.set(key, value, options);
148
- results.push(true);
161
+ const v = value === undefined ? null : value;
162
+ atomic.set(this.#denoKvKey(key), JSON.stringify(v), { expireIn });
149
163
  }
150
- return results;
164
+ const res = await atomic.commit();
165
+ const ok = !!res?.ok;
166
+ return keyValuePairs.map(() => ok);
151
167
  }
152
168
  /** @inheritdoc */
153
169
  async getMultiple(keys) {
@@ -164,27 +180,47 @@ export class AdapterDenoKv extends AdapterAbstract {
164
180
  /** @inheritdoc */
165
181
  async transaction(operations) {
166
182
  this._assertInitialized();
167
- // Note: This implementation does not use Deno.Kv's atomic feature
168
- // Operations are executed sequentially
169
- const results = [];
170
- try {
183
+ const { db } = this.options;
184
+ // When the transaction contains only set/delete ops we can use Deno.Kv's
185
+ // native atomic() for true all-or-nothing semantics. A `get` inside the
186
+ // transaction breaks that — Deno.Kv has no atomic-read — so in that case
187
+ // we fall back to sequential execution (consistent with pre-existing
188
+ // behavior).
189
+ const hasGet = operations.some((op) => op.type === "get");
190
+ if (!hasGet && operations.length > 0) {
191
+ const atomic = db.atomic();
171
192
  for (const op of operations) {
172
- switch (op.type) {
173
- case "set":
174
- results.push(await this.set(op.key, op.value, op.options || {}));
175
- break;
176
- case "get":
177
- results.push(await this.get(op.key));
178
- break;
179
- case "delete":
180
- results.push(await this.delete(op.key));
181
- break;
193
+ if (op.type === "set") {
194
+ const ttl = this._resolveTtl(op.options);
195
+ const v = op.value === undefined ? null : op.value;
196
+ atomic.set(this.#denoKvKey(op.key), JSON.stringify(v), {
197
+ expireIn: ttl ? ttl * 1000 : undefined,
198
+ });
199
+ }
200
+ else if (op.type === "delete") {
201
+ atomic.delete(this.#denoKvKey(op.key));
182
202
  }
183
203
  }
204
+ const res = await atomic.commit();
205
+ const ok = !!res?.ok;
206
+ if (!ok)
207
+ throw new Error("Deno.Kv atomic transaction failed to commit");
208
+ return operations.map(() => true);
184
209
  }
185
- catch (err) {
186
- // rollback here in a real db-based adapter
187
- throw err;
210
+ // Sequential fallback — operations are NOT atomic.
211
+ const results = [];
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
+ }
188
224
  }
189
225
  return results;
190
226
  }
@@ -88,7 +88,7 @@ export class AdapterMemory extends AdapterAbstract {
88
88
  key = this._withNs(key);
89
89
  // to be consistent across adapters, keeping internally the strigified version...
90
90
  this.#store.set(key, JSON.stringify(value));
91
- const ttl = options.ttl || this.options.defaultTtl;
91
+ const ttl = this._resolveTtl(options);
92
92
  if (ttl) {
93
93
  this.#expirations.set(key, new Date(Date.now() + ttl * 1_000));
94
94
  }
@@ -107,7 +107,7 @@ export class AdapterMemory extends AdapterAbstract {
107
107
  // NOTE: even if the saved value was `undefined` it is always returned as `null`
108
108
  if (value === undefined)
109
109
  return Promise.resolve(null);
110
- return JSON.parse(value);
110
+ return Promise.resolve(JSON.parse(value));
111
111
  }
112
112
  /** @inheritdoc */
113
113
  delete(key) {
@@ -140,9 +140,7 @@ export class AdapterMemory extends AdapterAbstract {
140
140
  .toSorted();
141
141
  if (pattern === "*")
142
142
  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}$`);
143
+ const regex = this._globToRegex(pattern);
146
144
  return Promise.resolve(all.filter((key) => regex.test(key)));
147
145
  }
148
146
  /** @inheritdoc */
@@ -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;
@@ -31,7 +33,10 @@ export interface AdapterPostgresOptions extends AdapterAbstractOptions {
31
33
  *
32
34
  * @remarks
33
35
  * - Uses UPSERT (INSERT ... ON CONFLICT) for atomic set operations
34
- * - Uses PostgreSQL transactions for the `transaction()` method
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
35
40
  * - Values are stored as JSONB for efficient querying
36
41
  * - Supports automatic TTL cleanup via background timer
37
42
  * - Table schema: key (VARCHAR), value (JSONB), expires_at, created_at, updated_at
@@ -13,7 +13,10 @@ import { createClog } from "@marianmeres/clog";
13
13
  *
14
14
  * @remarks
15
15
  * - Uses UPSERT (INSERT ... ON CONFLICT) for atomic set operations
16
- * - Uses PostgreSQL transactions for the `transaction()` method
16
+ * - Uses PostgreSQL transactions for the `transaction()` method — when `db`
17
+ * is a `pg.Pool`, a single client is checked out for the duration of the
18
+ * transaction so BEGIN/COMMIT/ROLLBACK and all contained queries run on
19
+ * the same physical connection
17
20
  * - Values are stored as JSONB for efficient querying
18
21
  * - Supports automatic TTL cleanup via background timer
19
22
  * - Table schema: key (VARCHAR), value (JSONB), expires_at, created_at, updated_at
@@ -51,12 +54,19 @@ export class AdapterPostgres extends AdapterAbstract {
51
54
  if (!this.options.db) {
52
55
  throw new Error("Missing pg instance");
53
56
  }
57
+ // validate tableName — it is spliced into SQL verbatim, so guard
58
+ // against surprises. Allow optional schema prefix (one dot).
59
+ if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(this.options.tableName)) {
60
+ throw new Error(`Invalid tableName "${this.options.tableName}". Only word characters and a single "schema." prefix are allowed.`);
61
+ }
62
+ }
63
+ /** Safe slug derived from tableName for use inside other identifiers (e.g. index names). */
64
+ get #safeSlug() {
65
+ return this.options.tableName.replace(/\W/g, "_");
54
66
  }
55
67
  /** @inheritdoc */
56
68
  async initialize() {
57
69
  const { db, tableName } = this.options;
58
- // so we can work with "schema." prefix in naming things...
59
- const safe = (name) => `${name}`.replace(/\W/g, "");
60
70
  await db.query(`
61
71
  CREATE TABLE IF NOT EXISTS ${tableName} (
62
72
  key VARCHAR(512) PRIMARY KEY,
@@ -67,13 +77,13 @@ export class AdapterPostgres extends AdapterAbstract {
67
77
  )
68
78
  `);
69
79
  await db.query(`
70
- CREATE INDEX IF NOT EXISTS idx_${safe(tableName)}_expires_at
80
+ CREATE INDEX IF NOT EXISTS idx_${this.#safeSlug}_expires_at
71
81
  ON ${tableName} (expires_at)
72
82
  WHERE expires_at IS NOT NULL
73
83
  `);
74
84
  // Index for efficient prefix lookups with LIKE 'prefix%' queries
75
85
  await db.query(`
76
- CREATE INDEX IF NOT EXISTS idx_${safe(tableName)}_key_prefix
86
+ CREATE INDEX IF NOT EXISTS idx_${this.#safeSlug}_key_prefix
77
87
  ON ${tableName} (key text_pattern_ops)
78
88
  `);
79
89
  this._initialized = true;
@@ -81,12 +91,14 @@ export class AdapterPostgres extends AdapterAbstract {
81
91
  }
82
92
  /** @inheritdoc */
83
93
  async destroy(hard) {
94
+ // stop the timer first so a pending tick cannot fire during DROP
95
+ clearTimeout(this.#cleanupTimer);
96
+ this.#cleanupTimer = undefined;
84
97
  if (hard) {
85
98
  const { db, tableName } = this.options;
86
99
  await db.query(`DROP TABLE IF EXISTS ${tableName}`);
87
100
  }
88
101
  this._initialized = false;
89
- clearTimeout(this.#cleanupTimer);
90
102
  }
91
103
  async #maybeTTLCleanup() {
92
104
  clearTimeout(this.#cleanupTimer); // safety
@@ -95,7 +107,7 @@ export class AdapterPostgres extends AdapterAbstract {
95
107
  // do the cleanup now
96
108
  try {
97
109
  await db.query(`
98
- DELETE FROM ${tableName}
110
+ DELETE FROM ${tableName}
99
111
  WHERE expires_at IS NOT NULL AND expires_at <= NOW()`);
100
112
  }
101
113
  catch (err) {
@@ -105,44 +117,67 @@ export class AdapterPostgres extends AdapterAbstract {
105
117
  this.#cleanupTimer = setTimeout(this.#maybeTTLCleanup.bind(this), this.options.ttlCleanupIntervalSec * 1000);
106
118
  }
107
119
  }
108
- /** convert Redis-style pattern to PostgreSQL LIKE pattern */
120
+ /**
121
+ * Convert Redis-style glob to a PostgreSQL LIKE pattern.
122
+ * Literal `%`, `_`, and `\` are escaped with `\`; `*`/`?` become `%`/`_`.
123
+ * LIKE queries using this output must include `ESCAPE '\'` — see {@link #likeEscapeClause}.
124
+ */
109
125
  #likePattern(pattern) {
110
- return pattern.replace(/\*/g, "%").replace(/\?/g, "_");
126
+ return pattern
127
+ .replace(/([\\%_])/g, "\\$1")
128
+ .replace(/\*/g, "%")
129
+ .replace(/\?/g, "_");
130
+ }
131
+ /** Suffix to append to any LIKE clause built from {@link #likePattern}. */
132
+ #likeEscape = ` ESCAPE '\\'`;
133
+ #withNsLike(pattern) {
134
+ // namespace is a literal prefix — its own `%`/`_`/`\` must be escaped too
135
+ const ns = this.namespace.replace(/([\\%_])/g, "\\$1");
136
+ return ns + (pattern === "*" ? "%" : this.#likePattern(pattern));
111
137
  }
112
138
  /** @inheritdoc */
113
- async set(key, value, options = {}) {
139
+ set(key, value, options = {}) {
140
+ return this.#setOn(this.options.db, key, value, options);
141
+ }
142
+ async #setOn(exec, key, value, options = {}) {
114
143
  this._assertInitialized();
115
144
  key = this._withNs(key);
116
- const { db, tableName } = this.options;
117
- const ttl = options.ttl || this.options.defaultTtl;
145
+ const { tableName } = this.options;
146
+ const ttl = this._resolveTtl(options);
118
147
  const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
119
148
  // a.k.a. UPSERT
120
- await db.query(`INSERT INTO ${tableName} (key, value, expires_at, updated_at)
149
+ await exec.query(`INSERT INTO ${tableName} (key, value, expires_at, updated_at)
121
150
  VALUES ($1, $2, $3, NOW())
122
- ON CONFLICT (key) DO UPDATE SET
151
+ ON CONFLICT (key) DO UPDATE SET
123
152
  value = EXCLUDED.value,
124
153
  expires_at = EXCLUDED.expires_at,
125
154
  updated_at = NOW()`, [key, JSON.stringify(value ?? null), expiresAt]);
126
155
  return true;
127
156
  }
128
157
  /** @inheritdoc */
129
- async get(key) {
158
+ get(key) {
159
+ return this.#getOn(this.options.db, key);
160
+ }
161
+ async #getOn(exec, key) {
130
162
  this._assertInitialized();
131
163
  key = this._withNs(key);
132
- const { db, tableName } = this.options;
133
- const { rows } = await db.query(`SELECT value, expires_at
134
- FROM ${tableName}
164
+ const { tableName } = this.options;
165
+ const { rows } = await exec.query(`SELECT value, expires_at
166
+ FROM ${tableName}
135
167
  WHERE key = $1 AND (expires_at IS NULL OR expires_at > NOW())`, [key]);
136
168
  if (rows.length === 0)
137
169
  return null;
138
170
  return rows[0].value;
139
171
  }
140
172
  /** @inheritdoc */
141
- async delete(key) {
173
+ delete(key) {
174
+ return this.#deleteOn(this.options.db, key);
175
+ }
176
+ async #deleteOn(exec, key) {
142
177
  this._assertInitialized();
143
178
  key = this._withNs(key);
144
- const { db, tableName } = this.options;
145
- const { rowCount } = await db.query(`DELETE FROM ${tableName} WHERE key = $1`, [key]);
179
+ const { tableName } = this.options;
180
+ const { rowCount } = await exec.query(`DELETE FROM ${tableName} WHERE key = $1`, [key]);
146
181
  return rowCount > 0;
147
182
  }
148
183
  /** @inheritdoc */
@@ -150,7 +185,7 @@ export class AdapterPostgres extends AdapterAbstract {
150
185
  this._assertInitialized();
151
186
  key = this._withNs(key);
152
187
  const { db, tableName } = this.options;
153
- const { rows } = await db.query(`SELECT 1 FROM ${tableName}
188
+ const { rows } = await db.query(`SELECT 1 FROM ${tableName}
154
189
  WHERE key = $1 AND (expires_at IS NULL OR expires_at > NOW())`, [key]);
155
190
  return rows.length > 0;
156
191
  }
@@ -158,43 +193,26 @@ export class AdapterPostgres extends AdapterAbstract {
158
193
  async keys(pattern) {
159
194
  this._assertInitialized();
160
195
  const { db, tableName } = this.options;
161
- let params = [];
162
- const query = `
163
- SELECT key FROM ${tableName}
164
- WHERE key LIKE $1
196
+ const { rows } = await db.query(`SELECT key FROM ${tableName}
197
+ WHERE key LIKE $1${this.#likeEscape}
165
198
  AND (expires_at IS NULL OR expires_at > NOW())
166
- ORDER BY key`;
167
- if (pattern === "*") {
168
- params = [this.namespace + "%"];
169
- }
170
- else {
171
- params = [this.namespace + this.#likePattern(pattern)];
172
- }
173
- const { rows } = await db.query(query, params);
199
+ ORDER BY key`, [this.#withNsLike(pattern)]);
174
200
  return rows
175
- .map((row) => {
176
- let k = row.key;
177
- // strip namespace if exists
178
- if (this.namespace)
179
- k = k.slice(this.namespace.length);
180
- return k;
181
- })
201
+ .map((row) => this._withoutNs(row.key))
182
202
  .toSorted();
183
203
  }
184
204
  /** @inheritdoc */
185
205
  async clear(pattern) {
186
206
  this._assertInitialized();
187
207
  const { db, tableName } = this.options;
188
- const likePattern = pattern === "*"
189
- ? this.namespace + "%"
190
- : this.namespace + this.#likePattern(pattern);
208
+ const likePattern = this.#withNsLike(pattern);
191
209
  // Batch large deletions to prevent long-running transactions
192
210
  const batchSize = 10000;
193
211
  let totalDeleted = 0;
194
212
  let deleted;
195
213
  do {
196
214
  const { rowCount } = await db.query(`DELETE FROM ${tableName} WHERE key IN (
197
- SELECT key FROM ${tableName} WHERE key LIKE $1 LIMIT $2
215
+ SELECT key FROM ${tableName} WHERE key LIKE $1${this.#likeEscape} LIMIT $2
198
216
  )`, [likePattern, batchSize]);
199
217
  deleted = rowCount ?? 0;
200
218
  totalDeleted += deleted;
@@ -204,23 +222,27 @@ export class AdapterPostgres extends AdapterAbstract {
204
222
  /** @inheritdoc */
205
223
  async setMultiple(keyValuePairs, options = {}) {
206
224
  this._assertInitialized();
225
+ if (keyValuePairs.length === 0)
226
+ return [];
207
227
  const { db, tableName } = this.options;
208
- const ttl = options.ttl || this.options.defaultTtl;
228
+ const ttl = this._resolveTtl(options);
209
229
  const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
210
- const values = Object.entries(keyValuePairs)
211
- .map(([_k, _v], i) => `($${i * 3 + 1}, $${i * 3 + 2}, $${i * 3 + 3})`)
230
+ const placeholders = keyValuePairs
231
+ .map((_, i) => `($${i * 3 + 1}, $${i * 3 + 2}, $${i * 3 + 3})`)
212
232
  .join(", ");
213
- const params = keyValuePairs.reduce((m, [k, v]) => [...m, this._withNs(k), JSON.stringify(v), expiresAt], []);
233
+ const params = [];
234
+ for (const [k, v] of keyValuePairs) {
235
+ params.push(this._withNs(k), JSON.stringify(v ?? null), expiresAt);
236
+ }
214
237
  // a.k.a UPSERT
215
238
  const sql = `
216
239
  INSERT INTO ${tableName} (key, value, expires_at)
217
- VALUES ${values}
218
- ON CONFLICT (key) DO UPDATE SET
240
+ VALUES ${placeholders}
241
+ ON CONFLICT (key) DO UPDATE SET
219
242
  value = EXCLUDED.value,
220
243
  expires_at = EXCLUDED.expires_at,
221
244
  updated_at = NOW()
222
245
  `;
223
- // console.log(sql, params);
224
246
  await db.query(sql, params);
225
247
  return keyValuePairs.map(() => true);
226
248
  }
@@ -232,23 +254,21 @@ export class AdapterPostgres extends AdapterAbstract {
232
254
  const placeholders = keys.map((_, i) => `$${i + 1}`).join(", ");
233
255
  const { db, tableName } = this.options;
234
256
  const sql = `
235
- SELECT key, value
236
- FROM ${tableName}
257
+ SELECT key, value
258
+ FROM ${tableName}
237
259
  WHERE key IN (${placeholders}) AND (expires_at IS NULL OR expires_at > NOW())
238
260
  `;
239
261
  const params = keys.map((k) => this._withNs(k));
240
- // console.log(sql, params);
241
262
  const { rows } = await db.query(sql, params);
242
- const found = {};
243
- rows.forEach((row) => {
244
- const key = this._withoutNs(row.key);
245
- found[key] = row.value;
246
- });
247
- // ensure all requested keys are in the result
263
+ const found = Object.create(null);
264
+ for (const row of rows) {
265
+ found[this._withoutNs(row.key)] = row.value;
266
+ }
267
+ // preserve explicit null / false / 0 / "" — missing keys become null
248
268
  const resultMap = {};
249
- keys.forEach((key) => {
250
- resultMap[key] = found[key] || null;
251
- });
269
+ for (const key of keys) {
270
+ resultMap[key] = key in found ? found[key] : null;
271
+ }
252
272
  return resultMap;
253
273
  }
254
274
  /** @inheritdoc */
@@ -257,7 +277,7 @@ export class AdapterPostgres extends AdapterAbstract {
257
277
  key = this._withNs(key);
258
278
  const { db, tableName } = this.options;
259
279
  const expiresAt = new Date(Date.now() + ttl * 1000);
260
- const { rowCount } = await db.query(`UPDATE ${tableName}
280
+ const { rowCount } = await db.query(`UPDATE ${tableName}
261
281
  SET expires_at = $2, updated_at = NOW()
262
282
  WHERE key = $1 AND (expires_at IS NULL OR expires_at > NOW())`, [key, expiresAt]);
263
283
  return rowCount > 0;
@@ -277,40 +297,69 @@ export class AdapterPostgres extends AdapterAbstract {
277
297
  return null;
278
298
  return new Date(expiresAt);
279
299
  }
300
+ /**
301
+ * Acquire a single pinned connection for a transaction.
302
+ *
303
+ * If `db` is a `pg.Pool`, a client is checked out and a `release` callback
304
+ * is returned. If `db` is already a `pg.Client`, it is used directly and
305
+ * `release` is a no-op.
306
+ */
307
+ async #acquireClient() {
308
+ const { db } = this.options;
309
+ // pg.Pool exposes `totalCount`; pg.Client does not.
310
+ if (typeof db.totalCount === "number" && typeof db.connect === "function") {
311
+ const client = await db.connect();
312
+ return { client, release: () => client.release() };
313
+ }
314
+ return { client: db, release: () => { } };
315
+ }
280
316
  /** @inheritdoc */
281
317
  async transaction(operations) {
282
318
  this._assertInitialized();
283
- const { db, logger } = this.options;
319
+ const { logger } = this.options;
320
+ const { client, release } = await this.#acquireClient();
284
321
  const results = [];
285
- await db.query("BEGIN");
286
322
  try {
287
- for (const op of operations) {
288
- switch (op.type) {
289
- case "set":
290
- results.push(await this.set(op.key, op.value, op.options || {}));
291
- break;
292
- case "get":
293
- results.push(await this.get(op.key));
294
- break;
295
- case "delete":
296
- results.push(await this.delete(op.key));
297
- break;
323
+ await client.query("BEGIN");
324
+ try {
325
+ for (const op of operations) {
326
+ switch (op.type) {
327
+ case "set":
328
+ results.push(await this.#setOn(client, op.key, op.value, op.options || {}));
329
+ break;
330
+ case "get":
331
+ results.push(await this.#getOn(client, op.key));
332
+ break;
333
+ case "delete":
334
+ results.push(await this.#deleteOn(client, op.key));
335
+ break;
336
+ }
337
+ }
338
+ await client.query("COMMIT");
339
+ }
340
+ catch (err) {
341
+ try {
342
+ await client.query("ROLLBACK");
343
+ }
344
+ catch (rollbackErr) {
345
+ // Rollback failure is a real problem — surface it even though
346
+ // we re-throw the original error below.
347
+ logger?.error?.(`Rollback failed: ${rollbackErr}`);
298
348
  }
349
+ // Do NOT log `err` here — we're re-throwing it; the caller will
350
+ // see it. Double-logging is just noise.
351
+ throw err;
299
352
  }
300
- await db.query("COMMIT");
301
353
  }
302
- catch (err) {
303
- await db.query("ROLLBACK");
304
- logger?.error?.(err);
305
- throw err;
354
+ finally {
355
+ release();
306
356
  }
307
357
  return results;
308
358
  }
309
359
  async __debug_dump() {
310
360
  this._assertInitialized();
311
361
  const { db, tableName } = this.options;
312
- const { rows } = await db.query(`SELECT key, value, expires_at FROM ${tableName} WHERE key LIKE $1`, [this.namespace + "%"]);
313
- // console.log(12312, rows);
362
+ const { rows } = await db.query(`SELECT key, value, expires_at FROM ${tableName} WHERE key LIKE $1${this.#likeEscape}`, [this.#withNsLike("*")]);
314
363
  return rows.reduce((m, row) => {
315
364
  m[this._withoutNs(row.key)] = {
316
365
  value: row.value,
@@ -46,6 +46,7 @@ export interface AdapterRedisOptions extends AdapterAbstractOptions {
46
46
  * ```
47
47
  */
48
48
  export declare class AdapterRedis extends AdapterAbstract {
49
+ #private;
49
50
  readonly namespace: string;
50
51
  _type: string;
51
52
  readonly options: AdapterRedisOptions;
@@ -51,30 +51,58 @@ export class AdapterRedis extends AdapterAbstract {
51
51
  throw new Error("Missing redis db client instance");
52
52
  }
53
53
  }
54
+ #errorListener;
55
+ #weOpened = false;
54
56
  /** @inheritdoc */
55
57
  async initialize() {
56
58
  const { db, logger } = this.options;
57
- db.on("error", (err) => logger?.error?.(err));
59
+ // avoid stacking listeners across repeated initialize() calls
60
+ if (this.#errorListener) {
61
+ db.off?.("error", this.#errorListener);
62
+ }
63
+ this.#errorListener = (err) => logger?.error?.(err);
64
+ db.on("error", this.#errorListener);
58
65
  // the pool instance doesn't have connect, so being defensive...
59
- if (!db.isOpen)
66
+ if (!db.isOpen) {
60
67
  await db?.connect();
68
+ this.#weOpened = true;
69
+ }
61
70
  this._initialized = true;
62
71
  }
63
72
  /** @inheritdoc */
64
- destroy(_hard) {
73
+ async destroy(_hard) {
65
74
  this._initialized = false;
66
- return Promise.resolve();
75
+ const { db } = this.options;
76
+ if (this.#errorListener) {
77
+ db.off?.("error", this.#errorListener);
78
+ this.#errorListener = undefined;
79
+ }
80
+ // Only close a connection we opened ourselves — if the caller opened the
81
+ // client before passing it in, they own the lifecycle. `quit` is the
82
+ // graceful path; it is missing on the pool, so be defensive.
83
+ if (this.#weOpened && db?.isOpen) {
84
+ const quit = db.quit ?? db.close;
85
+ if (typeof quit === "function") {
86
+ try {
87
+ await quit.call(db);
88
+ }
89
+ catch {
90
+ // ignore — caller may have already closed it
91
+ }
92
+ }
93
+ this.#weOpened = false;
94
+ }
67
95
  }
68
96
  /** @inheritdoc */
69
97
  async set(key, value, options = {}) {
70
98
  this._assertInitialized();
71
99
  key = this._withNs(key);
72
100
  const { db } = this.options;
73
- const ttl = options.ttl || this.options.defaultTtl || undefined;
101
+ const ttl = this._resolveTtl(options);
74
102
  if (value === undefined)
75
103
  value = null; // redis does not accept undefined
76
104
  value = JSON.stringify(value);
77
- const r = await db.set(key, value, { EX: ttl });
105
+ const r = await db.set(key, value, ttl ? { EX: ttl } : {});
78
106
  return r === "OK";
79
107
  }
80
108
  /** @inheritdoc */
@@ -151,11 +179,11 @@ export class AdapterRedis extends AdapterAbstract {
151
179
  async setMultiple(keyValuePairs, options = {}) {
152
180
  this._assertInitialized();
153
181
  const { db } = this.options;
154
- const ttl = options.ttl || this.options.defaultTtl || undefined;
182
+ const ttl = this._resolveTtl(options);
155
183
  const pipeline = db.multi();
156
184
  for (let [key, value] of keyValuePairs) {
157
185
  key = this._withNs(key);
158
- pipeline.set(key, JSON.stringify(value), { EX: ttl });
186
+ pipeline.set(key, JSON.stringify(value), ttl ? { EX: ttl } : {});
159
187
  }
160
188
  const res = await pipeline.exec();
161
189
  return res.map((v) => String(v) === "OK");
@@ -212,9 +240,12 @@ export class AdapterRedis extends AdapterAbstract {
212
240
  for (const op of operations) {
213
241
  const key = this._withNs(op.key);
214
242
  switch (op.type) {
215
- case "set":
216
- multi.set(key, JSON.stringify(op.value));
243
+ case "set": {
244
+ const ttl = this._resolveTtl(op.options);
245
+ const val = op.value === undefined ? null : op.value;
246
+ multi.set(key, JSON.stringify(val), ttl ? { EX: ttl } : {});
217
247
  break;
248
+ }
218
249
  case "get":
219
250
  multi.get(key);
220
251
  break;
@@ -250,10 +281,18 @@ export class AdapterRedis extends AdapterAbstract {
250
281
  async __debug_dump() {
251
282
  this._assertInitialized();
252
283
  const { db } = this.options;
253
- const keys = (await db.keys("*")).toSorted();
284
+ // SCAN scoped to this namespace — do not touch foreign tenants
285
+ const match = this.namespace + "*";
286
+ const nsKeys = [];
287
+ let cursor = "0";
288
+ do {
289
+ const r = await db.scan(cursor, { MATCH: match, COUNT: 500 });
290
+ cursor = `${r.cursor}`;
291
+ nsKeys.push(...r.keys.map((k) => String(k)));
292
+ } while (cursor !== "0");
293
+ const keys = nsKeys.map((k) => this._withoutNs(k)).toSorted();
254
294
  const out = {};
255
- for (const _key of keys) {
256
- const key = this._withoutNs(String(_key));
295
+ for (const key of keys) {
257
296
  out[key] = {
258
297
  value: await this.get(key),
259
298
  ttl: await this.ttl(key),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marianmeres/kv",
3
- "version": "1.3.1",
3
+ "version": "2.1.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.15.0",
17
- "@types/pg": "^8.16.0",
25
+ "@marianmeres/clog": "^3.17.0",
26
+ "@types/pg": "^8.20.0",
18
27
  "@types/redis": "^4.0.10",
19
- "pg": "^8.17.1",
20
- "redis": "^5.10.0"
28
+ "pg": "^8.20.0",
29
+ "redis": "^5.12.1"
21
30
  },
22
31
  "repository": {
23
32
  "type": "git",