@marianmeres/kv 2.4.0 → 3.0.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 +85 -54
- package/API.md +151 -209
- package/README.md +69 -42
- package/dist/adapter/abstract.d.ts +6 -17
- package/dist/adapter/abstract.js +10 -24
- package/dist/adapter/memory.d.ts +2 -3
- package/dist/adapter/memory.js +2 -5
- package/dist/adapter/postgres.d.ts +1 -2
- package/dist/adapter/postgres.js +5 -6
- package/dist/adapter/redis.d.ts +1 -2
- package/dist/adapter/redis.js +4 -7
- package/dist/{mod.d.ts → index.d.ts} +1 -2
- package/dist/{mod.js → index.js} +0 -1
- package/dist/kv.d.ts +9 -22
- package/dist/kv.js +3 -18
- package/dist/utils/sleep.d.ts +1 -1
- package/dist/utils/sleep.js +2 -2
- package/package.json +70 -37
- package/CLAUDE.md +0 -3
- package/dist/adapter/deno-kv.d.ts +0 -107
- package/dist/adapter/deno-kv.js +0 -396
package/README.md
CHANGED
|
@@ -5,42 +5,41 @@
|
|
|
5
5
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
|
|
7
7
|
Key-value storage abstraction layer with support for multiple backend adapters:
|
|
8
|
-
- redis
|
|
8
|
+
- redis
|
|
9
9
|
- postgresql
|
|
10
10
|
- memory
|
|
11
|
-
- Deno KV (only in Deno runtime)
|
|
12
11
|
|
|
13
12
|
The API is inspired by the Redis API.
|
|
14
13
|
|
|
15
14
|
## Installation
|
|
16
15
|
|
|
17
|
-
```
|
|
18
|
-
|
|
16
|
+
```sh
|
|
17
|
+
npm install @marianmeres/kv # or pnpm add
|
|
18
|
+
deno add jsr:@marianmeres/kv # Deno
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
```
|
|
21
|
+
The `redis` and `postgres` adapters take a client you create yourself (`redis`, `pg`).
|
|
22
|
+
Requires Node >= 24.12.
|
|
24
23
|
|
|
25
24
|
## Usage
|
|
26
25
|
|
|
27
26
|
```typescript
|
|
28
|
-
import { createKVClient } from
|
|
27
|
+
import { createKVClient } from "@marianmeres/kv";
|
|
29
28
|
|
|
30
29
|
// Basic usage with memory adapter (default)
|
|
31
30
|
const client = createKVClient("my-app-namespace:");
|
|
32
31
|
|
|
33
32
|
// Or specify a different adapter type
|
|
34
33
|
const redisClient = createKVClient(
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
34
|
+
"my-app-namespace:",
|
|
35
|
+
"redis", // 'redis' | 'postgres' | 'memory'
|
|
36
|
+
{ db: myRedisClient }, // adapter-specific options
|
|
38
37
|
);
|
|
39
38
|
|
|
40
39
|
// Use the client
|
|
41
|
-
await client.set(
|
|
42
|
-
await client.get(
|
|
43
|
-
await client.keys(
|
|
40
|
+
await client.set("my:foo:key", { my: "value" });
|
|
41
|
+
await client.get("my:foo:key"); // { my: "value" }
|
|
42
|
+
await client.keys("my:*"); // ['my:foo:key']
|
|
44
43
|
```
|
|
45
44
|
|
|
46
45
|
**Important**: Namespace must end with a colon (`:`) or be an empty string.
|
|
@@ -83,9 +82,9 @@ client.ttl(key: string): Promise<TtlResult>
|
|
|
83
82
|
|
|
84
83
|
```typescript
|
|
85
84
|
type TtlResult =
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
85
|
+
| { state: "missing" }
|
|
86
|
+
| { state: "no-ttl" }
|
|
87
|
+
| { state: "expires"; at: Date };
|
|
89
88
|
```
|
|
90
89
|
|
|
91
90
|
## Pattern Syntax
|
|
@@ -98,51 +97,59 @@ type TtlResult =
|
|
|
98
97
|
|
|
99
98
|
## Adapter Feature Matrix
|
|
100
99
|
|
|
101
|
-
| Feature
|
|
102
|
-
|
|
103
|
-
| Persistent
|
|
104
|
-
| TTL on `set()`
|
|
105
|
-
| `ttl()` → `expires`/`no-ttl`/`missing`
|
|
106
|
-
| `expire()`
|
|
107
|
-
| Atomic `setIfAbsent` / `incr` / `decr` / `cas` / `getSet` |
|
|
108
|
-
| Sorted `keys()`
|
|
109
|
-
| Streaming `keysIter()`
|
|
110
|
-
| Per-pair TTL in `setMultiple`
|
|
111
|
-
| Atomic `transaction()`
|
|
112
|
-
| `delete()` returns real existed-flag
|
|
113
|
-
| Background TTL cleanup
|
|
114
|
-
| `keys()` / `clear()`
|
|
100
|
+
| Feature | Memory | Redis | PostgreSQL |
|
|
101
|
+
| --------------------------------------------------------- | :-----------------: | :--------------------: | :--------------: |
|
|
102
|
+
| Persistent | ✗ | ✓ | ✓ |
|
|
103
|
+
| TTL on `set()` | ✓ | ✓ | ✓ |
|
|
104
|
+
| `ttl()` → `expires`/`no-ttl`/`missing` | ✓ | ✓ | ✓ |
|
|
105
|
+
| `expire()` | ✓ | ✓ | ✓ |
|
|
106
|
+
| Atomic `setIfAbsent` / `incr` / `decr` / `cas` / `getSet` | ✓ | ✓ (Lua) | ✓ (UPSERT) |
|
|
107
|
+
| Sorted `keys()` | ✓ | ✓ | ✓ |
|
|
108
|
+
| Streaming `keysIter()` | ✓ | ✓ (SCAN) | ✓ (cursor) |
|
|
109
|
+
| Per-pair TTL in `setMultiple` | ✓ | ✓ | ✓ |
|
|
110
|
+
| Atomic `transaction()` | ✓ (single-threaded) | ✓ (MULTI) | ✓ (BEGIN/COMMIT) |
|
|
111
|
+
| `delete()` returns real existed-flag | ✓ | ✓ | ✓ |
|
|
112
|
+
| Background TTL cleanup | optional | native (Redis does it) | optional |
|
|
113
|
+
| `keys()` / `clear()` | ✓ | ✓ (non-cluster only) | ✓ |
|
|
115
114
|
|
|
116
115
|
## Adapter-Specific Limitations
|
|
117
116
|
|
|
118
|
-
### Deno KV
|
|
119
|
-
- **`delete()`**: Always returns `true`, even for non-existent keys (Deno.Kv limitation)
|
|
120
|
-
- **`expire()`**: Not supported — always returns `false`
|
|
121
|
-
- **`ttl()`**: Not supported — always returns `null`
|
|
122
|
-
- **`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.
|
|
123
|
-
- **Note**: TTL can be set during `set()`, but cannot be queried or modified after.
|
|
124
|
-
|
|
125
117
|
### Redis
|
|
118
|
+
|
|
126
119
|
- **`keys()` and `clear()`**: Not supported in cluster mode (throws error)
|
|
127
120
|
- **Namespace**: Required (cannot be empty string)
|
|
128
121
|
- **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.
|
|
129
122
|
|
|
130
123
|
### PostgreSQL
|
|
124
|
+
|
|
131
125
|
- Creates a table (default: `__kv`) in your database.
|
|
132
126
|
- `tableName` must match `^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$` (word chars plus an optional `schema.` prefix).
|
|
133
127
|
- `transaction()` pins a single connection from the Pool for the whole BEGIN/…/COMMIT block — safe to call against a `pg.Pool`.
|
|
134
128
|
- Supports optional TTL cleanup via `ttlCleanupIntervalSec` option.
|
|
135
129
|
|
|
136
130
|
### Memory
|
|
131
|
+
|
|
137
132
|
- Data is not persisted (in-memory only).
|
|
138
133
|
- Supports optional TTL cleanup via `ttlCleanupIntervalSec` option.
|
|
139
134
|
|
|
140
|
-
## Breaking Changes (
|
|
135
|
+
## Breaking Changes (3.0.0)
|
|
141
136
|
|
|
142
|
-
|
|
137
|
+
- **The Deno KV adapter is removed.** `"deno-kv"` is no longer an adapter type, and
|
|
138
|
+
`AdapterDenoKv`, `AdapterDenoKvOptions` and `KvRaceError` (only Deno KV threw it) are no
|
|
139
|
+
longer exported. Deno KV has no equivalent outside the Deno runtime. Stay on 2.x if you
|
|
140
|
+
depend on it, or move to the `redis`, `postgres` or `memory` adapter.
|
|
141
|
+
- The npm package now declares **Node >= 24.12** (`engines`). The memory, Redis and
|
|
142
|
+
PostgreSQL adapters behave exactly as in 2.4.
|
|
143
|
+
- The JSR package now resolves `@marianmeres/clog`, `pg` and `redis` from npm instead of
|
|
144
|
+
JSR.
|
|
143
145
|
|
|
144
|
-
|
|
146
|
+
## Changes in 2.2.0
|
|
147
|
+
|
|
148
|
+
Shipped as a minor release, although the first two items are breaking:
|
|
149
|
+
|
|
150
|
+
**Breaking:**
|
|
145
151
|
- **`ttl(key)` now returns a discriminated `TtlResult`** — `{ state: "missing" | "no-ttl" | "expires", at? }` — instead of `Date | null | false`. Migration:
|
|
152
|
+
|
|
146
153
|
```ts
|
|
147
154
|
// before
|
|
148
155
|
const t = await client.ttl(k);
|
|
@@ -160,7 +167,7 @@ Since 2.0, the following changes are in this tree:
|
|
|
160
167
|
```
|
|
161
168
|
- **Key validation is on by default.** Non-empty strings, no `\0`, total `namespace + key` length ≤ 512. Set `validateKeys: false` on the adapter options to opt out. Previous behavior silently accepted empty/overlong keys and let the backend error cryptically.
|
|
162
169
|
|
|
163
|
-
**
|
|
170
|
+
**Additive:**
|
|
164
171
|
- New methods `setIfAbsent`, `incr`, `decr`, `getSet`, `cas`, `keysIter` on every adapter.
|
|
165
172
|
- `setMultiple` accepts `{ key, value, ttl? }[]` entries in addition to the legacy `[key, value][]` tuples. Per-pair `ttl` overrides batch `options.ttl`.
|
|
166
173
|
- Deno KV: new `strictDeleteResult: true` option pre-checks existence so `delete()` returns the real did-it-exist flag (default stays `true` for BC).
|
|
@@ -202,6 +209,26 @@ but a few change semantics in ways that could affect existing code:
|
|
|
202
209
|
|
|
203
210
|
For complete API documentation including all methods, types, and adapter-specific options, see [API.md](API.md).
|
|
204
211
|
|
|
212
|
+
## Development
|
|
213
|
+
|
|
214
|
+
Node LTS (`.node-version`), pnpm, Biome, `node:test`. The source is erasable-only
|
|
215
|
+
TypeScript that Node runs directly; `dist/` is built only for publishing.
|
|
216
|
+
|
|
217
|
+
Every test runs against all three adapters, so `pnpm test` needs a running PostgreSQL and
|
|
218
|
+
Redis. Copy `.env.example` to `.env` and fill in the connection details. Redis keys in the
|
|
219
|
+
target database are deleted before each test, so point it at a scratch database (the
|
|
220
|
+
default is `/13`).
|
|
221
|
+
|
|
222
|
+
| Command | Does |
|
|
223
|
+
| ----------------------------------- | -------------------------------------------------- |
|
|
224
|
+
| `pnpm install` | installs dependencies and dev tooling |
|
|
225
|
+
| `pnpm test` / `pnpm run test:watch` | `node --test` over `tests/**/*.test.ts` |
|
|
226
|
+
| `pnpm run typecheck` | `tsc --noEmit` over `src` and `tests` |
|
|
227
|
+
| `pnpm run lint` / `pnpm run format` | `biome check .` read-only / with `--write` |
|
|
228
|
+
| `pnpm run ci` | typecheck + lint + test, what CI runs |
|
|
229
|
+
| `pnpm run build` | `tsc -p tsconfig.build.json` → `dist/` |
|
|
230
|
+
| `pnpm run rp` / `pnpm run rpm` | patch / minor release, then publish to npm and JSR |
|
|
231
|
+
|
|
205
232
|
## License
|
|
206
233
|
|
|
207
234
|
[MIT](LICENSE)
|
|
@@ -15,7 +15,7 @@ export interface SetOptions extends Record<string, any> {
|
|
|
15
15
|
* Information about the adapter instance.
|
|
16
16
|
*/
|
|
17
17
|
export interface AdapterInfo {
|
|
18
|
-
/** The adapter type identifier (e.g., "redis", "postgres", "memory"
|
|
18
|
+
/** The adapter type identifier (e.g., "redis", "postgres", "memory"). */
|
|
19
19
|
type: string;
|
|
20
20
|
}
|
|
21
21
|
/**
|
|
@@ -73,13 +73,6 @@ export type TtlResult = {
|
|
|
73
73
|
state: "expires";
|
|
74
74
|
at: Date;
|
|
75
75
|
};
|
|
76
|
-
/**
|
|
77
|
-
* Thrown when a CAS-based atomic primitive (e.g. Deno KV `incr`/`cas`)
|
|
78
|
-
* exhausts its retry budget due to contention on the key.
|
|
79
|
-
*/
|
|
80
|
-
export declare class KvRaceError extends Error {
|
|
81
|
-
constructor(message: string);
|
|
82
|
-
}
|
|
83
76
|
/**
|
|
84
77
|
* Abstract base class for all KV storage adapters.
|
|
85
78
|
*
|
|
@@ -96,8 +89,8 @@ export declare class KvRaceError extends Error {
|
|
|
96
89
|
* ```
|
|
97
90
|
*/
|
|
98
91
|
export declare abstract class AdapterAbstract {
|
|
99
|
-
readonly namespace: string;
|
|
100
92
|
protected _type: string;
|
|
93
|
+
readonly namespace: string;
|
|
101
94
|
readonly options: AdapterAbstractOptions;
|
|
102
95
|
protected _initialized: boolean;
|
|
103
96
|
/**
|
|
@@ -236,8 +229,7 @@ export declare abstract class AdapterAbstract {
|
|
|
236
229
|
*
|
|
237
230
|
* @param key - The key to delete.
|
|
238
231
|
* @returns A promise that resolves to `true` if the key existed and was deleted,
|
|
239
|
-
* `false` if the key didn't exist.
|
|
240
|
-
* the adapter was created with `strictDeleteResult: true`.
|
|
232
|
+
* `false` if the key didn't exist.
|
|
241
233
|
*
|
|
242
234
|
* @example
|
|
243
235
|
* ```typescript
|
|
@@ -348,7 +340,7 @@ export declare abstract class AdapterAbstract {
|
|
|
348
340
|
* Executes multiple operations within a single transaction.
|
|
349
341
|
*
|
|
350
342
|
* For adapters that support it (Redis, PostgreSQL), operations are atomic.
|
|
351
|
-
* For memory
|
|
343
|
+
* For memory, operations are executed sequentially.
|
|
352
344
|
*
|
|
353
345
|
* @param operations - An array of operations to execute.
|
|
354
346
|
* @returns A promise that resolves to an array of results for each operation.
|
|
@@ -370,7 +362,7 @@ export declare abstract class AdapterAbstract {
|
|
|
370
362
|
* @param key - The key to set expiration on.
|
|
371
363
|
* @param ttl - Time-to-live in seconds from now.
|
|
372
364
|
* @returns A promise that resolves to `true` if the expiration was set,
|
|
373
|
-
* `false` if the key doesn't exist.
|
|
365
|
+
* `false` if the key doesn't exist.
|
|
374
366
|
*
|
|
375
367
|
* @example
|
|
376
368
|
* ```typescript
|
|
@@ -391,9 +383,6 @@ export declare abstract class AdapterAbstract {
|
|
|
391
383
|
* case "missing": console.log("key not found"); break;
|
|
392
384
|
* }
|
|
393
385
|
* ```
|
|
394
|
-
*
|
|
395
|
-
* Note: Deno KV cannot report TTL state — always returns `{ state: "no-ttl" }`
|
|
396
|
-
* for existing keys and `{ state: "missing" }` for absent ones.
|
|
397
386
|
*/
|
|
398
387
|
ttl(key: string): Promise<TtlResult>;
|
|
399
388
|
/**
|
|
@@ -404,7 +393,7 @@ export declare abstract class AdapterAbstract {
|
|
|
404
393
|
* @example
|
|
405
394
|
* ```typescript
|
|
406
395
|
* const info = client.info();
|
|
407
|
-
* console.log(info.type); // "redis", "postgres",
|
|
396
|
+
* console.log(info.type); // "redis", "postgres", or "memory"
|
|
408
397
|
* ```
|
|
409
398
|
*/
|
|
410
399
|
info(): AdapterInfo;
|
package/dist/adapter/abstract.js
CHANGED
|
@@ -3,16 +3,6 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Abstract base class and shared types for all KV adapters.
|
|
5
5
|
*/
|
|
6
|
-
/**
|
|
7
|
-
* Thrown when a CAS-based atomic primitive (e.g. Deno KV `incr`/`cas`)
|
|
8
|
-
* exhausts its retry budget due to contention on the key.
|
|
9
|
-
*/
|
|
10
|
-
export class KvRaceError extends Error {
|
|
11
|
-
constructor(message) {
|
|
12
|
-
super(message);
|
|
13
|
-
this.name = "KvRaceError";
|
|
14
|
-
}
|
|
15
|
-
}
|
|
16
6
|
function notImplemented() {
|
|
17
7
|
throw new Error("Not implemented");
|
|
18
8
|
}
|
|
@@ -32,8 +22,8 @@ function notImplemented() {
|
|
|
32
22
|
* ```
|
|
33
23
|
*/
|
|
34
24
|
export class AdapterAbstract {
|
|
35
|
-
namespace;
|
|
36
25
|
_type = "abstract";
|
|
26
|
+
namespace;
|
|
37
27
|
options = {
|
|
38
28
|
defaultTtl: 0,
|
|
39
29
|
validateKeys: true,
|
|
@@ -50,10 +40,10 @@ export class AdapterAbstract {
|
|
|
50
40
|
constructor(namespace = "", options = {}) {
|
|
51
41
|
this.namespace = namespace;
|
|
52
42
|
this.options = { ...this.options, ...(options || {}) };
|
|
53
|
-
|
|
54
|
-
//
|
|
55
|
-
//
|
|
56
|
-
//
|
|
43
|
+
this._assertValidNamespace();
|
|
44
|
+
// NOTE: subclasses re-declare `options` with a field initializer, which
|
|
45
|
+
// replaces the value set here once `super()` returns — so each subclass
|
|
46
|
+
// merges its own options again in its constructor.
|
|
57
47
|
}
|
|
58
48
|
_assertInitialized() {
|
|
59
49
|
if (!this._initialized) {
|
|
@@ -114,7 +104,7 @@ export class AdapterAbstract {
|
|
|
114
104
|
* Normalizes the polymorphic `setMultiple` input to a single shape.
|
|
115
105
|
*/
|
|
116
106
|
_normalizePairs(entries) {
|
|
117
|
-
return entries.map((e) => Array.isArray(e) ? { key: e[0], value: e[1] } : e);
|
|
107
|
+
return entries.map((e) => (Array.isArray(e) ? { key: e[0], value: e[1] } : e));
|
|
118
108
|
}
|
|
119
109
|
/**
|
|
120
110
|
* Stores a key-value pair in the storage.
|
|
@@ -206,8 +196,7 @@ export class AdapterAbstract {
|
|
|
206
196
|
*
|
|
207
197
|
* @param key - The key to delete.
|
|
208
198
|
* @returns A promise that resolves to `true` if the key existed and was deleted,
|
|
209
|
-
* `false` if the key didn't exist.
|
|
210
|
-
* the adapter was created with `strictDeleteResult: true`.
|
|
199
|
+
* `false` if the key didn't exist.
|
|
211
200
|
*
|
|
212
201
|
* @example
|
|
213
202
|
* ```typescript
|
|
@@ -332,7 +321,7 @@ export class AdapterAbstract {
|
|
|
332
321
|
* Executes multiple operations within a single transaction.
|
|
333
322
|
*
|
|
334
323
|
* For adapters that support it (Redis, PostgreSQL), operations are atomic.
|
|
335
|
-
* For memory
|
|
324
|
+
* For memory, operations are executed sequentially.
|
|
336
325
|
*
|
|
337
326
|
* @param operations - An array of operations to execute.
|
|
338
327
|
* @returns A promise that resolves to an array of results for each operation.
|
|
@@ -356,7 +345,7 @@ export class AdapterAbstract {
|
|
|
356
345
|
* @param key - The key to set expiration on.
|
|
357
346
|
* @param ttl - Time-to-live in seconds from now.
|
|
358
347
|
* @returns A promise that resolves to `true` if the expiration was set,
|
|
359
|
-
* `false` if the key doesn't exist.
|
|
348
|
+
* `false` if the key doesn't exist.
|
|
360
349
|
*
|
|
361
350
|
* @example
|
|
362
351
|
* ```typescript
|
|
@@ -379,9 +368,6 @@ export class AdapterAbstract {
|
|
|
379
368
|
* case "missing": console.log("key not found"); break;
|
|
380
369
|
* }
|
|
381
370
|
* ```
|
|
382
|
-
*
|
|
383
|
-
* Note: Deno KV cannot report TTL state — always returns `{ state: "no-ttl" }`
|
|
384
|
-
* for existing keys and `{ state: "missing" }` for absent ones.
|
|
385
371
|
*/
|
|
386
372
|
ttl(key) {
|
|
387
373
|
return notImplemented();
|
|
@@ -394,7 +380,7 @@ export class AdapterAbstract {
|
|
|
394
380
|
* @example
|
|
395
381
|
* ```typescript
|
|
396
382
|
* const info = client.info();
|
|
397
|
-
* console.log(info.type); // "redis", "postgres",
|
|
383
|
+
* console.log(info.type); // "redis", "postgres", or "memory"
|
|
398
384
|
* ```
|
|
399
385
|
*/
|
|
400
386
|
info() {
|
package/dist/adapter/memory.d.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*
|
|
4
4
|
* In-memory key-value storage adapter implementation.
|
|
5
5
|
*/
|
|
6
|
-
import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult } from "./abstract.
|
|
6
|
+
import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult } from "./abstract.ts";
|
|
7
7
|
/**
|
|
8
8
|
* Configuration options for the in-memory KV adapter.
|
|
9
9
|
*/
|
|
@@ -24,7 +24,7 @@ export interface AdapterMemoryOptions extends AdapterAbstractOptions {
|
|
|
24
24
|
* @remarks
|
|
25
25
|
* - Fast and simple, ideal for testing and caching
|
|
26
26
|
* - Supports TTL with optional automatic cleanup
|
|
27
|
-
* - Thread-safe within a single
|
|
27
|
+
* - Thread-safe within a single process
|
|
28
28
|
* - Not suitable for multi-process or distributed environments
|
|
29
29
|
*
|
|
30
30
|
* @example
|
|
@@ -39,7 +39,6 @@ export interface AdapterMemoryOptions extends AdapterAbstractOptions {
|
|
|
39
39
|
*/
|
|
40
40
|
export declare class AdapterMemory extends AdapterAbstract {
|
|
41
41
|
#private;
|
|
42
|
-
readonly namespace: string;
|
|
43
42
|
_type: string;
|
|
44
43
|
readonly options: AdapterMemoryOptions;
|
|
45
44
|
constructor(namespace?: string, options?: Partial<AdapterMemoryOptions>);
|
package/dist/adapter/memory.js
CHANGED
|
@@ -14,7 +14,7 @@ import { AdapterAbstract, } from "./abstract.js";
|
|
|
14
14
|
* @remarks
|
|
15
15
|
* - Fast and simple, ideal for testing and caching
|
|
16
16
|
* - Supports TTL with optional automatic cleanup
|
|
17
|
-
* - Thread-safe within a single
|
|
17
|
+
* - Thread-safe within a single process
|
|
18
18
|
* - Not suitable for multi-process or distributed environments
|
|
19
19
|
*
|
|
20
20
|
* @example
|
|
@@ -28,7 +28,6 @@ import { AdapterAbstract, } from "./abstract.js";
|
|
|
28
28
|
* ```
|
|
29
29
|
*/
|
|
30
30
|
export class AdapterMemory extends AdapterAbstract {
|
|
31
|
-
namespace;
|
|
32
31
|
_type = "memory";
|
|
33
32
|
options = {
|
|
34
33
|
defaultTtl: 0, // no ttl by default
|
|
@@ -40,10 +39,8 @@ export class AdapterMemory extends AdapterAbstract {
|
|
|
40
39
|
#expirations = new Map();
|
|
41
40
|
#cleanupTimer;
|
|
42
41
|
constructor(namespace = "", options = {}) {
|
|
43
|
-
super();
|
|
44
|
-
this.namespace = namespace;
|
|
42
|
+
super(namespace);
|
|
45
43
|
this.options = Object.freeze({ ...this.options, ...(options || {}) });
|
|
46
|
-
this._assertValidNamespace();
|
|
47
44
|
}
|
|
48
45
|
/** @inheritdoc */
|
|
49
46
|
initialize() {
|
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
*
|
|
4
4
|
* PostgreSQL key-value storage adapter implementation.
|
|
5
5
|
*/
|
|
6
|
-
import { AdapterAbstract, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult, type AdapterAbstractOptions } from "./abstract.js";
|
|
7
6
|
import type pg from "pg";
|
|
7
|
+
import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult } from "./abstract.ts";
|
|
8
8
|
/**
|
|
9
9
|
* Configuration options for the PostgreSQL KV adapter.
|
|
10
10
|
*/
|
|
@@ -33,7 +33,6 @@ export interface AdapterPostgresOptions extends AdapterAbstractOptions {
|
|
|
33
33
|
*/
|
|
34
34
|
export declare class AdapterPostgres extends AdapterAbstract {
|
|
35
35
|
#private;
|
|
36
|
-
readonly namespace: string;
|
|
37
36
|
_type: string;
|
|
38
37
|
readonly options: AdapterPostgresOptions;
|
|
39
38
|
constructor(namespace?: string, options?: Partial<AdapterPostgresOptions>);
|
package/dist/adapter/postgres.js
CHANGED
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
*
|
|
4
4
|
* PostgreSQL key-value storage adapter implementation.
|
|
5
5
|
*/
|
|
6
|
-
import { AdapterAbstract, } from "./abstract.js";
|
|
7
6
|
import { createClog } from "@marianmeres/clog";
|
|
7
|
+
import { AdapterAbstract, } from "./abstract.js";
|
|
8
8
|
/**
|
|
9
9
|
* PostgreSQL key-value storage adapter.
|
|
10
10
|
*
|
|
@@ -12,7 +12,6 @@ import { createClog } from "@marianmeres/clog";
|
|
|
12
12
|
* Automatically creates the required table and indexes on initialization.
|
|
13
13
|
*/
|
|
14
14
|
export class AdapterPostgres extends AdapterAbstract {
|
|
15
|
-
namespace;
|
|
16
15
|
_type = "postgres";
|
|
17
16
|
options = {
|
|
18
17
|
defaultTtl: 0, // no ttl by default
|
|
@@ -24,9 +23,7 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
24
23
|
};
|
|
25
24
|
#cleanupTimer;
|
|
26
25
|
constructor(namespace = "", options = {}) {
|
|
27
|
-
super();
|
|
28
|
-
this.namespace = namespace;
|
|
29
|
-
this._assertValidNamespace();
|
|
26
|
+
super(namespace);
|
|
30
27
|
this.options = Object.freeze({ ...this.options, ...(options || {}) });
|
|
31
28
|
if (!this.options.db) {
|
|
32
29
|
throw new Error("Missing pg instance");
|
|
@@ -265,7 +262,9 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
265
262
|
this._assertInitialized();
|
|
266
263
|
key = this._withNs(key);
|
|
267
264
|
const { tableName } = this.options;
|
|
268
|
-
const { rowCount } = await exec.query(`DELETE FROM ${tableName} WHERE key = $1`, [
|
|
265
|
+
const { rowCount } = await exec.query(`DELETE FROM ${tableName} WHERE key = $1`, [
|
|
266
|
+
key,
|
|
267
|
+
]);
|
|
269
268
|
return rowCount > 0;
|
|
270
269
|
}
|
|
271
270
|
/** @inheritdoc */
|
package/dist/adapter/redis.d.ts
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* Redis key-value storage adapter implementation.
|
|
5
5
|
*/
|
|
6
6
|
import type { RedisClientPoolType, RedisClientType } from "redis";
|
|
7
|
-
import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult } from "./abstract.
|
|
7
|
+
import { AdapterAbstract, type AdapterAbstractOptions, type Operation, type SetMultipleEntry, type SetOptions, type TtlResult } from "./abstract.ts";
|
|
8
8
|
/**
|
|
9
9
|
* Configuration options for the Redis KV adapter.
|
|
10
10
|
*/
|
|
@@ -50,7 +50,6 @@ export interface AdapterRedisOptions extends AdapterAbstractOptions {
|
|
|
50
50
|
*/
|
|
51
51
|
export declare class AdapterRedis extends AdapterAbstract {
|
|
52
52
|
#private;
|
|
53
|
-
readonly namespace: string;
|
|
54
53
|
_type: string;
|
|
55
54
|
readonly options: AdapterRedisOptions;
|
|
56
55
|
constructor(namespace?: string, options?: Partial<AdapterRedisOptions>);
|
package/dist/adapter/redis.js
CHANGED
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Redis key-value storage adapter implementation.
|
|
5
5
|
*/
|
|
6
|
-
import { AdapterAbstract, } from "./abstract.js";
|
|
7
6
|
import { createClog } from "@marianmeres/clog";
|
|
7
|
+
import { AdapterAbstract, } from "./abstract.js";
|
|
8
8
|
/**
|
|
9
9
|
* Redis key-value storage adapter.
|
|
10
10
|
*
|
|
@@ -31,7 +31,6 @@ import { createClog } from "@marianmeres/clog";
|
|
|
31
31
|
* ```
|
|
32
32
|
*/
|
|
33
33
|
export class AdapterRedis extends AdapterAbstract {
|
|
34
|
-
namespace;
|
|
35
34
|
_type = "redis";
|
|
36
35
|
options = {
|
|
37
36
|
defaultTtl: 0, // no ttl by default
|
|
@@ -41,12 +40,10 @@ export class AdapterRedis extends AdapterAbstract {
|
|
|
41
40
|
validateKeys: true,
|
|
42
41
|
};
|
|
43
42
|
constructor(namespace = "", options = {}) {
|
|
44
|
-
super();
|
|
45
|
-
this.namespace = namespace;
|
|
43
|
+
super(namespace);
|
|
46
44
|
if (!this.namespace) {
|
|
47
45
|
throw new Error(`Missing namespace (required in RedisAdapter)`);
|
|
48
46
|
}
|
|
49
|
-
this._assertValidNamespace();
|
|
50
47
|
this.options = Object.freeze({ ...this.options, ...(options || {}) });
|
|
51
48
|
if (!this.options.db) {
|
|
52
49
|
throw new Error("Missing redis db client instance");
|
|
@@ -362,7 +359,7 @@ return 0
|
|
|
362
359
|
// Positive number: TTL in seconds remaining
|
|
363
360
|
return {
|
|
364
361
|
state: "expires",
|
|
365
|
-
at: new Date(Date.now() + parseInt(`${ttl}
|
|
362
|
+
at: new Date(Date.now() + parseInt(`${ttl}`, 10) * 1_000),
|
|
366
363
|
};
|
|
367
364
|
}
|
|
368
365
|
/** @inheritdoc */
|
|
@@ -415,7 +412,7 @@ return 0
|
|
|
415
412
|
this._assertInitialized();
|
|
416
413
|
const { db } = this.options;
|
|
417
414
|
// SCAN scoped to this namespace — do not touch foreign tenants
|
|
418
|
-
const match = this.namespace
|
|
415
|
+
const match = `${this.namespace}*`;
|
|
419
416
|
const nsKeys = [];
|
|
420
417
|
let cursor = "0";
|
|
421
418
|
do {
|
|
@@ -7,7 +7,6 @@
|
|
|
7
7
|
* - **memory** - In-memory storage (default, not persisted)
|
|
8
8
|
* - **redis** - Redis server
|
|
9
9
|
* - **postgres** - PostgreSQL database
|
|
10
|
-
* - **deno-kv** - Deno KV (Deno runtime only)
|
|
11
10
|
*
|
|
12
11
|
* @example
|
|
13
12
|
* ```typescript
|
|
@@ -30,4 +29,4 @@
|
|
|
30
29
|
* await client.destroy();
|
|
31
30
|
* ```
|
|
32
31
|
*/
|
|
33
|
-
export * from "./kv.
|
|
32
|
+
export * from "./kv.ts";
|
package/dist/{mod.js → index.js}
RENAMED
package/dist/kv.d.ts
CHANGED
|
@@ -6,17 +6,15 @@
|
|
|
6
6
|
* Exports the main {@link createKVClient} factory function and re-exports
|
|
7
7
|
* all adapter classes, types, and interfaces.
|
|
8
8
|
*/
|
|
9
|
-
import {
|
|
10
|
-
import {
|
|
11
|
-
import {
|
|
12
|
-
|
|
13
|
-
export
|
|
14
|
-
export {
|
|
15
|
-
export {
|
|
16
|
-
export { AdapterRedis, type AdapterRedisOptions } from "./adapter/redis.
|
|
17
|
-
export {
|
|
18
|
-
export { AdapterDenoKv, type AdapterDenoKvOptions } from "./adapter/deno-kv.js";
|
|
19
|
-
export { sleep } from "./utils/sleep.js";
|
|
9
|
+
import { AdapterMemory, type AdapterMemoryOptions } from "./adapter/memory.ts";
|
|
10
|
+
import { AdapterPostgres, type AdapterPostgresOptions } from "./adapter/postgres.ts";
|
|
11
|
+
import { AdapterRedis, type AdapterRedisOptions } from "./adapter/redis.ts";
|
|
12
|
+
export type { AdapterAbstractOptions, AdapterInfo, Operation, SetMultipleEntry, SetOptions, TtlResult, } from "./adapter/abstract.ts";
|
|
13
|
+
export { AdapterAbstract } from "./adapter/abstract.ts";
|
|
14
|
+
export { AdapterMemory, type AdapterMemoryOptions } from "./adapter/memory.ts";
|
|
15
|
+
export { AdapterPostgres, type AdapterPostgresOptions } from "./adapter/postgres.ts";
|
|
16
|
+
export { AdapterRedis, type AdapterRedisOptions } from "./adapter/redis.ts";
|
|
17
|
+
export { sleep } from "./utils/sleep.ts";
|
|
20
18
|
/**
|
|
21
19
|
* Type mapping for all supported KV adapter types.
|
|
22
20
|
* @internal
|
|
@@ -34,10 +32,6 @@ interface KnownTypes {
|
|
|
34
32
|
options: AdapterRedisOptions;
|
|
35
33
|
adapter: AdapterRedis;
|
|
36
34
|
};
|
|
37
|
-
"deno-kv": {
|
|
38
|
-
options: AdapterDenoKvOptions;
|
|
39
|
-
adapter: AdapterDenoKv;
|
|
40
|
-
};
|
|
41
35
|
}
|
|
42
36
|
/**
|
|
43
37
|
* Factory function to create a KV client with the specified adapter type.
|
|
@@ -53,14 +47,12 @@ interface KnownTypes {
|
|
|
53
47
|
* - `"memory"` - In-memory storage (default, not persisted)
|
|
54
48
|
* - `"redis"` - Redis server (requires `db` option with Redis client)
|
|
55
49
|
* - `"postgres"` - PostgreSQL database (requires `db` option with pg client/pool)
|
|
56
|
-
* - `"deno-kv"` - Deno KV (Deno runtime only, requires `db` option with Deno.Kv)
|
|
57
50
|
* @param options - Adapter-specific configuration options.
|
|
58
51
|
*
|
|
59
52
|
* @returns A configured adapter instance. Call `initialize()` before use.
|
|
60
53
|
*
|
|
61
54
|
* @throws {TypeError} If namespace doesn't end with `:` (and is not empty).
|
|
62
55
|
* @throws {TypeError} If an unsupported adapter type is specified.
|
|
63
|
-
* @throws {Error} If `"deno-kv"` is used outside the Deno runtime.
|
|
64
56
|
* @throws {Error} If required options (like `db`) are missing for the adapter.
|
|
65
57
|
*
|
|
66
58
|
* @example
|
|
@@ -80,11 +72,6 @@ interface KnownTypes {
|
|
|
80
72
|
* const pool = new pg.Pool({ connectionString: '...' });
|
|
81
73
|
* const postgres = createKVClient("myapp:", "postgres", { db: pool });
|
|
82
74
|
* await postgres.initialize();
|
|
83
|
-
*
|
|
84
|
-
* // Deno KV (Deno runtime only)
|
|
85
|
-
* const kv = await Deno.openKv();
|
|
86
|
-
* const denoKv = createKVClient("myapp:", "deno-kv", { db: kv });
|
|
87
|
-
* await denoKv.initialize();
|
|
88
75
|
* ```
|
|
89
76
|
*/
|
|
90
77
|
export declare function createKVClient<T extends keyof KnownTypes>(namespace?: string, type?: T, options?: Partial<KnownTypes[T]["options"]>): KnownTypes[T]["adapter"];
|