@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 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
- └── _sqlite.ts — SQLite test helper (fresh `:memory:` database per test)
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. For several processes on one file, open it with a busy timeout
813
- (`new DatabaseSync(path, { timeout: 5000 })`) so a locked write waits instead of failing,
814
- and consider `PRAGMA journal_mode = WAL`.
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`,
@@ -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
  }
@@ -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
  }
@@ -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
  /**
@@ -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
  }
@@ -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.0",
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",