@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.
@@ -0,0 +1,54 @@
1
+ /**
2
+ * @module
3
+ *
4
+ * The one seam between the postgres adapter and the database: whatever the host passed
5
+ * as `db` becomes a sqlkit `Driver`, and every statement the adapter sends goes through it.
6
+ */
7
+ import { createPgClientDriver, createPgDriver, } from "@marianmeres/sqlkit/pg";
8
+ /** One driver per pool or client object, however many adapters share it. */
9
+ const drivers = new WeakMap();
10
+ /** Whether `db` is a sqlkit `Driver` (by shape). */
11
+ export function isDriver(db) {
12
+ const d = db;
13
+ return (typeof d === "object" &&
14
+ d !== null &&
15
+ typeof d.dialect === "string" &&
16
+ typeof d.query === "function" &&
17
+ typeof d.exec === "function" &&
18
+ typeof d.transaction === "function" &&
19
+ typeof d.capabilities === "object" &&
20
+ d.capabilities !== null);
21
+ }
22
+ /** A `pg.Pool` has `connect()` and counts its clients; a `pg.Client` does not. */
23
+ export function isPool(db) {
24
+ return (typeof db === "object" &&
25
+ db !== null &&
26
+ typeof db.connect === "function" &&
27
+ typeof db.totalCount === "number");
28
+ }
29
+ /**
30
+ * The `Driver` the postgres adapter runs on. A host's `Driver` is used as it is; a
31
+ * pool or a client gets one driver per object. The adapter never closes any of them.
32
+ *
33
+ * @throws {TypeError} For a `Driver` of another dialect, or one without `savepoint()`
34
+ * (built by a sqlkit older than 0.3.0).
35
+ */
36
+ export function toPgDriver(db) {
37
+ if (isDriver(db)) {
38
+ if (db.dialect !== "pg") {
39
+ throw new TypeError(`The postgres adapter runs on PostgreSQL: got a "${db.dialect}" driver (${db.adapter})`);
40
+ }
41
+ // `transaction()` runs in the driver's `savepoint()`. The type requires it; a
42
+ // driver from an older sqlkit, passed past the type, would fail there instead.
43
+ if (typeof db.savepoint !== "function") {
44
+ throw new TypeError("The postgres adapter needs a Driver from @marianmeres/sqlkit 0.3.0 or newer: this one has no savepoint()");
45
+ }
46
+ return db;
47
+ }
48
+ let driver = drivers.get(db);
49
+ if (driver === undefined) {
50
+ driver = isPool(db) ? createPgDriver(db) : createPgClientDriver(db);
51
+ drivers.set(db, driver);
52
+ }
53
+ return driver;
54
+ }
@@ -0,0 +1,37 @@
1
+ /**
2
+ * @module
3
+ *
4
+ * The one seam between the sqlite adapter and sqlkit's node:sqlite driver. That driver's
5
+ * module imports `node:sqlite` when it loads, so it is imported here lazily, and only
6
+ * for a `DatabaseSync`: the package root loads no `node:sqlite`. A sqlkit `Driver` the
7
+ * host passes is checked here and used as it is.
8
+ */
9
+ import type { DatabaseSync } from "node:sqlite";
10
+ import type { Driver } from "@marianmeres/sqlkit";
11
+ /**
12
+ * What the sqlite adapter's `db` option takes: a node:sqlite `DatabaseSync`, or a sqlkit
13
+ * `Driver` of the `sqlite` dialect with a sync tier (`openSqlite()`'s, for one).
14
+ */
15
+ export type SqliteDb = DatabaseSync | Driver;
16
+ /**
17
+ * Whether `db` has the shape of a node:sqlite `DatabaseSync`. By shape, so nothing here
18
+ * imports `node:sqlite`. `isOpen` is read rather than `isTransaction`, which throws on a
19
+ * closed handle.
20
+ */
21
+ export declare function isDatabaseSync(db: unknown): db is DatabaseSync;
22
+ /**
23
+ * kv's own sqlkit driver over a handle the host passed: one per handle, keeping
24
+ * {@link STATEMENT_CACHE} compiled statements. Imports `@marianmeres/sqlkit/sqlite` on
25
+ * the first call.
26
+ *
27
+ * The adapter never calls `close()` on it: that would close the host's handle.
28
+ */
29
+ export declare function ownSqliteDriver(db: DatabaseSync): Promise<Driver>;
30
+ /**
31
+ * Refuses a host's `Driver` the sqlite adapter cannot run on: one of another dialect,
32
+ * and one without the sync tier or `savepoint()` a unit runs on (a sqlkit older than
33
+ * 0.3.0 built no `savepoint()`).
34
+ *
35
+ * @throws {TypeError}
36
+ */
37
+ export declare function assertSqliteDriver(db: Driver): void;
@@ -0,0 +1,67 @@
1
+ /**
2
+ * @module
3
+ *
4
+ * The one seam between the sqlite adapter and sqlkit's node:sqlite driver. That driver's
5
+ * module imports `node:sqlite` when it loads, so it is imported here lazily, and only
6
+ * for a `DatabaseSync`: the package root loads no `node:sqlite`. A sqlkit `Driver` the
7
+ * host passes is checked here and used as it is.
8
+ */
9
+ /**
10
+ * Compiled statements kv's own driver keeps, by their text: what sqlkit's `openSqlite()`
11
+ * keeps. Without a number the driver compiles every statement on every call.
12
+ */
13
+ const STATEMENT_CACHE = 128;
14
+ /** One driver per handle, however many adapters share it. */
15
+ const drivers = new WeakMap();
16
+ /**
17
+ * Whether `db` has the shape of a node:sqlite `DatabaseSync`. By shape, so nothing here
18
+ * imports `node:sqlite`. `isOpen` is read rather than `isTransaction`, which throws on a
19
+ * closed handle.
20
+ */
21
+ export function isDatabaseSync(db) {
22
+ const d = db;
23
+ return (typeof d === "object" &&
24
+ d !== null &&
25
+ typeof d.prepare === "function" &&
26
+ typeof d.exec === "function" &&
27
+ typeof d.isOpen === "boolean");
28
+ }
29
+ /**
30
+ * kv's own sqlkit driver over a handle the host passed: one per handle, keeping
31
+ * {@link STATEMENT_CACHE} compiled statements. Imports `@marianmeres/sqlkit/sqlite` on
32
+ * the first call.
33
+ *
34
+ * The adapter never calls `close()` on it: that would close the host's handle.
35
+ */
36
+ export async function ownSqliteDriver(db) {
37
+ let driver = drivers.get(db);
38
+ if (driver === undefined) {
39
+ const { createSqliteDriver } = await import("@marianmeres/sqlkit/sqlite");
40
+ // two adapters on one handle may have awaited the import together
41
+ driver =
42
+ drivers.get(db) ??
43
+ createSqliteDriver(db, { statementCache: STATEMENT_CACHE });
44
+ drivers.set(db, driver);
45
+ }
46
+ return driver;
47
+ }
48
+ /**
49
+ * Refuses a host's `Driver` the sqlite adapter cannot run on: one of another dialect,
50
+ * and one without the sync tier or `savepoint()` a unit runs on (a sqlkit older than
51
+ * 0.3.0 built no `savepoint()`).
52
+ *
53
+ * @throws {TypeError}
54
+ */
55
+ export function assertSqliteDriver(db) {
56
+ if (db.dialect !== "sqlite") {
57
+ throw new TypeError(`The sqlite adapter runs on SQLite: got a "${db.dialect}" driver (${db.adapter})`);
58
+ }
59
+ const missing = typeof db.sync !== "object" || db.sync === null
60
+ ? "no sync tier"
61
+ : typeof db.savepoint !== "function"
62
+ ? "no savepoint()"
63
+ : undefined;
64
+ if (missing) {
65
+ throw new TypeError(`The sqlite adapter needs a Driver with a sync tier and savepoint(), from @marianmeres/sqlkit 0.3.0 or newer: this one has ${missing}`);
66
+ }
67
+ }
package/package.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "@marianmeres/kv",
3
- "version": "3.1.1",
3
+ "version": "4.1.0",
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",
7
7
  "type": "module",
8
8
  "engines": {
9
- "node": ">=24.12"
9
+ "node": "^24.20.0 || >=26.6.0"
10
10
  },
11
11
  "publishConfig": {
12
12
  "access": "public"
@@ -43,14 +43,16 @@
43
43
  "storage"
44
44
  ],
45
45
  "dependencies": {
46
- "@marianmeres/clog": "^3.23.0",
47
- "@types/pg": "^8.23.1",
48
- "pg": "^8.23.1",
46
+ "@marianmeres/clog": "^3.23.1",
47
+ "@marianmeres/sqlkit": "^0.3.1",
49
48
  "redis": "^6.3.1"
50
49
  },
51
50
  "devDependencies": {
52
- "@biomejs/biome": "^2.6.4",
51
+ "@biomejs/biome": "^2.6.8",
52
+ "@electric-sql/pglite": "^0.5.17",
53
53
  "@types/node": "^26.6.6",
54
+ "@types/pg": "^8.23.1",
55
+ "pg": "^8.23.1",
54
56
  "typescript": "^7.0.2"
55
57
  },
56
58
  "scripts": {
@@ -59,15 +61,11 @@
59
61
  "typecheck": "tsc --noEmit",
60
62
  "lint": "biome check .",
61
63
  "format": "biome check --write .",
62
- "test": "node --test --env-file-if-exists=.env \"tests/**/*.test.ts\"",
63
- "test:watch": "node --test --watch --env-file-if-exists=.env \"tests/**/*.test.ts\"",
64
- "test:deno": "deno test -A --no-check --env-file tests/",
64
+ "test": "node --test --test-concurrency=1 --env-file-if-exists=.env \"tests/**/*.test.ts\"",
65
+ "test:watch": "node --test --test-concurrency=1 --watch --env-file-if-exists=.env \"tests/**/*.test.ts\"",
65
66
  "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\"",
67
- "release": "npx --yes @marianmeres/release@^2.2.0",
68
- "publish:jsr": "pnpm run test:deno && deno publish --no-check --set-version \"$npm_package_version\"",
69
- "publish:all": "pnpm publish && pnpm run publish:jsr",
70
- "rp": "pnpm run release -y && pnpm run publish:all",
71
- "rpm": "pnpm run release minor -y && pnpm run publish:all"
67
+ "release": "npx --yes @marianmeres/release@^2.3.0 --before-bump \"pnpm run ci\"",
68
+ "rp": "npm whoami >/dev/null && pnpm run release -y --before-push \"pnpm publish\"",
69
+ "rpm": "npm whoami >/dev/null && pnpm run release minor -y --before-push \"pnpm publish\""
72
70
  }
73
71
  }