@marianmeres/kv 4.0.0 → 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.
- package/AGENTS.md +108 -28
- package/API.md +123 -26
- package/README.md +113 -8
- package/dist/adapter/postgres.js +16 -6
- package/dist/adapter/sqlite.d.ts +23 -7
- package/dist/adapter/sqlite.js +228 -107
- package/dist/kv.d.ts +9 -1
- package/dist/kv.js +8 -1
- package/dist/utils/driver.d.ts +2 -1
- package/dist/utils/driver.js +7 -1
- package/dist/utils/sqlite-driver.d.ts +37 -0
- package/dist/utils/sqlite-driver.js +67 -0
- package/package.json +9 -8
|
@@ -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": "4.
|
|
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": "
|
|
9
|
+
"node": "^24.20.0 || >=26.6.0"
|
|
10
10
|
},
|
|
11
11
|
"publishConfig": {
|
|
12
12
|
"access": "public"
|
|
@@ -43,12 +43,13 @@
|
|
|
43
43
|
"storage"
|
|
44
44
|
],
|
|
45
45
|
"dependencies": {
|
|
46
|
-
"@marianmeres/clog": "^3.23.
|
|
47
|
-
"@marianmeres/sqlkit": "^0.
|
|
46
|
+
"@marianmeres/clog": "^3.23.1",
|
|
47
|
+
"@marianmeres/sqlkit": "^0.3.1",
|
|
48
48
|
"redis": "^6.3.1"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
|
-
"@biomejs/biome": "^2.6.
|
|
51
|
+
"@biomejs/biome": "^2.6.8",
|
|
52
|
+
"@electric-sql/pglite": "^0.5.17",
|
|
52
53
|
"@types/node": "^26.6.6",
|
|
53
54
|
"@types/pg": "^8.23.1",
|
|
54
55
|
"pg": "^8.23.1",
|
|
@@ -63,8 +64,8 @@
|
|
|
63
64
|
"test": "node --test --test-concurrency=1 --env-file-if-exists=.env \"tests/**/*.test.ts\"",
|
|
64
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
|
-
"release": "npx --yes @marianmeres/release@^2.
|
|
67
|
-
"rp": "pnpm run release -y
|
|
68
|
-
"rpm": "pnpm run release minor -y
|
|
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\""
|
|
69
70
|
}
|
|
70
71
|
}
|