@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/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
|
|
8
|
-
- **
|
|
9
|
-
|
|
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
|
-
├──
|
|
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
|
-
│ └──
|
|
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
|
-
|
|
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.
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
- [ ]
|
|
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
|
|
63
|
-
|
|
64
|
-
| Memory
|
|
65
|
-
| Redis
|
|
66
|
-
| PostgreSQL | `"postgres"` | `db` (pg.Pool/Client) | `tableName` limited to `[A-Za-z0-9_]` + optional `schema.` prefix
|
|
67
|
-
|
|
|
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 {
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
interface
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
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
|
-
|
|
125
|
-
|
|
126
|
-
|
|
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
|
-
#
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
#
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
#
|
|
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
|
|
206
|
+
- [README](./README.md) — Quick start, feature matrix, breaking changes, development
|