@marianmeres/kv 2.4.0 → 3.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 +92 -54
- package/API.md +201 -202
- package/README.md +95 -42
- package/dist/adapter/abstract.d.ts +8 -19
- package/dist/adapter/abstract.js +12 -26
- 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/adapter/sqlite.d.ts +102 -0
- package/dist/adapter/sqlite.js +410 -0
- package/dist/{mod.d.ts → index.d.ts} +2 -2
- package/dist/{mod.js → index.js} +1 -1
- package/dist/kv.d.ts +19 -20
- package/dist/kv.js +12 -17
- package/dist/utils/sleep.d.ts +1 -1
- package/dist/utils/sleep.js +2 -2
- package/package.json +71 -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,42 @@
|
|
|
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
|
+
- sqlite (`node:sqlite`)
|
|
10
11
|
- memory
|
|
11
|
-
- Deno KV (only in Deno runtime)
|
|
12
12
|
|
|
13
13
|
The API is inspired by the Redis API.
|
|
14
14
|
|
|
15
15
|
## Installation
|
|
16
16
|
|
|
17
|
-
```
|
|
18
|
-
|
|
17
|
+
```sh
|
|
18
|
+
npm install @marianmeres/kv # or pnpm add
|
|
19
|
+
deno add jsr:@marianmeres/kv # Deno
|
|
19
20
|
```
|
|
20
21
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
```
|
|
22
|
+
The `redis`, `postgres` and `sqlite` adapters take a client you create yourself (`redis`,
|
|
23
|
+
`pg`, or a `node:sqlite` `DatabaseSync`, which ships with Node). Requires Node >= 24.12.
|
|
24
24
|
|
|
25
25
|
## Usage
|
|
26
26
|
|
|
27
27
|
```typescript
|
|
28
|
-
import { createKVClient } from
|
|
28
|
+
import { createKVClient } from "@marianmeres/kv";
|
|
29
29
|
|
|
30
30
|
// Basic usage with memory adapter (default)
|
|
31
31
|
const client = createKVClient("my-app-namespace:");
|
|
32
32
|
|
|
33
33
|
// Or specify a different adapter type
|
|
34
34
|
const redisClient = createKVClient(
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
35
|
+
"my-app-namespace:",
|
|
36
|
+
"redis", // 'redis' | 'postgres' | 'sqlite' | 'memory'
|
|
37
|
+
{ db: myRedisClient }, // adapter-specific options
|
|
38
38
|
);
|
|
39
39
|
|
|
40
40
|
// Use the client
|
|
41
|
-
await client.set(
|
|
42
|
-
await client.get(
|
|
43
|
-
await client.keys(
|
|
41
|
+
await client.set("my:foo:key", { my: "value" });
|
|
42
|
+
await client.get("my:foo:key"); // { my: "value" }
|
|
43
|
+
await client.keys("my:*"); // ['my:foo:key']
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
**Important**: Namespace must end with a colon (`:`) or be an empty string.
|
|
@@ -83,9 +83,9 @@ client.ttl(key: string): Promise<TtlResult>
|
|
|
83
83
|
|
|
84
84
|
```typescript
|
|
85
85
|
type TtlResult =
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
86
|
+
| { state: "missing" }
|
|
87
|
+
| { state: "no-ttl" }
|
|
88
|
+
| { state: "expires"; at: Date };
|
|
89
89
|
```
|
|
90
90
|
|
|
91
91
|
## Pattern Syntax
|
|
@@ -98,51 +98,84 @@ type TtlResult =
|
|
|
98
98
|
|
|
99
99
|
## Adapter Feature Matrix
|
|
100
100
|
|
|
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()`
|
|
101
|
+
| Feature | Memory | Redis | PostgreSQL | SQLite |
|
|
102
|
+
| --------------------------------------------------------- | :-----------------: | :--------------------: | :--------------: | :-----------------------: |
|
|
103
|
+
| Persistent | ✗ | ✓ | ✓ | ✓ (file database) |
|
|
104
|
+
| TTL on `set()` | ✓ | ✓ | ✓ | ✓ |
|
|
105
|
+
| `ttl()` → `expires`/`no-ttl`/`missing` | ✓ | ✓ | ✓ | ✓ |
|
|
106
|
+
| `expire()` | ✓ | ✓ | ✓ | ✓ |
|
|
107
|
+
| Atomic `setIfAbsent` / `incr` / `decr` / `cas` / `getSet` | ✓ | ✓ (Lua) | ✓ (UPSERT) | ✓ (UPSERT / IMMEDIATE tx) |
|
|
108
|
+
| Sorted `keys()` | ✓ | ✓ | ✓ | ✓ |
|
|
109
|
+
| Streaming `keysIter()` | ✓ | ✓ (SCAN) | ✓ (cursor) | ✓ (keyset paging) |
|
|
110
|
+
| Per-pair TTL in `setMultiple` | ✓ | ✓ | ✓ | ✓ |
|
|
111
|
+
| Atomic `transaction()` | ✓ (single-threaded) | ✓ (MULTI) | ✓ (BEGIN/COMMIT) | ✓ (BEGIN IMMEDIATE) |
|
|
112
|
+
| `delete()` returns real existed-flag | ✓ | ✓ | ✓ | ✓ |
|
|
113
|
+
| Background TTL cleanup | optional | native (Redis does it) | optional | optional |
|
|
114
|
+
| `keys()` / `clear()` | ✓ | ✓ (non-cluster only) | ✓ | ✓ |
|
|
115
115
|
|
|
116
116
|
## Adapter-Specific Limitations
|
|
117
117
|
|
|
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
118
|
### Redis
|
|
119
|
+
|
|
126
120
|
- **`keys()` and `clear()`**: Not supported in cluster mode (throws error)
|
|
127
121
|
- **Namespace**: Required (cannot be empty string)
|
|
128
122
|
- **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
123
|
|
|
130
124
|
### PostgreSQL
|
|
125
|
+
|
|
131
126
|
- Creates a table (default: `__kv`) in your database.
|
|
132
127
|
- `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
128
|
- `transaction()` pins a single connection from the Pool for the whole BEGIN/…/COMMIT block — safe to call against a `pg.Pool`.
|
|
134
129
|
- Supports optional TTL cleanup via `ttlCleanupIntervalSec` option.
|
|
135
130
|
|
|
131
|
+
### SQLite
|
|
132
|
+
|
|
133
|
+
```typescript
|
|
134
|
+
import { DatabaseSync } from "node:sqlite";
|
|
135
|
+
|
|
136
|
+
const client = createKVClient("my-app-namespace:", "sqlite", {
|
|
137
|
+
db: new DatabaseSync("kv.db"),
|
|
138
|
+
});
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
- Takes an open `node:sqlite` `DatabaseSync` and never closes it — the handle is yours,
|
|
142
|
+
and can be shared with your own tables or other adapters.
|
|
143
|
+
- Creates a table (default: `__kv`). `tableName` must match `^[A-Za-z_][A-Za-z0-9_]*$` — no
|
|
144
|
+
`schema.` prefix.
|
|
145
|
+
- `node:sqlite` is synchronous: each call blocks the event loop while it runs.
|
|
146
|
+
- Multi-statement operations (`getSet`, `incr`/`decr`, `setMultiple`, `clear`,
|
|
147
|
+
`transaction`) run in `BEGIN IMMEDIATE`. Called inside a transaction you opened on the
|
|
148
|
+
same handle, they use a savepoint instead, so your `COMMIT`/`ROLLBACK` decides.
|
|
149
|
+
- The adapter does not touch connection settings. For several processes on one file,
|
|
150
|
+
open it with a busy timeout (`new DatabaseSync(path, { timeout: 5000 })`) and consider
|
|
151
|
+
`PRAGMA journal_mode = WAL`.
|
|
152
|
+
- `cas()` compares the stored JSON text, so object key order matters (as with Memory and
|
|
153
|
+
Redis; PostgreSQL compares `jsonb`, which ignores key order).
|
|
154
|
+
- Supports optional TTL cleanup via `ttlCleanupIntervalSec` option.
|
|
155
|
+
|
|
136
156
|
### Memory
|
|
157
|
+
|
|
137
158
|
- Data is not persisted (in-memory only).
|
|
138
159
|
- Supports optional TTL cleanup via `ttlCleanupIntervalSec` option.
|
|
139
160
|
|
|
140
|
-
## Breaking Changes (
|
|
161
|
+
## Breaking Changes (3.0.0)
|
|
141
162
|
|
|
142
|
-
|
|
163
|
+
- **The Deno KV adapter is removed.** `"deno-kv"` is no longer an adapter type, and
|
|
164
|
+
`AdapterDenoKv`, `AdapterDenoKvOptions` and `KvRaceError` (only Deno KV threw it) are no
|
|
165
|
+
longer exported. Deno KV has no equivalent outside the Deno runtime. Stay on 2.x if you
|
|
166
|
+
depend on it, or move to the `redis`, `postgres` or `memory` adapter.
|
|
167
|
+
- The npm package now declares **Node >= 24.12** (`engines`). The memory, Redis and
|
|
168
|
+
PostgreSQL adapters behave exactly as in 2.4.
|
|
169
|
+
- The JSR package now resolves `@marianmeres/clog`, `pg` and `redis` from npm instead of
|
|
170
|
+
JSR.
|
|
143
171
|
|
|
144
|
-
|
|
172
|
+
## Changes in 2.2.0
|
|
173
|
+
|
|
174
|
+
Shipped as a minor release, although the first two items are breaking:
|
|
175
|
+
|
|
176
|
+
**Breaking:**
|
|
145
177
|
- **`ttl(key)` now returns a discriminated `TtlResult`** — `{ state: "missing" | "no-ttl" | "expires", at? }` — instead of `Date | null | false`. Migration:
|
|
178
|
+
|
|
146
179
|
```ts
|
|
147
180
|
// before
|
|
148
181
|
const t = await client.ttl(k);
|
|
@@ -160,7 +193,7 @@ Since 2.0, the following changes are in this tree:
|
|
|
160
193
|
```
|
|
161
194
|
- **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
195
|
|
|
163
|
-
**
|
|
196
|
+
**Additive:**
|
|
164
197
|
- New methods `setIfAbsent`, `incr`, `decr`, `getSet`, `cas`, `keysIter` on every adapter.
|
|
165
198
|
- `setMultiple` accepts `{ key, value, ttl? }[]` entries in addition to the legacy `[key, value][]` tuples. Per-pair `ttl` overrides batch `options.ttl`.
|
|
166
199
|
- 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 +235,26 @@ but a few change semantics in ways that could affect existing code:
|
|
|
202
235
|
|
|
203
236
|
For complete API documentation including all methods, types, and adapter-specific options, see [API.md](API.md).
|
|
204
237
|
|
|
238
|
+
## Development
|
|
239
|
+
|
|
240
|
+
Node LTS (`.node-version`), pnpm, Biome, `node:test`. The source is erasable-only
|
|
241
|
+
TypeScript that Node runs directly; `dist/` is built only for publishing.
|
|
242
|
+
|
|
243
|
+
Every test runs against all four adapters, so `pnpm test` needs a running PostgreSQL and
|
|
244
|
+
Redis (SQLite runs in memory, nothing to set up). Copy `.env.example` to `.env` and fill
|
|
245
|
+
in the connection details. Redis keys in the target database are deleted before each
|
|
246
|
+
test, so point it at a scratch database (the default is `/13`).
|
|
247
|
+
|
|
248
|
+
| Command | Does |
|
|
249
|
+
| ----------------------------------- | -------------------------------------------------- |
|
|
250
|
+
| `pnpm install` | installs dependencies and dev tooling |
|
|
251
|
+
| `pnpm test` / `pnpm run test:watch` | `node --test` over `tests/**/*.test.ts` |
|
|
252
|
+
| `pnpm run typecheck` | `tsc --noEmit` over `src` and `tests` |
|
|
253
|
+
| `pnpm run lint` / `pnpm run format` | `biome check .` read-only / with `--write` |
|
|
254
|
+
| `pnpm run ci` | typecheck + lint + test, what CI runs |
|
|
255
|
+
| `pnpm run build` | `tsc -p tsconfig.build.json` → `dist/` |
|
|
256
|
+
| `pnpm run rp` / `pnpm run rpm` | patch / minor release, then publish to npm and JSR |
|
|
257
|
+
|
|
205
258
|
## License
|
|
206
259
|
|
|
207
260
|
[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", "
|
|
18
|
+
/** The adapter type identifier (e.g., "redis", "postgres", "sqlite", "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
|
|
@@ -331,7 +323,7 @@ export declare abstract class AdapterAbstract {
|
|
|
331
323
|
/**
|
|
332
324
|
* Retrieves multiple values in a single batch operation.
|
|
333
325
|
*
|
|
334
|
-
* More efficient than multiple individual `get` calls, especially for Redis and
|
|
326
|
+
* More efficient than multiple individual `get` calls, especially for Redis, PostgreSQL and SQLite.
|
|
335
327
|
*
|
|
336
328
|
* @param keys - An array of keys to retrieve.
|
|
337
329
|
* @returns A promise that resolves to an object mapping keys to their values.
|
|
@@ -347,8 +339,8 @@ export declare abstract class AdapterAbstract {
|
|
|
347
339
|
/**
|
|
348
340
|
* Executes multiple operations within a single transaction.
|
|
349
341
|
*
|
|
350
|
-
* For adapters that support it (Redis, PostgreSQL), operations are atomic.
|
|
351
|
-
* For memory
|
|
342
|
+
* For adapters that support it (Redis, PostgreSQL, SQLite), operations are atomic.
|
|
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", "sqlite", 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
|
|
@@ -313,7 +302,7 @@ export class AdapterAbstract {
|
|
|
313
302
|
/**
|
|
314
303
|
* Retrieves multiple values in a single batch operation.
|
|
315
304
|
*
|
|
316
|
-
* More efficient than multiple individual `get` calls, especially for Redis and
|
|
305
|
+
* More efficient than multiple individual `get` calls, especially for Redis, PostgreSQL and SQLite.
|
|
317
306
|
*
|
|
318
307
|
* @param keys - An array of keys to retrieve.
|
|
319
308
|
* @returns A promise that resolves to an object mapping keys to their values.
|
|
@@ -331,8 +320,8 @@ export class AdapterAbstract {
|
|
|
331
320
|
/**
|
|
332
321
|
* Executes multiple operations within a single transaction.
|
|
333
322
|
*
|
|
334
|
-
* For adapters that support it (Redis, PostgreSQL), operations are atomic.
|
|
335
|
-
* For memory
|
|
323
|
+
* For adapters that support it (Redis, PostgreSQL, SQLite), operations are atomic.
|
|
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", "sqlite", 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 {
|