@marianmeres/kv 3.1.0 → 3.1.1
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 +6 -1
- package/API.md +10 -3
- package/dist/adapter/memory.d.ts +1 -0
- package/dist/adapter/memory.js +3 -0
- package/dist/adapter/postgres.d.ts +1 -0
- package/dist/adapter/postgres.js +9 -2
- package/dist/adapter/sqlite.d.ts +1 -0
- package/dist/adapter/sqlite.js +10 -1
- package/package.json +2 -1
package/AGENTS.md
CHANGED
|
@@ -8,6 +8,9 @@ Machine-friendly reference for AI agents working with this codebase.
|
|
|
8
8
|
- **Install**: `pnpm install` | **Test**: `pnpm test` (needs Postgres + Redis; SQLite runs in memory) |
|
|
9
9
|
**Check all**: `pnpm run ci` | **Build**: `pnpm run build`
|
|
10
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
14
|
|
|
12
15
|
## Purpose
|
|
13
16
|
|
|
@@ -33,7 +36,8 @@ tests/
|
|
|
33
36
|
├── _tests-runner.ts — Test harness: builds one client per adapter per test
|
|
34
37
|
├── _redis.ts — Redis test helper
|
|
35
38
|
├── _pg.ts — PostgreSQL test helper
|
|
36
|
-
|
|
39
|
+
├── _sqlite.ts — SQLite test helper (fresh `:memory:` database per test)
|
|
40
|
+
└── _no-destroy-child.ts — child process: an adapter left running must not hold it open
|
|
37
41
|
|
|
38
42
|
dist/ — `tsc -p tsconfig.build.json` output; gitignored; the npm payload
|
|
39
43
|
```
|
|
@@ -70,6 +74,7 @@ dist/ — `tsc -p tsconfig.build.json` output; gitignored; the
|
|
|
70
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`.
|
|
71
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.
|
|
72
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.
|
|
73
78
|
|
|
74
79
|
## Before Making Changes
|
|
75
80
|
|
package/API.md
CHANGED
|
@@ -107,6 +107,9 @@ destroy(hard?: boolean): Promise<void>
|
|
|
107
107
|
| --------- | --------- | ------- | --------------------------------------------------------------------------------- |
|
|
108
108
|
| `hard` | `boolean` | `false` | If `true`, performs a hard cleanup (e.g., drops tables in PostgreSQL and SQLite). |
|
|
109
109
|
|
|
110
|
+
Stops the TTL cleanup timer (`ttlCleanupIntervalSec`). That timer never keeps the process
|
|
111
|
+
alive on its own, so a short-lived script that skips `destroy()` still exits.
|
|
112
|
+
|
|
110
113
|
---
|
|
111
114
|
|
|
112
115
|
#### `info()`
|
|
@@ -715,6 +718,7 @@ interface AdapterMemoryOptions extends AdapterAbstractOptions {
|
|
|
715
718
|
* Interval in seconds for automatic cleanup of expired keys.
|
|
716
719
|
* Set to 0 to disable automatic cleanup (expired keys will still be
|
|
717
720
|
* lazily removed on access).
|
|
721
|
+
* The timer never keeps the process alive; `destroy()` stops it.
|
|
718
722
|
*/
|
|
719
723
|
ttlCleanupIntervalSec: number;
|
|
720
724
|
}
|
|
@@ -767,6 +771,7 @@ interface AdapterPostgresOptions extends AdapterAbstractOptions {
|
|
|
767
771
|
/**
|
|
768
772
|
* Interval in seconds for automatic cleanup of expired keys.
|
|
769
773
|
* Set to 0 to disable automatic cleanup.
|
|
774
|
+
* The timer never keeps the process alive; `destroy()` stops it.
|
|
770
775
|
*/
|
|
771
776
|
ttlCleanupIntervalSec: number;
|
|
772
777
|
}
|
|
@@ -803,15 +808,17 @@ interface AdapterSqliteOptions extends AdapterAbstractOptions {
|
|
|
803
808
|
/**
|
|
804
809
|
* Interval in seconds for automatic cleanup of expired keys.
|
|
805
810
|
* Set to 0 to disable automatic cleanup.
|
|
811
|
+
* The timer never keeps the process alive; `destroy()` stops it.
|
|
806
812
|
*/
|
|
807
813
|
ttlCleanupIntervalSec: number;
|
|
808
814
|
}
|
|
809
815
|
```
|
|
810
816
|
|
|
811
817
|
**Connection ownership:** the adapter never opens, closes or reconfigures the handle — it
|
|
812
|
-
sets no pragmas.
|
|
813
|
-
|
|
814
|
-
|
|
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
|
|
820
|
+
timeout (`new DatabaseSync(path, { timeout: 5000 })`) so a locked write waits instead of
|
|
821
|
+
failing, and consider `PRAGMA journal_mode = WAL`.
|
|
815
822
|
|
|
816
823
|
**Atomicity:** `setIfAbsent`, `cas`, `expire` and `set` are single statements.
|
|
817
824
|
`getSet`, `incr`/`decr`, `setMultiple`, `clear` and `transaction` run in `BEGIN IMMEDIATE`,
|
package/dist/adapter/memory.d.ts
CHANGED
|
@@ -12,6 +12,7 @@ export interface AdapterMemoryOptions extends AdapterAbstractOptions {
|
|
|
12
12
|
* Interval in seconds for automatic cleanup of expired keys.
|
|
13
13
|
* Set to 0 to disable automatic cleanup (expired keys will still be
|
|
14
14
|
* lazily removed on access).
|
|
15
|
+
* The timer never keeps the process alive; `destroy()` stops it.
|
|
15
16
|
*/
|
|
16
17
|
ttlCleanupIntervalSec: number;
|
|
17
18
|
}
|
package/dist/adapter/memory.js
CHANGED
|
@@ -67,6 +67,9 @@ export class AdapterMemory extends AdapterAbstract {
|
|
|
67
67
|
}
|
|
68
68
|
// schedule next...
|
|
69
69
|
this.#cleanupTimer = setTimeout(this.#maybeTTLCleanup.bind(this), this.options.ttlCleanupIntervalSec * 1000);
|
|
70
|
+
// housekeeping must not hold the process open; destroy() still clears it
|
|
71
|
+
// (`?.`: browser and worker timers are plain numbers)
|
|
72
|
+
this.#cleanupTimer.unref?.();
|
|
70
73
|
}
|
|
71
74
|
}
|
|
72
75
|
#isExpired(key) {
|
|
@@ -22,6 +22,7 @@ export interface AdapterPostgresOptions extends AdapterAbstractOptions {
|
|
|
22
22
|
/**
|
|
23
23
|
* Interval in seconds for automatic cleanup of expired keys.
|
|
24
24
|
* Set to 0 to disable automatic cleanup.
|
|
25
|
+
* The timer never keeps the process alive; `destroy()` stops it.
|
|
25
26
|
*/
|
|
26
27
|
ttlCleanupIntervalSec: number;
|
|
27
28
|
}
|
package/dist/adapter/postgres.js
CHANGED
|
@@ -65,14 +65,15 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
65
65
|
}
|
|
66
66
|
/** @inheritdoc */
|
|
67
67
|
async destroy(hard) {
|
|
68
|
-
// stop the timer first so a pending tick cannot fire during DROP
|
|
68
|
+
// stop the timer first so a pending tick cannot fire during DROP, and mark the
|
|
69
|
+
// adapter down before any await so an in-flight tick does not re-arm it
|
|
69
70
|
clearTimeout(this.#cleanupTimer);
|
|
70
71
|
this.#cleanupTimer = undefined;
|
|
72
|
+
this._initialized = false;
|
|
71
73
|
if (hard) {
|
|
72
74
|
const { db, tableName } = this.options;
|
|
73
75
|
await db.query(`DROP TABLE IF EXISTS ${tableName}`);
|
|
74
76
|
}
|
|
75
|
-
this._initialized = false;
|
|
76
77
|
}
|
|
77
78
|
async #maybeTTLCleanup() {
|
|
78
79
|
clearTimeout(this.#cleanupTimer); // safety
|
|
@@ -87,8 +88,14 @@ export class AdapterPostgres extends AdapterAbstract {
|
|
|
87
88
|
catch (err) {
|
|
88
89
|
logger?.error?.(`TTL cleanup error: ${err}`);
|
|
89
90
|
}
|
|
91
|
+
// destroy() ran while the query was in flight
|
|
92
|
+
if (!this._initialized)
|
|
93
|
+
return;
|
|
90
94
|
// schedule next...
|
|
91
95
|
this.#cleanupTimer = setTimeout(this.#maybeTTLCleanup.bind(this), this.options.ttlCleanupIntervalSec * 1000);
|
|
96
|
+
// housekeeping must not hold the process open; destroy() still clears it
|
|
97
|
+
// (`?.`: browser and worker timers are plain numbers)
|
|
98
|
+
this.#cleanupTimer.unref?.();
|
|
92
99
|
}
|
|
93
100
|
}
|
|
94
101
|
/**
|
package/dist/adapter/sqlite.d.ts
CHANGED
|
@@ -24,6 +24,7 @@ export interface AdapterSqliteOptions extends AdapterAbstractOptions {
|
|
|
24
24
|
/**
|
|
25
25
|
* Interval in seconds for automatic cleanup of expired keys.
|
|
26
26
|
* Set to 0 to disable automatic cleanup.
|
|
27
|
+
* The timer never keeps the process alive; `destroy()` stops it.
|
|
27
28
|
*/
|
|
28
29
|
ttlCleanupIntervalSec: number;
|
|
29
30
|
}
|
package/dist/adapter/sqlite.js
CHANGED
|
@@ -134,7 +134,13 @@ export class AdapterSqlite extends AdapterAbstract {
|
|
|
134
134
|
#maybeTTLCleanup() {
|
|
135
135
|
clearTimeout(this.#cleanupTimer); // safety
|
|
136
136
|
if (this.options.ttlCleanupIntervalSec) {
|
|
137
|
-
const { tableName, logger } = this.options;
|
|
137
|
+
const { db, tableName, logger } = this.options;
|
|
138
|
+
// The caller closed the handle without destroy(). Every later tick would fail
|
|
139
|
+
// the same way, so say it once and stop.
|
|
140
|
+
if (!db.isOpen) {
|
|
141
|
+
logger?.error?.("TTL cleanup stopped: the database handle was closed before destroy()");
|
|
142
|
+
return;
|
|
143
|
+
}
|
|
138
144
|
// do the cleanup now
|
|
139
145
|
try {
|
|
140
146
|
this.#stmt(`DELETE FROM ${tableName}
|
|
@@ -145,6 +151,9 @@ export class AdapterSqlite extends AdapterAbstract {
|
|
|
145
151
|
}
|
|
146
152
|
// schedule next...
|
|
147
153
|
this.#cleanupTimer = setTimeout(this.#maybeTTLCleanup.bind(this), this.options.ttlCleanupIntervalSec * 1000);
|
|
154
|
+
// housekeeping must not hold the process open; destroy() still clears it
|
|
155
|
+
// (`?.`: browser and worker timers are plain numbers)
|
|
156
|
+
this.#cleanupTimer.unref?.();
|
|
148
157
|
}
|
|
149
158
|
}
|
|
150
159
|
/**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@marianmeres/kv",
|
|
3
|
-
"version": "3.1.
|
|
3
|
+
"version": "3.1.1",
|
|
4
4
|
"description": "Key-value storage abstraction with a unified, Redis-inspired API over memory, Redis, PostgreSQL and SQLite backends.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Marian Meres",
|
|
@@ -63,6 +63,7 @@
|
|
|
63
63
|
"test:watch": "node --test --watch --env-file-if-exists=.env \"tests/**/*.test.ts\"",
|
|
64
64
|
"test:deno": "deno test -A --no-check --env-file tests/",
|
|
65
65
|
"ci": "pnpm run typecheck && pnpm run lint && pnpm test",
|
|
66
|
+
"jsr:check": "deno publish --dry-run --allow-dirty --no-check --set-version \"$npm_package_version\"",
|
|
66
67
|
"release": "npx --yes @marianmeres/release@^2.2.0",
|
|
67
68
|
"publish:jsr": "pnpm run test:deno && deno publish --no-check --set-version \"$npm_package_version\"",
|
|
68
69
|
"publish:all": "pnpm publish && pnpm run publish:jsr",
|