@marianmeres/kv 3.1.1 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -5,12 +5,10 @@ Machine-friendly reference for AI agents working with this codebase.
5
5
  ## Quick Reference
6
6
 
7
7
  - **Stack**: TypeScript (erasable-only), Node LTS (`.node-version`), pnpm, `node:test`, Biome.
8
- - **Install**: `pnpm install` | **Test**: `pnpm test` (needs Postgres + Redis; SQLite runs in memory) |
8
+ - **Install**: `pnpm install` | **Test**: `pnpm test` (needs Postgres + Redis; SQLite and PGlite run in memory;
9
+ test files run one at a time) |
9
10
  **Check all**: `pnpm run ci` | **Build**: `pnpm run build`
10
- - **Published**: npm (`dist/`, built by `tsc`) and JSR (`src/` via `jsr.json`, for Deno consumers)
11
- - **JSR imports**: `jsr.json` maps `@marianmeres/clog` to `jsr:` so Deno apps get one copy;
12
- keep its range equal to `package.json`'s. `pg` and `redis` resolve from `package.json` as
13
- `npm:`. Only `deno publish` reads `jsr.json`: `test:deno` still runs against npm clog.
11
+ - **Published**: npm (`dist/`, built by `tsc`)
14
12
 
15
13
  ## Purpose
16
14
 
@@ -20,25 +18,39 @@ Key-value storage abstraction layer providing a unified Redis-inspired API acros
20
18
 
21
19
  ```
22
20
  src/
23
- ├── index.ts — The only entry point (package.json "exports", jsr.json "exports")
21
+ ├── index.ts — The only entry point (package.json "exports")
24
22
  ├── kv.ts — Factory function and all exports
25
23
  ├── adapter/
26
24
  │ ├── abstract.ts — Base class + shared types
27
25
  │ ├── memory.ts — In-memory adapter
28
26
  │ ├── redis.ts — Redis adapter
29
27
  │ ├── postgres.ts — PostgreSQL adapter
30
- │ └── sqlite.ts — SQLite adapter (`node:sqlite`)
28
+ │ └── sqlite.ts — SQLite adapter (`node:sqlite`, through a sqlkit driver)
31
29
  └── utils/
30
+ ├── driver.ts — `toPgDriver()`: the postgres adapter's `db` as a sqlkit `Driver`;
31
+ │ `isDriver()`, which the sqlite adapter shares
32
+ ├── sqlite-driver.ts — `ownSqliteDriver()`: the sqlite adapter's handle as kv's own
33
+ │ sqlkit `Driver`, its module imported lazily; `SqliteDb`, and
34
+ │ `assertSqliteDriver()` for a host's `Driver`
32
35
  └── sleep.ts — Sleep utility function
33
36
 
34
37
  tests/
35
- ├── kv.test.ts — Main test file (node:test); every test runs against all adapters
38
+ ├── kv.test.ts — Main test file (node:test); every test runs against all adapters,
39
+ │ the postgres adapter on PGlite and the sqlite adapter on a
40
+ │ sqlkit Driver too
41
+ ├── driver.test.ts — The postgres adapter on a pool, a client and a sqlkit Driver
42
+ │ (over node-postgres and over PGlite), and the sqlite adapter
43
+ │ on a sqlkit Driver the host built
36
44
  ├── _tests-runner.ts — Test harness: builds one client per adapter per test
37
45
  ├── _redis.ts — Redis test helper
38
46
  ├── _pg.ts — PostgreSQL test helper
47
+ ├── _pglite.ts — PGlite test helper (one in-memory PGlite per test file, as a sqlkit Driver)
39
48
  ├── _sqlite.ts — SQLite test helper (fresh `:memory:` database per test)
40
49
  └── _no-destroy-child.ts — child process: an adapter left running must not hold it open
41
50
 
51
+ docs/
52
+ └── backlog.md — Open work, ranked, not scheduled (the open copy)
53
+
42
54
  dist/ — `tsc -p tsconfig.build.json` output; gitignored; the npm payload
43
55
  ```
44
56
 
@@ -46,8 +58,10 @@ dist/ — `tsc -p tsconfig.build.json` output; gitignored; the
46
58
 
47
59
  1. **Runtime policy** — Node at the keyboard and in production, npm as the registry. No
48
60
  `Deno.*`, `Bun.*`, `bun:*`, `jsr:` or `npm:` specifiers. Web standards first; `node:*`
49
- where they don't reach. Nothing is built, tested or documented for Bun or Deno; JSR is
50
- published only while Deno consumers exist (`publish:jsr` runs `test:deno` first).
61
+ where they don't reach. Nothing is built, tested or documented for Bun or Deno.
62
+ Published to npm only; 3.1.1 was the last version on JSR. `engines.node` is
63
+ `@marianmeres/sqlkit`'s (`^24.20.0 || >=26.6.0`): kv installs it, so kv's floor is
64
+ never below it (convention 24).
51
65
  2. **Erasable TypeScript** — no `enum`, `namespace`, constructor parameter properties;
52
66
  `import type` for types; explicit `.ts` import extensions (rewritten to `.js` on emit).
53
67
  Node strips types and never checks them: `pnpm run typecheck` is the only type gate.
@@ -64,32 +78,107 @@ dist/ — `tsc -p tsconfig.build.json` output; gitignored; the
64
78
  8. Pattern matching: Redis-style (`*` = any chars, `?` = single char). All other characters — including `.`, `(`, `[`, `%`, `_` — are matched **literally**.
65
79
  9. TTL resolution: `options.ttl ?? defaultTtl`; `0` or negative disables expiration for that call (explicitly overrides `defaultTtl`).
66
80
  10. Shared helpers live in `abstract.ts` — use `_globToRegex()`, `_resolveTtl()`, `_normalizePairs()`; do not re-implement per-adapter. The SQL adapters keep their own pattern escaping next to the SQL that uses it: Postgres `#likePattern` (LIKE, `ESCAPE '\'`), SQLite `#globPattern` (GLOB — case-sensitive, unlike SQLite's LIKE; `[` → `[[]`). Both escape the namespace as a literal prefix.
67
- 11. Postgres `transaction()` must pin a single connection via `pool.connect()`; every nested query uses that client, not `this.options.db`.
68
- 12. Redis adapter owns the connection iff `initialize()` opened it (`#weOpened` flag). The Postgres and SQLite adapters never close the `db` they were given.
81
+ 11. Postgres `transaction()` is `this.#db.savepoint()`. Outside a transaction that is the
82
+ driver's `transaction()`: it pins the connection (or, on one `pg.Client`, holds every
83
+ other caller back), checks the `COMMIT` and rolls back. Inside a transaction the host
84
+ opened on the same `Driver` it is a savepoint of it, so a failed unit is undone alone
85
+ and the host's transaction goes on, as on SQLite (convention 19). Nothing in the
86
+ adapter sends `BEGIN`, `COMMIT`, `ROLLBACK` or `SAVEPOINT`. Pass the callback's `tx`
87
+ to the `…On` helpers.
88
+ 12. Redis adapter owns the connection iff `initialize()` opened it (`#weOpened` flag). The Postgres and SQLite adapters never close the `db` they were given; the Postgres adapter never calls `close()` on a driver, its own or the host's (it would end the host's pool or client). The SQLite adapter never calls `close()` on a driver either, its own or the host's: sqlkit's `createSqliteDriver(db).close()` closes the host's handle.
69
89
  13. Key validation lives in `_withNs()` — enforced when `options.validateKeys !== false`. Reject empty strings, keys with `\0`, and total `namespace + key` length > 512.
70
90
  14. `ttl()` returns `TtlResult = { state: "missing" | "no-ttl" | "expires"; at? }` — discriminated union, not `Date | null | false`.
71
91
  15. `incr`/`decr`/`getSet`/`cas`/`setIfAbsent` must be atomic: Redis = Lua or NX; Postgres = UPSERT/UPDATE with RETURNING; SQLite = a single UPSERT/UPDATE (`setIfAbsent`, `cas`) or a read-modify-write inside `#atomic()` (`getSet`, `incr`/`decr`); Memory = plain read-modify-write (single-threaded).
72
- 16. Non-numeric `incr`/`decr` target throws `TypeError("KV value is not a number")`. In Postgres, detect via error code `22P02`; SQLite checks `typeof` in JS, like Memory.
73
- 17. `keysIter` must clean up on early consumer break — PG releases its server-side cursor in the generator's `finally`. SQLite pages by keyset (`key > last`), so nothing stays open between yields.
74
- 18. SQLite: `src/` imports `node:sqlite` **type-only** — the caller passes the `DatabaseSync`. A runtime import would make every consumer of the package load `node:sqlite`.
75
- 19. SQLite multi-statement operations go through `#atomic()`: `BEGIN IMMEDIATE`, or a savepoint when `db.isTransaction` (the caller's transaction on the same handle). The callback must stay synchronous — an `await` inside would let other work join the transaction.
76
- 20. SQLite stores `value` as JSON text and `expires_at` as epoch ms (INTEGER), compared against a bound `Date.now()` — never SQLite's own clock. Read counts/integers through `Number()` (a handle opened with `readBigInts` returns bigints).
77
- 21. TTL cleanup timers are `unref()`ed (`unref?.()`: browser and worker timers are plain numbers), so a client nobody destroyed cannot hold the process open; `destroy()` still clears them. Postgres's tick awaits its query, so it re-checks `_initialized` before re-arming, and `destroy()` clears `_initialized` before its first `await`. SQLite stops the cleanup (one error log) when it finds `db.isOpen` false.
92
+ 16. Non-numeric `incr`/`decr` target throws `TypeError("KV value is not a number")`. In Postgres, the upsert's `DO UPDATE` has a `WHERE` that skips a live value that is not a JSON number, so the statement returns no row and raises nothing (a transaction the host opened on the same `Driver` is not aborted); no row is the `TypeError`, and the `22P02` catch on the sqlkit `SqlError`'s `code` is a backstop for a delta PostgreSQL cannot cast. SQLite checks `typeof` in JS, like Memory. Neither SQL adapter catches, wraps or translates any other database error: the caller gets sqlkit's `SqlError` (on SQLite with node:sqlite's error as its `cause`).
93
+ 17. `keysIter` in both SQL adapters pages by keyset, 500 keys a page, so nothing stays open between yields and an early consumer break leaves nothing to release. It is not one snapshot. SQLite pages with `key > last`. Postgres pages in byte order on the `text_pattern_ops` prefix index (`key ~>~ $2`, `ORDER BY key USING ~<~`); a plain `key > $2 ORDER BY key` would walk the primary key across every namespace. Postgres `keys()` has no SQL `ORDER BY` for the same reason: it sorts in JS.
94
+ 18. SQLite talks to the database through `src/utils/sqlite-driver.ts`: `ownSqliteDriver(db)`
95
+ builds kv's own sqlkit driver over the host's `DatabaseSync` (`createSqliteDriver`, one
96
+ per handle in a `WeakMap`, keeping 128 compiled statements: without the number every
97
+ call compiles). `@marianmeres/sqlkit/sqlite` loads `node:sqlite`, so it is imported
98
+ there with `import()`, when `initialize()` or `destroy(true)` first opens the driver
99
+ over a handle (on a host's `Driver` nothing is imported). Nothing in `src/` imports it
100
+ statically, and `node:sqlite` only as types: a static import would make every
101
+ consumer of the package load `node:sqlite` (a test checks the package root loads
102
+ none). Every statement goes through `#q()`, and the DDL through `#exec()`: on kv's own
103
+ driver on its sync tier, so a statement runs inside the call; on a host's `Driver` on
104
+ its async tier, so it waits its turn and joins the host's transaction when it was
105
+ issued inside one. Statement texts open with their keyword (`INSERT`,
106
+ `SELECT`, `UPDATE`, `DELETE`): the driver keeps only a query or a data change, and an
107
+ `exec` (the DDL) or a pragma empties what it kept, so neither inside an operation.
108
+ 19. SQLite multi-statement operations go through `#atomic(fn)`, `fn` a synchronous
109
+ function over the `SyncDriver` it is given: the driver's `sync.savepoint(fn)`, which
110
+ outside a transaction is `BEGIN IMMEDIATE` … `COMMIT`. When the caller has a `BEGIN`
111
+ open on the handle (`db.isTransaction`), the driver does not know that transaction and
112
+ SQLite refuses a second one, so `SAVEPOINT`, `ROLLBACK TO` and `RELEASE` go to the
113
+ handle and the unit's statements through the driver: the one place the adapter still
114
+ talks to the handle, besides `isOpen`. Neither `fn` nor `#atomic` may `await`: a unit
115
+ is over when the call returns, and tests pin it. The statements a unit shares with
116
+ `set`/`get`/`delete` are built once (`#setStatement`, `#getStatement`,
117
+ `#deleteStatement`), and the key is validated there, so an invalid key throws inside
118
+ the unit and undoes it. On a host's `Driver` the same `fn` runs in
119
+ `driver.savepoint(async () => fn(driver.sync))`: sqlkit's rule S3 puts its sync calls
120
+ inside that savepoint, which is a transaction of its own outside one, and a savepoint
121
+ of the host's transaction when the call was issued inside it (a failed unit is undone
122
+ alone, the host's transaction goes on). The unit waits its turn, then runs without a
123
+ break. There `driver.sync` is never used outside that callback: it is a `TypeError`
124
+ whenever the host has a transaction open elsewhere (S4).
125
+ 20. SQLite stores `value` as JSON text and `expires_at` as epoch ms (INTEGER), compared against a bound `Date.now()` — never SQLite's own clock. Read integer columns through `Number()` (a handle opened with `readBigInts` returns bigints); the driver's `rowCount` is already a number.
126
+ 21. TTL cleanup timers are `unref()`ed (`unref?.()`: browser and worker timers are plain numbers), so a client nobody destroyed cannot hold the process open; `destroy()` still clears them. Postgres's tick awaits its query, so it re-checks `_initialized` before re-arming, and `destroy()` clears `_initialized` before its first `await`. SQLite over a handle stops the cleanup (one error log) when it finds `db.isOpen` false. On a host's `Driver` its tick is Postgres's: it awaits the delete, logs a failure, re-checks `_initialized` and re-arms; a closed driver is told from another failure only by its message, so it is not told apart.
127
+ 22. Postgres talks to the database only through `src/utils/driver.ts`: `toPgDriver(db)`,
128
+ called once in the constructor, turns a `pg.Pool` or `pg.Client` into a sqlkit
129
+ `Driver` (one per object, in a `WeakMap`: `createPgDriver` adds an `error` listener on
130
+ every call, and several adapters on one pool is normal), and uses a host's `Driver` as
131
+ it is. A `Driver` of another dialect is a `TypeError`, and so is one without
132
+ `savepoint()` (built by a sqlkit older than 0.3.0). `options.db` stays what the host
133
+ passed; every statement goes through `this.#db`, with its text and `$n` parameters.
134
+ Nothing in `src/` imports `pg` (it is a dev dependency); `@marianmeres/sqlkit/pg` is
135
+ imported statically, so the package root loads `node:async_hooks`. A kv call issued
136
+ inside a transaction the host opened on the same `Driver` joins it, by design.
137
+ 23. The SQLite adapter's `db` is a `SqliteDb`: a `DatabaseSync`, or a sqlkit `Driver` of
138
+ the `sqlite` dialect with a sync tier and `savepoint()` (node:sqlite's, from
139
+ `openSqlite()` or `createSqliteDriver()`; by its shape Durable Objects' too, which no
140
+ test covers). One flag set in the constructor, `#onHostDriver`, picks the path; it is
141
+ read in `#open`, `#q`, `#exec`, `#atomic` and the cleanup, and nowhere else. A
142
+ `Driver` of another dialect, one without a sync tier or without `savepoint()`
143
+ (`assertSqliteDriver`), and a `db` that is neither (`isDatabaseSync`) are a
144
+ `TypeError` at construction. `options.db` stays what the host passed. A `BEGIN` sent
145
+ to the handle behind a host's `Driver` makes a unit fail (`SqlError`, `cannot start a
146
+ transaction within a transaction`): documented, not handled, since kv has no handle
147
+ to look at. kv's methods are async, so they cannot be called from inside the host's
148
+ sync transaction (S5).
149
+ 24. A sqlkit minor is a kv minor. sqlkit is on `0.x`, so each minor is a caret range of
150
+ its own: a consumer whose own sqlkit is on another minor gets two copies. Since 0.3.0
151
+ two copies know each other's `SqlError` (a mark `instanceof` reads; a copy of 0.2.0
152
+ or older has none, so its `instanceof SqlError` misses the errors of the driver kv
153
+ built). A minor can still change the `Driver` type both SQL adapters take, as 0.3.0
154
+ did with `savepoint`. Moving kv's range across a sqlkit minor therefore takes,
155
+ together: `engines.node` to sqlkit's, the README's "Requires Node" and the `^0.x.0`
156
+ in its notes and in `API.md`, and a "Changes in" section in the README telling
157
+ consumers to move their own sqlkit.
158
+ 25. PGlite is a tested target of the postgres adapter, not an adapter of its own.
159
+ `tests/_tests-runner.ts` builds a fifth client, `pglite`: the postgres adapter on a
160
+ sqlkit `Driver` over the test file's one in-memory PGlite (`tests/_pglite.ts`). Its
161
+ `info().type` is `"postgres"`, so a test that needs a client's adapter type reads
162
+ `client.info().type`, never the key in `clients`. `@electric-sql/pglite` is a dev
163
+ dependency; nothing in `src/` imports it. A sixth client, `sqliteDriver`, is the
164
+ sqlite adapter on a sqlkit `Driver` from `openSqlite()`, a fresh in-memory database
165
+ per test closed in the `finally`; its `info().type` is `"sqlite"`.
78
166
 
79
167
  ## Before Making Changes
80
168
 
81
169
  - [ ] Check existing patterns in adapter implementations
82
- - [ ] Add or extend a test in `tests/kv.test.ts`, then run `pnpm run ci`
170
+ - [ ] Add or extend a test in `tests/kv.test.ts` (or in `tests/driver.test.ts` for what only
171
+ an SQL adapter's `db` decides), then run `pnpm run ci`
83
172
  - [ ] Verify adapter limitations are documented (README feature matrix, API.md)
84
173
 
85
174
  ## Supported Adapters
86
175
 
87
- | Adapter | Type String | Required Options | Limitations |
88
- | ---------- | ------------ | --------------------- | --------------------------------------------------------------------------- |
89
- | Memory | `"memory"` | None | Not persisted |
90
- | Redis | `"redis"` | `db` (Redis client) | Namespace required; `keys()`/`clear()` unavailable in cluster mode |
91
- | PostgreSQL | `"postgres"` | `db` (pg.Pool/Client) | `tableName` limited to `[A-Za-z0-9_]` + optional `schema.` prefix |
92
- | SQLite | `"sqlite"` | `db` (`DatabaseSync`) | `tableName` limited to `[A-Za-z0-9_]`, no schema prefix; synchronous driver |
176
+ | Adapter | Type String | Required Options | Limitations |
177
+ | ---------- | ------------ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
178
+ | Memory | `"memory"` | None | Not persisted |
179
+ | Redis | `"redis"` | `db` (Redis client) | Namespace required; `keys()`/`clear()` unavailable in cluster mode |
180
+ | PostgreSQL | `"postgres"` | `db` (`pg.Pool`, `pg.Client` or a sqlkit `Driver`, PGlite's included) | `tableName` limited to `[A-Za-z0-9_]` + optional `schema.` prefix |
181
+ | SQLite | `"sqlite"` | `db` (`DatabaseSync`, or a sqlkit `Driver` of the `sqlite` dialect with a sync tier) | `tableName` limited to `[A-Za-z0-9_]`, no schema prefix; synchronous engine |
93
182
 
94
183
  ## Core API
95
184
 
@@ -156,6 +245,12 @@ interface Operation {
156
245
 
157
246
  type SetMultipleEntry = [string, any] | { key: string; value: any; ttl?: number };
158
247
 
248
+ // the postgres adapter's `db`; sqlkit's structural types, so `src/` never imports `pg`
249
+ type PostgresDb = PgPoolLike | PgStandaloneClientLike | Driver;
250
+
251
+ // the sqlite adapter's `db`; `DatabaseSync` is imported as a type only
252
+ type SqliteDb = DatabaseSync | Driver;
253
+
159
254
  type TtlResult =
160
255
  | { state: "missing" }
161
256
  | { state: "no-ttl" }
@@ -165,22 +260,28 @@ type TtlResult =
165
260
  ## Commands
166
261
 
167
262
  ```bash
168
- pnpm test # node --test over tests/**/*.test.ts, loads .env if present
263
+ pnpm test # node --test over tests/**/*.test.ts, one file at a time
264
+ # (--test-concurrency=1: they share `__kv` and one Redis DB), loads .env
169
265
  pnpm run test:watch
170
266
  pnpm run typecheck # tsc --noEmit
171
267
  pnpm run lint # biome check . (read-only); `pnpm run format` writes
172
268
  pnpm run ci # typecheck + lint + test — what CI runs
173
269
  pnpm run build # tsc -p tsconfig.build.json → dist/
174
- pnpm run test:deno # the same suite on Deno; only gates publish:jsr
175
270
  ```
176
271
 
177
- Releasing (`pnpm run rp` / `rpm`, or `pnpm run release major` + `pnpm run publish:all`) is a
178
- human action.
272
+ Releasing is a human action: `pnpm run rp` / `rpm` (patch / minor), or
273
+ `pnpm run release major --before-push "pnpm publish"`. `release` runs `pnpm run ci` before
274
+ it writes anything (`--before-bump`), and the publish runs between the tag and the push
275
+ (`--before-push`): a failing gate changes nothing, and a failed publish leaves no tag on
276
+ the remote.
179
277
 
180
278
  ## Test Environment Variables
181
279
 
182
- Every test runs against all four adapters, so tests need a live Postgres and Redis (SQLite
183
- uses a fresh `:memory:` database per test and needs nothing). Put
280
+ Every test in `tests/kv.test.ts` runs against all four adapters, against the postgres
281
+ adapter on PGlite (in memory, in the test process: it needs nothing) and against the
282
+ sqlite adapter on a sqlkit `Driver` (in memory too), so tests need a live
283
+ Postgres and Redis (SQLite uses a fresh `:memory:` database per test and needs nothing).
284
+ `tests/driver.test.ts` needs Postgres only. Put
184
285
  these in `.env` (see `.env.example`); CI provides them via service containers
185
286
  (`.github/workflows/ci.yml`). The harness deletes **every key** in the Redis DB before each
186
287
  test — use a scratch DB.
@@ -197,6 +298,7 @@ TEST_REDIS_URL=redis://localhost:6379/13
197
298
  ## Extending
198
299
 
199
300
  To add a new adapter:
301
+
200
302
  1. Create `src/adapter/<name>.ts`
201
303
  2. Extend `AdapterAbstract`; call `super(namespace)` and re-merge `options` (convention 5)
202
304
  3. Implement all abstract/interface methods
@@ -209,3 +311,4 @@ To add a new adapter:
209
311
 
210
312
  - [API Reference](./API.md) — Complete API documentation
211
313
  - [README](./README.md) — Quick start, feature matrix, breaking changes, development
314
+ - [Backlog](./docs/backlog.md) — Open work after 4.0.0, with each row's trigger
package/API.md CHANGED
@@ -27,6 +27,7 @@ function createKVClient<T extends keyof KnownTypes>(
27
27
  ```
28
28
 
29
29
  **Type Parameters:**
30
+
30
31
  - `T` - The adapter type (inferred from the `type` parameter)
31
32
 
32
33
  **Parameters:**
@@ -40,9 +41,11 @@ function createKVClient<T extends keyof KnownTypes>(
40
41
  **Returns:** A configured adapter instance. Call `initialize()` before use.
41
42
 
42
43
  **Throws:**
44
+
43
45
  - `TypeError` - If namespace doesn't end with `:` (and is not empty)
44
46
  - `TypeError` - If an unsupported adapter type is specified
45
47
  - `Error` - If required options (like `db`) are missing for the adapter
48
+ - `TypeError` - If `db` is not of a kind the adapter takes (see its options below)
46
49
 
47
50
  **Example:**
48
51
 
@@ -64,11 +67,17 @@ import pg from "pg";
64
67
  const pool = new pg.Pool({ connectionString: "..." });
65
68
  const postgres = createKVClient("myapp:", "postgres", { db: pool });
66
69
  await postgres.initialize();
70
+ // ...or on the sqlkit Driver your app already shares
71
+ import { createPgDriver } from "@marianmeres/sqlkit/pg";
72
+ const shared = createKVClient("myapp:", "postgres", { db: createPgDriver(pool) });
67
73
 
68
74
  // SQLite storage (node:sqlite ships with Node)
69
75
  import { DatabaseSync } from "node:sqlite";
70
76
  const sqlite = createKVClient("myapp:", "sqlite", { db: new DatabaseSync("kv.db") });
71
77
  await sqlite.initialize();
78
+ // ...or on a sqlkit Driver over SQLite
79
+ import { openSqlite } from "@marianmeres/sqlkit/sqlite";
80
+ const onDriver = createKVClient("myapp:", "sqlite", { db: openSqlite("kv.db") });
72
81
  ```
73
82
 
74
83
  ---
@@ -89,6 +98,9 @@ initialize(): Promise<void>
89
98
 
90
99
  Must be called before any other operations. For some adapters (like memory), this is a no-op, but should always be called for consistency.
91
100
 
101
+ Await it: the SQL adapters create their table after an `await`. On the sqlite adapter
102
+ over a `DatabaseSync`, the first call imports sqlkit's SQLite driver.
103
+
92
104
  **Throws:** `Error` - If connection fails.
93
105
 
94
106
  ---
@@ -220,7 +232,7 @@ decr(key: string, by?: number, options?: Partial<SetOptions>): Promise<number>
220
232
 
221
233
  **Returns:** the new value after the operation.
222
234
 
223
- **Errors:** throws `TypeError("KV value is not a number")` when the stored value is not a JSON number.
235
+ **Errors:** throws `TypeError("KV value is not a number")` when the stored value is not a JSON number. On the SQL adapters that fails nothing in the database: a transaction you opened on the same `Driver` goes on.
224
236
 
225
237
  **Example:**
226
238
 
@@ -372,6 +384,7 @@ type TtlResult =
372
384
  | `key` | `string` | The key to check. |
373
385
 
374
386
  **Returns:** A `TtlResult`. Switch on `.state`:
387
+
375
388
  - `"missing"` — key doesn't exist (or has expired)
376
389
  - `"no-ttl"` — key exists with no expiration
377
390
  - `"expires"` — key exists and will expire at `.at`
@@ -422,6 +435,7 @@ keys(pattern: string): Promise<string[]>
422
435
  ```
423
436
 
424
437
  Uses Redis-style wildcard patterns:
438
+
425
439
  - `*` matches any number of characters
426
440
  - `?` matches exactly one character
427
441
  - **Every other character is a literal match**, including regex metacharacters (`.`, `(`, `[`, `+`, `^`, `$`, `|`) and SQL LIKE metacharacters (`%`, `_`, `\`).
@@ -456,11 +470,13 @@ Iterates matching keys without materializing the full list. Prefer this over `ke
456
470
  keysIter(pattern: string): AsyncIterable<string>
457
471
  ```
458
472
 
459
- Ordering is not guaranteed across adapters — use `keys()` if you need sorted output.
473
+ Ordering is not guaranteed across adapters — use `keys()` if you need sorted output. The
474
+ walk is not one snapshot: a key added or removed while it runs may or may not be seen.
460
475
 
461
476
  **Per-adapter behavior:**
477
+
462
478
  - Redis: wraps `SCAN` (non-blocking).
463
- - PostgreSQL: uses a server-side cursor (`DECLARE CURSOR`) inside a short transaction. Early break releases the cursor and commits.
479
+ - PostgreSQL: keyset pages of 500 keys, in byte order on the prefix index `initialize()` creates. Nothing stays open between pages, so an early break has nothing to release and a write between two yields does not wait for the walk.
464
480
  - SQLite: keyset pages of 500 keys (`key > last ORDER BY key`). Nothing stays open between pages, so an early break has nothing to release.
465
481
  - Memory: yields from the internal `Map`.
466
482
 
@@ -468,7 +484,7 @@ Ordering is not guaranteed across adapters — use `keys()` if you need sorted o
468
484
 
469
485
  ```typescript
470
486
  for await (const k of client.keysIter("user:*")) {
471
- if (someCondition(k)) break; // safe — cursor is released
487
+ if (someCondition(k)) break; // safe — nothing is left open
472
488
  }
473
489
  ```
474
490
 
@@ -585,12 +601,12 @@ transaction(operations: Operation[]): Promise<any[]>
585
601
 
586
602
  Atomicity per adapter:
587
603
 
588
- | Adapter | Atomic | Notes |
589
- | ---------- | :----: | -------------------------------------------------------------------- |
590
- | Memory | ✓ | Single-threaded by nature |
591
- | Redis | ✓ | Uses `MULTI`/`EXEC` |
592
- | PostgreSQL | ✓ | Pins a single connection for `BEGIN`/…/`COMMIT`, even on a `pg.Pool` |
593
- | SQLite | ✓ | `BEGIN IMMEDIATE`; a savepoint inside a caller-opened transaction |
604
+ | Adapter | Atomic | Notes |
605
+ | ---------- | :----: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
606
+ | Memory | ✓ | Single-threaded by nature |
607
+ | Redis | ✓ | Uses `MULTI`/`EXEC` |
608
+ | PostgreSQL | ✓ | One connection for the whole unit: pinned on a `pg.Pool`, in turn on one `pg.Client`; a savepoint inside a transaction opened on the same `Driver` |
609
+ | SQLite | ✓ | `BEGIN IMMEDIATE`; a savepoint inside a transaction you opened on the same handle or `Driver` |
594
610
 
595
611
  Per-operation `options.ttl` is honored by **all** adapters (Redis, PostgreSQL, SQLite, Memory).
596
612
 
@@ -708,6 +724,49 @@ interface Operation {
708
724
 
709
725
  ---
710
726
 
727
+ ### `PostgresDb`
728
+
729
+ What the postgres adapter's `db` option takes.
730
+
731
+ ```typescript
732
+ import type { Driver } from "@marianmeres/sqlkit";
733
+ import type { PgPoolLike, PgStandaloneClientLike } from "@marianmeres/sqlkit/pg";
734
+
735
+ type PostgresDb = PgPoolLike | PgStandaloneClientLike | Driver;
736
+ ```
737
+
738
+ - `PgPoolLike` — a node-postgres `pg.Pool`.
739
+ - `PgStandaloneClientLike` — a connected node-postgres `pg.Client`.
740
+ - `Driver` — a sqlkit driver of the `pg` dialect, e.g. `createPgDriver(pool)` from
741
+ `@marianmeres/sqlkit/pg`.
742
+
743
+ The first two are declared by shape, so kv imports nothing from `pg`, and a `pg.Pool` and
744
+ a `pg.Client` fit them as they are. See [`AdapterPostgresOptions`](#adapterpostgresoptions).
745
+
746
+ ---
747
+
748
+ ### `SqliteDb`
749
+
750
+ What the sqlite adapter's `db` option takes.
751
+
752
+ ```typescript
753
+ import type { DatabaseSync } from "node:sqlite";
754
+ import type { Driver } from "@marianmeres/sqlkit";
755
+
756
+ type SqliteDb = DatabaseSync | Driver;
757
+ ```
758
+
759
+ - `DatabaseSync` — an open `node:sqlite` handle, e.g. `new DatabaseSync("kv.db")`.
760
+ - `Driver` — a sqlkit driver of the `sqlite` dialect with a sync tier and `savepoint()`,
761
+ e.g. `openSqlite("kv.db")` or `createSqliteDriver(handle)` from
762
+ `@marianmeres/sqlkit/sqlite`.
763
+
764
+ kv imports `DatabaseSync` as a type only: the package root loads no `node:sqlite`, and the
765
+ adapter imports sqlkit's SQLite driver only when `db` is a `DatabaseSync`. See
766
+ [`AdapterSqliteOptions`](#adaptersqliteoptions).
767
+
768
+ ---
769
+
711
770
  ## Adapter-Specific Options
712
771
 
713
772
  ### `AdapterMemoryOptions`
@@ -757,8 +816,11 @@ interface AdapterRedisOptions extends AdapterAbstractOptions {
757
816
 
758
817
  ```typescript
759
818
  interface AdapterPostgresOptions extends AdapterAbstractOptions {
760
- /** PostgreSQL connection instance - either `pg.Pool` or `pg.Client`. */
761
- db: pg.Pool | pg.Client;
819
+ /**
820
+ * The database: a node-postgres `pg.Pool`, a connected `pg.Client`, or a sqlkit
821
+ * `Driver` of the `pg` dialect. The caller owns it: the adapter never closes it.
822
+ */
823
+ db: PostgresDb;
762
824
  /**
763
825
  * Name of the table to use for storing key-value pairs.
764
826
  * The table will be created automatically if it doesn't exist.
@@ -777,10 +839,63 @@ interface AdapterPostgresOptions extends AdapterAbstractOptions {
777
839
  }
778
840
  ```
779
841
 
780
- **Transactions on a Pool:**
781
- `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.
842
+ `db` is a [`PostgresDb`](#postgresdb): pass a `pg.Pool` or a connected `pg.Client` as it
843
+ is, or a [`@marianmeres/sqlkit`](https://www.npmjs.com/package/@marianmeres/sqlkit)
844
+ `Driver` your app built. The constructor refuses, with a `TypeError`, a `Driver` of
845
+ another dialect and anything that is neither a pool, a client nor a driver.
846
+
847
+ **Connection ownership:** the adapter never closes what it was given — not the pool, not
848
+ the client, not the driver — so `destroy()` leaves it open and several adapters can share
849
+ one.
850
+
851
+ **Transactions and connections:** every statement runs on a sqlkit `Driver`. The adapter
852
+ builds one over a `pg.Pool` or a `pg.Client`, one per pool or client object however many
853
+ adapters share it, and uses a `Driver` you pass as it is. `transaction()` runs on one
854
+ connection for the whole unit, and a `COMMIT` that did not commit rejects:
855
+
856
+ - **On a `pg.Pool`**, it pins one connection for its length; other calls run on other
857
+ connections at once. A connection whose `ROLLBACK` failed is destroyed, not returned to
858
+ the pool.
859
+ - **On one `pg.Client`**, calls take turns: one issued while a transaction runs waits for
860
+ it to finish, and never becomes part of it.
861
+ - **On a `Driver` you pass**, the same holds for the pool or client under it. In addition,
862
+ a kv call issued inside a transaction you opened on that same driver
863
+ (`driver.transaction(async () => { await kv.set(…) })`) joins your transaction and
864
+ commits or rolls back with it. Make the call outside your transaction if it must
865
+ outlive your rollback. A kv `transaction()` issued there is a savepoint of your
866
+ transaction: when it fails, what it did is undone alone, your transaction is not
867
+ aborted, and it goes on. The `Driver` has to come from sqlkit 0.3.0 or newer, which
868
+ has `savepoint()`; an older one is refused at construction, with a `TypeError`.
869
+
870
+ The adapter listens for the pool's or client's `error` event, so an idle connection the
871
+ server dropped does not end the process: it is reported through `process.emitWarning`
872
+ when you have no listener of your own.
873
+
874
+ A `Driver` over PGlite (`createPgliteDriver` from `@marianmeres/sqlkit/pglite`) is of the
875
+ `pg` dialect and is a tested target: every test of the suite runs on it, as on a
876
+ `pg.Pool`. PGlite is Postgres compiled to WebAssembly, one connection inside your
877
+ process, so calls take turns there as on one `pg.Client`. For that your app depends on
878
+ `@electric-sql/pglite` and on `@marianmeres/sqlkit` itself (`^0.3.0`).
879
+
880
+ **Errors:** a statement the database refused rejects with sqlkit's `SqlError` (exported
881
+ by `@marianmeres/sqlkit`), unwrapped and untranslated. Its `code` is Postgres's SQLSTATE
882
+ (e.g. `22P05`), its message is Postgres's, and its `cause` is the driver library's own
883
+ error (node-postgres's, on a pool or a client). An `incr`/`decr` on a stored value that is
884
+ not a number is no database error: the statement leaves the value as it is and returns no
885
+ row, the adapter answers `TypeError("KV value is not a number")`, as every adapter does,
886
+ and a transaction you opened on the same `Driver` goes on. The one database error the
887
+ adapter reads is `22P02` from that statement, a backstop it answers with the same
888
+ `TypeError`. kv's own `TypeError` and `RangeError`, for an invalid key or namespace, are
889
+ unchanged.
890
+
891
+ `instanceof SqlError` holds when your app's own `@marianmeres/sqlkit` is 0.3.0 or newer
892
+ (kv installs `^0.3.1`). From 0.3.0 a `SqlError` is recognized across copies of the
893
+ package, so yours need not be the copy kv loads. A copy of 0.2 or older does not know an
894
+ error from a driver the adapter built over your pool or client, and the test is `false`.
895
+ `kind`, `code` and the message read the same on any copy.
782
896
 
783
897
  **Table Schema:**
898
+
784
899
  - `key` (VARCHAR 512) - Primary key
785
900
  - `value` (JSONB) - Stored value
786
901
  - `expires_at` (TIMESTAMP WITH TIME ZONE) - Expiration time
@@ -794,10 +909,12 @@ interface AdapterPostgresOptions extends AdapterAbstractOptions {
794
909
  ```typescript
795
910
  interface AdapterSqliteOptions extends AdapterAbstractOptions {
796
911
  /**
797
- * An open `node:sqlite` database, e.g. `new DatabaseSync("kv.db")`. The caller owns
798
- * it: `destroy()` never closes it, so one handle can be shared across adapters.
912
+ * The database: an open `node:sqlite` handle, e.g. `new DatabaseSync("kv.db")`, or a
913
+ * sqlkit `Driver` of the `sqlite` dialect with a sync tier, e.g. `openSqlite("kv.db")`.
914
+ * The caller owns it: `destroy()` never closes it, so one can be shared across
915
+ * adapters.
799
916
  */
800
- db: DatabaseSync;
917
+ db: SqliteDb;
801
918
  /**
802
919
  * Name of the table to use for storing key-value pairs.
803
920
  * The table will be created automatically if it doesn't exist.
@@ -814,27 +931,76 @@ interface AdapterSqliteOptions extends AdapterAbstractOptions {
814
931
  }
815
932
  ```
816
933
 
817
- **Connection ownership:** the adapter never opens, closes or reconfigures the handle — it
818
- sets no pragmas. Call `destroy()` before you close the handle: if the TTL cleanup finds it
819
- closed, it logs one error and stops. For several processes on one file, open it with a busy
934
+ `db` is a [`SqliteDb`](#sqlitedb): an open `DatabaseSync` as it is, or a
935
+ [`@marianmeres/sqlkit`](https://www.npmjs.com/package/@marianmeres/sqlkit) `Driver` your
936
+ app built. The constructor refuses, with a `TypeError`, anything that is neither, a
937
+ `Driver` of another dialect, and a `Driver` without a sync tier or `savepoint()`.
938
+ `options.db` stays what you passed.
939
+
940
+ **On a `DatabaseSync`**, every statement runs on a sqlkit driver the adapter builds over
941
+ the handle, one per handle however many adapters share it, on its synchronous tier: a
942
+ statement has run when the call returns, and so has a multi-statement operation, so
943
+ nothing else on the handle comes between its statements. The first `initialize()` or
944
+ `destroy(true)` imports `@marianmeres/sqlkit/sqlite` for it.
945
+
946
+ **On a `Driver` you pass**, it has to be of the `sqlite` dialect, with a sync tier and
947
+ `savepoint()`, so from sqlkit 0.3.0 or newer: `openSqlite()` and `createSqliteDriver()`
948
+ from `@marianmeres/sqlkit/sqlite` build one. What holds there:
949
+
950
+ - **Calls take their turn.** One issued while a transaction you opened on the driver is
951
+ open, from outside it, waits for it to end and never becomes part of it.
952
+ - **A call issued inside a transaction you opened on the driver joins it**
953
+ (`driver.transaction(async () => { await kv.set(…) })`), and commits or rolls back with
954
+ it. Make the call outside your transaction if it must outlive your rollback. A
955
+ multi-statement operation issued there is a savepoint of your transaction: when it
956
+ fails, it is undone alone, and your transaction goes on.
957
+ - **kv cannot be called from inside a synchronous transaction of yours**
958
+ (`driver.sync.transaction(…)`): its methods are async, and the call rejects with a
959
+ `TypeError`.
960
+ - **A `BEGIN` you send to the handle behind the driver is not a transaction the driver
961
+ knows.** A single statement runs inside it, and a multi-statement operation rejects
962
+ with a `SqlError` (`cannot start a transaction within a transaction`). Open your
963
+ transactions through the driver.
964
+
965
+ sqlkit's driver for a Durable Object's SQLite storage has the same shape, and is expected
966
+ to work; it is not part of the test suite.
967
+
968
+ **Connection ownership:** the adapter never opens, closes or reconfigures the handle or
969
+ the driver — it sets no pragmas, and never calls the driver's `close()`, which would close
970
+ the handle under it. Call `destroy()` before you close either: on a `DatabaseSync`, a TTL
971
+ cleanup that finds the handle closed logs one error and stops; on a `Driver`, it logs
972
+ each failed tick until `destroy()`. For several processes on one file, open it with a busy
820
973
  timeout (`new DatabaseSync(path, { timeout: 5000 })`) so a locked write waits instead of
821
- failing, and consider `PRAGMA journal_mode = WAL`.
974
+ failing, and consider `PRAGMA journal_mode = WAL`. `openSqlite()` sets a busy timeout,
975
+ and the WAL journal for a file.
822
976
 
823
977
  **Atomicity:** `setIfAbsent`, `cas`, `expire` and `set` are single statements.
824
978
  `getSet`, `incr`/`decr`, `setMultiple`, `clear` and `transaction` run in `BEGIN IMMEDIATE`,
825
979
  which takes the write lock up front, so they stay atomic against other connections and
826
- processes. Called inside a transaction you opened on the same handle (`db.isTransaction`),
827
- they use a savepoint instead: their own failure rolls back only themselves, and your
828
- `COMMIT`/`ROLLBACK` decides the rest.
980
+ processes. Called inside a transaction you opened on the same handle (`db.isTransaction`)
981
+ or through the same `Driver`, they use a savepoint instead: their own failure rolls back
982
+ only themselves, and your `COMMIT`/`ROLLBACK` decides the rest.
829
983
 
830
984
  **Synchronous driver:** `node:sqlite` blocks the event loop for the duration of each call.
831
985
  Every method still returns a Promise, like the other adapters.
832
986
 
987
+ **Errors:** a statement SQLite refused rejects with sqlkit's `SqlError` (exported by
988
+ `@marianmeres/sqlkit`), unwrapped and untranslated, as on PostgreSQL. Its class and
989
+ `kind` say what happened: a locked database, for one, is a `BusyError` (`kind` `"busy"`,
990
+ `retryable`). Its `code` is SQLite's result code (`"5"` for busy), its message is
991
+ SQLite's, and its `cause` is node:sqlite's own error, which carries node:sqlite's `code`
992
+ and `errcode`. The adapter catches no database error. A non-numeric `incr`/`decr` target
993
+ is checked in JavaScript and rejects with `TypeError("KV value is not a number")`, as on
994
+ every adapter. kv's own `TypeError` and `RangeError`, for an invalid key or namespace, are
995
+ unchanged. `instanceof SqlError` holds when your app's own `@marianmeres/sqlkit` is 0.3.0
996
+ or newer, as on PostgreSQL.
997
+
833
998
  **Pattern matching** uses SQLite `GLOB`, which is case-sensitive and uses the primary-key
834
999
  index for a literal prefix. `[` is escaped, so `keys()` / `clear()` follow the same
835
1000
  literal-except-`*`/`?` rules as every adapter.
836
1001
 
837
1002
  **Table Schema:**
1003
+
838
1004
  - `key` (TEXT) - Primary key
839
1005
  - `value` (TEXT) - Stored value as JSON text
840
1006
  - `expires_at` (INTEGER) - Expiration time as epoch milliseconds; `NULL` = no expiration