@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 CHANGED
@@ -4,9 +4,10 @@ Machine-friendly reference for AI agents working with this codebase.
4
4
 
5
5
  ## Quick Reference
6
6
 
7
- - **Stack**: TypeScript, Deno (primary), Node.js (via npm build)
8
- - **Run**: `deno task test` | **Build**: `deno task npm:build`
9
- - **Version**: 2.1.0
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) |
9
+ **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)
10
11
 
11
12
  ## Purpose
12
13
 
@@ -16,55 +17,74 @@ Key-value storage abstraction layer providing a unified Redis-inspired API acros
16
17
 
17
18
  ```
18
19
  src/
19
- ├── mod.ts — Main entry point (re-exports kv.ts)
20
+ ├── index.ts — The only entry point (package.json "exports", jsr.json "exports")
20
21
  ├── kv.ts — Factory function and all exports
21
22
  ├── adapter/
22
23
  │ ├── abstract.ts — Base class + shared types
23
24
  │ ├── memory.ts — In-memory adapter
24
25
  │ ├── redis.ts — Redis adapter
25
26
  │ ├── postgres.ts — PostgreSQL adapter
26
- │ └── deno-kv.ts — Deno KV adapter
27
+ │ └── sqlite.ts — SQLite adapter (`node:sqlite`)
27
28
  └── utils/
28
29
  └── sleep.ts — Sleep utility function
29
30
 
30
31
  tests/
31
- ├── kv.test.ts — Main test file
32
- ├── _tests-runner.ts — Test harness
32
+ ├── kv.test.ts — Main test file (node:test); every test runs against all adapters
33
+ ├── _tests-runner.ts — Test harness: builds one client per adapter per test
33
34
  ├── _redis.ts — Redis test helper
34
- └── _pg.ts — PostgreSQL test helper
35
+ ├── _pg.ts — PostgreSQL test helper
36
+ └── _sqlite.ts — SQLite test helper (fresh `:memory:` database per test)
37
+
38
+ dist/ — `tsc -p tsconfig.build.json` output; gitignored; the npm payload
35
39
  ```
36
40
 
37
41
  ## Critical Conventions
38
42
 
39
- 1. Namespace must end with `:` or be empty string.
40
- 2. Values are JSON-stringified internally.
41
- 3. TTL is in seconds; stored as absolute `Date` internally.
42
- 4. Pattern matching: Redis-style (`*` = any chars, `?` = single char). All other characters — including `.`, `(`, `[`, `%`, `_` — are matched **literally**.
43
- 5. TTL resolution: `options.ttl ?? defaultTtl`; `0` or negative disables expiration for that call (explicitly overrides `defaultTtl`).
44
- 6. All pattern-to-regex / pattern-to-LIKE conversion lives in `abstract.ts` — use `_globToRegex()`, `_resolveTtl()`, `_normalizePairs()`; do not re-implement per-adapter.
45
- 7. Postgres `transaction()` must pin a single connection via `pool.connect()`; every nested query uses that client, not `this.options.db`.
46
- 8. Redis adapter owns the connection iff `initialize()` opened it (`#weOpened` flag).
47
- 9. Key validation lives in `_withNs()` — enforced when `options.validateKeys !== false`. Reject empty strings, keys with `\0`, and total `namespace + key` length > 512.
48
- 10. `ttl()` returns `TtlResult = { state: "missing" | "no-ttl" | "expires"; at? }` — discriminated union, not `Date | null | false`.
49
- 11. `incr`/`decr`/`getSet`/`cas`/`setIfAbsent` must be atomic: Redis = Lua or NX; Postgres = UPSERT/UPDATE with RETURNING; Deno KV = `#atomicUpdate` CAS retry loop; Memory = plain read-modify-write (single-threaded).
50
- 12. Non-numeric `incr`/`decr` target throws `TypeError("KV value is not a number")`. In Postgres, detect via error code `22P02`.
51
- 13. Deno KV atomic retries exhausted → throw `KvRaceError` (imported from `abstract.ts`).
52
- 14. `keysIter` must clean up on early consumer break — PG releases its server-side cursor in the generator's `finally`.
43
+ 1. **Runtime policy** — Node at the keyboard and in production, npm as the registry. No
44
+ `Deno.*`, `Bun.*`, `bun:*`, `jsr:` or `npm:` specifiers. Web standards first; `node:*`
45
+ where they don't reach. Nothing is built, tested or documented for Bun or Deno; JSR is
46
+ published only while Deno consumers exist (`publish:jsr` runs `test:deno` first).
47
+ 2. **Erasable TypeScript** — no `enum`, `namespace`, constructor parameter properties;
48
+ `import type` for types; explicit `.ts` import extensions (rewritten to `.js` on emit).
49
+ Node strips types and never checks them: `pnpm run typecheck` is the only type gate.
50
+ 3. **Formatting & lint** — tabs, 4 wide, 90 columns, double quotes (`biome.json`);
51
+ manifests at 2 spaces. `pnpm run format` before committing. `noExplicitAny` is off
52
+ because stored values are arbitrary JSON and `any` is public API; `noNonNullAssertion`
53
+ is off for the `db: null!` option defaults and `Map#get` after `has()`.
54
+ 4. Namespace must end with `:` or be empty string. Validated in the `AdapterAbstract`
55
+ constructor; adapters pass it via `super(namespace)`.
56
+ 5. Adapters re-declare `options` with a field initializer and merge user options again in
57
+ their own constructor (the field replaces what the base constructor set).
58
+ 6. Values are JSON-stringified internally.
59
+ 7. TTL is in seconds; stored as absolute `Date` internally.
60
+ 8. Pattern matching: Redis-style (`*` = any chars, `?` = single char). All other characters — including `.`, `(`, `[`, `%`, `_` — are matched **literally**.
61
+ 9. TTL resolution: `options.ttl ?? defaultTtl`; `0` or negative disables expiration for that call (explicitly overrides `defaultTtl`).
62
+ 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.
63
+ 11. Postgres `transaction()` must pin a single connection via `pool.connect()`; every nested query uses that client, not `this.options.db`.
64
+ 12. Redis adapter owns the connection iff `initialize()` opened it (`#weOpened` flag). The Postgres and SQLite adapters never close the `db` they were given.
65
+ 13. Key validation lives in `_withNs()` — enforced when `options.validateKeys !== false`. Reject empty strings, keys with `\0`, and total `namespace + key` length > 512.
66
+ 14. `ttl()` returns `TtlResult = { state: "missing" | "no-ttl" | "expires"; at? }` — discriminated union, not `Date | null | false`.
67
+ 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).
68
+ 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.
69
+ 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.
70
+ 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`.
71
+ 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.
72
+ 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).
53
73
 
54
74
  ## Before Making Changes
55
75
 
56
76
  - [ ] Check existing patterns in adapter implementations
57
- - [ ] Run tests: `deno test --unstable-kv -A --env-file`
58
- - [ ] Verify adapter limitations are documented
77
+ - [ ] Add or extend a test in `tests/kv.test.ts`, then run `pnpm run ci`
78
+ - [ ] Verify adapter limitations are documented (README feature matrix, API.md)
59
79
 
60
80
  ## Supported Adapters
61
81
 
62
- | Adapter | Type String | Required Options | Limitations |
63
- |---------|-------------|------------------|-------------|
64
- | Memory | `"memory"` | None | Not persisted |
65
- | Redis | `"redis"` | `db` (Redis client) | Namespace required; `keys()`/`clear()` unavailable in cluster mode |
66
- | PostgreSQL | `"postgres"` | `db` (pg.Pool/Client) | `tableName` limited to `[A-Za-z0-9_]` + optional `schema.` prefix |
67
- | Deno KV | `"deno-kv"` | `db` (Deno.Kv) | Deno runtime only; `delete()` always `true`; `expire()`/`ttl()` unsupported; `transaction()` atomic only when no `get` ops |
82
+ | Adapter | Type String | Required Options | Limitations |
83
+ | ---------- | ------------ | --------------------- | --------------------------------------------------------------------------- |
84
+ | Memory | `"memory"` | None | Not persisted |
85
+ | Redis | `"redis"` | `db` (Redis client) | Namespace required; `keys()`/`clear()` unavailable in cluster mode |
86
+ | PostgreSQL | `"postgres"` | `db` (pg.Pool/Client) | `tableName` limited to `[A-Za-z0-9_]` + optional `schema.` prefix |
87
+ | SQLite | `"sqlite"` | `db` (`DatabaseSync`) | `tableName` limited to `[A-Za-z0-9_]`, no schema prefix; synchronous driver |
68
88
 
69
89
  ## Core API
70
90
 
@@ -111,58 +131,76 @@ ttl(key): Promise<TtlResult>
111
131
  ## Key Types
112
132
 
113
133
  ```typescript
114
- interface SetOptions { ttl: number }
115
- interface AdapterInfo { type: string }
116
- interface AdapterAbstractOptions { defaultTtl: number; logger?: Logger; validateKeys?: boolean }
117
- interface Operation { type: "set" | "get" | "delete"; key: string; value?: any; options?: SetOptions }
118
-
119
- type SetMultipleEntry =
120
- | [string, any]
121
- | { key: string; value: any; ttl?: number };
134
+ interface SetOptions {
135
+ ttl: number;
136
+ }
137
+ interface AdapterInfo {
138
+ type: string;
139
+ }
140
+ interface AdapterAbstractOptions {
141
+ defaultTtl: number;
142
+ logger?: Logger;
143
+ validateKeys?: boolean;
144
+ }
145
+ interface Operation {
146
+ type: "set" | "get" | "delete";
147
+ key: string;
148
+ value?: any;
149
+ options?: SetOptions;
150
+ }
151
+
152
+ type SetMultipleEntry = [string, any] | { key: string; value: any; ttl?: number };
122
153
 
123
154
  type TtlResult =
124
- | { state: "missing" }
125
- | { state: "no-ttl" }
126
- | { state: "expires"; at: Date };
127
-
128
- class KvRaceError extends Error {} // Deno KV CAS retry-exhaustion
155
+ | { state: "missing" }
156
+ | { state: "no-ttl" }
157
+ | { state: "expires"; at: Date };
129
158
  ```
130
159
 
131
160
  ## Commands
132
161
 
133
162
  ```bash
134
- # Run tests (requires --unstable-kv for Deno KV)
135
- deno test --unstable-kv -A --env-file
136
-
137
- # Run tests with watch mode
138
- deno test --unstable-kv -A --env-file --watch
139
-
140
- # Build npm package
141
- deno run -A scripts/build-npm.ts
163
+ pnpm test # node --test over tests/**/*.test.ts, loads .env if present
164
+ pnpm run test:watch
165
+ pnpm run typecheck # tsc --noEmit
166
+ pnpm run lint # biome check . (read-only); `pnpm run format` writes
167
+ pnpm run ci # typecheck + lint + test — what CI runs
168
+ pnpm run build # tsc -p tsconfig.build.json → dist/
169
+ pnpm run test:deno # the same suite on Deno; only gates publish:jsr
142
170
  ```
143
171
 
172
+ Releasing (`pnpm run rp` / `rpm`, or `pnpm run release major` + `pnpm run publish:all`) is a
173
+ human action.
174
+
144
175
  ## Test Environment Variables
145
176
 
177
+ Every test runs against all four adapters, so tests need a live Postgres and Redis (SQLite
178
+ uses a fresh `:memory:` database per test and needs nothing). Put
179
+ these in `.env` (see `.env.example`); CI provides them via service containers
180
+ (`.github/workflows/ci.yml`). The harness deletes **every key** in the Redis DB before each
181
+ test — use a scratch DB.
182
+
146
183
  ```
147
184
  TEST_PG_HOST=localhost
148
185
  TEST_PG_PORT=5432
149
186
  TEST_PG_DATABASE=<required>
150
187
  TEST_PG_USER=<required>
151
188
  TEST_PG_PASSWORD=<required>
152
- TEST_REDIS_URL=redis://localhost:6379
189
+ TEST_REDIS_URL=redis://localhost:6379/13
153
190
  ```
154
191
 
155
192
  ## Extending
156
193
 
157
194
  To add a new adapter:
158
195
  1. Create `src/adapter/<name>.ts`
159
- 2. Extend `AdapterAbstract`
196
+ 2. Extend `AdapterAbstract`; call `super(namespace)` and re-merge `options` (convention 5)
160
197
  3. Implement all abstract/interface methods
161
198
  4. Add to `KnownTypes` in `src/kv.ts`
162
199
  5. Add case in `createKVClient` factory
163
200
  6. Export from `src/kv.ts`
201
+ 7. Add a client for it in `tests/_tests-runner.ts`; it must run on Node
164
202
 
165
203
  ## Documentation Index
166
204
 
167
205
  - [API Reference](./API.md) — Complete API documentation
168
- - [README](./README.md) — Quick start and installation
206
+ - [README](./README.md) — Quick start, feature matrix, breaking changes, development