@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 +49 -46
- package/API.md +43 -5
- package/CLAUDE.md +3 -0
- package/README.md +68 -7
- package/dist/adapter/abstract.d.ts +19 -0
- package/dist/adapter/abstract.js +30 -1
- package/dist/adapter/deno-kv.js +69 -33
- package/dist/adapter/memory.js +3 -5
- package/dist/adapter/postgres.d.ts +6 -1
- package/dist/adapter/postgres.js +134 -85
- package/dist/adapter/redis.d.ts +1 -0
- package/dist/adapter/redis.js +52 -13
- package/package.json +14 -5
package/AGENTS.md
CHANGED
|
@@ -1,50 +1,65 @@
|
|
|
1
|
-
# @marianmeres/kv
|
|
1
|
+
# @marianmeres/kv — Agent Guide
|
|
2
2
|
|
|
3
3
|
Machine-friendly reference for AI agents working with this codebase.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Quick Reference
|
|
6
6
|
|
|
7
|
-
- **
|
|
8
|
-
- **
|
|
9
|
-
- **
|
|
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
|
-
##
|
|
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
|
|
31
|
-
├── kv.ts
|
|
19
|
+
├── mod.ts — Main entry point (re-exports kv.ts)
|
|
20
|
+
├── kv.ts — Factory function and all exports
|
|
32
21
|
├── adapter/
|
|
33
|
-
│ ├── abstract.ts
|
|
34
|
-
│ ├── memory.ts
|
|
35
|
-
│ ├── redis.ts
|
|
36
|
-
│ ├── postgres.ts
|
|
37
|
-
│ └── deno-kv.ts
|
|
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
|
|
28
|
+
└── sleep.ts — Sleep utility function
|
|
40
29
|
|
|
41
30
|
tests/
|
|
42
|
-
├── kv.test.ts
|
|
43
|
-
├── _tests-runner.ts
|
|
44
|
-
├── _redis.ts
|
|
45
|
-
└── _pg.ts
|
|
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.
|
|
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
|
-
|
|
406
|
-
|
|
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
|
-
|
|
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
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
|
|
69
|
-
- **`ttl()`**: Not supported
|
|
70
|
-
- **
|
|
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
|
-
-
|
|
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
|
*
|
package/dist/adapter/abstract.js
CHANGED
|
@@ -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
|
-
|
|
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
|
*
|
package/dist/adapter/deno-kv.js
CHANGED
|
@@ -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 =
|
|
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
|
-
|
|
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 [
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
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
|
-
//
|
|
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 (
|
|
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
|
-
|
|
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
|
-
|
|
148
|
-
|
|
161
|
+
const v = value === undefined ? null : value;
|
|
162
|
+
atomic.set(this.#denoKvKey(key), JSON.stringify(v), { expireIn });
|
|
149
163
|
}
|
|
150
|
-
|
|
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
|
-
|
|
168
|
-
//
|
|
169
|
-
|
|
170
|
-
|
|
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
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
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
|
-
|
|
186
|
-
|
|
187
|
-
|
|
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
|
}
|
package/dist/adapter/memory.js
CHANGED
|
@@ -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 =
|
|
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
|
-
|
|
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
|
package/dist/adapter/postgres.js
CHANGED
|
@@ -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_${
|
|
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_${
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
|
|
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 {
|
|
117
|
-
const ttl =
|
|
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
|
|
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
|
-
|
|
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 {
|
|
133
|
-
const { rows } = await
|
|
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
|
-
|
|
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 {
|
|
145
|
-
const { rowCount } = await
|
|
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
|
-
|
|
162
|
-
|
|
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 =
|
|
228
|
+
const ttl = this._resolveTtl(options);
|
|
209
229
|
const expiresAt = ttl ? new Date(Date.now() + ttl * 1000) : null;
|
|
210
|
-
const
|
|
211
|
-
.map((
|
|
230
|
+
const placeholders = keyValuePairs
|
|
231
|
+
.map((_, i) => `($${i * 3 + 1}, $${i * 3 + 2}, $${i * 3 + 3})`)
|
|
212
232
|
.join(", ");
|
|
213
|
-
const params =
|
|
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 ${
|
|
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
|
-
|
|
244
|
-
|
|
245
|
-
|
|
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
|
-
|
|
250
|
-
resultMap[key] = found[key]
|
|
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 {
|
|
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
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
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
|
-
|
|
303
|
-
|
|
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
|
|
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,
|
package/dist/adapter/redis.d.ts
CHANGED
package/dist/adapter/redis.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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 =
|
|
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 =
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
+
"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.
|
|
17
|
-
"@types/pg": "^8.
|
|
25
|
+
"@marianmeres/clog": "^3.17.0",
|
|
26
|
+
"@types/pg": "^8.20.0",
|
|
18
27
|
"@types/redis": "^4.0.10",
|
|
19
|
-
"pg": "^8.
|
|
20
|
-
"redis": "^5.
|
|
28
|
+
"pg": "^8.20.0",
|
|
29
|
+
"redis": "^5.12.1"
|
|
21
30
|
},
|
|
22
31
|
"repository": {
|
|
23
32
|
"type": "git",
|