@statewalker/db-sqlite-node 0.2.0 → 0.3.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/README.md +48 -15
- package/dist/index.d.mts +2 -2
- package/dist/index.mjs +10 -19
- package/dist/index.mjs.map +1 -1
- package/package.json +13 -6
- package/src/node-sqlite-db.test.ts +13 -73
- package/src/node-sqlite-db.ts +12 -24
package/README.md
CHANGED
|
@@ -1,33 +1,66 @@
|
|
|
1
1
|
# @statewalker/db-sqlite-node
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## What it is
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
A SQLite driver for Node.js that implements `Db` from `@statewalker/db-api` on Node.js's
|
|
6
|
+
built-in `node:sqlite` (Node.js 22.13 or later; Node.js 24.21 bundles SQLite 3.53.4), with a
|
|
7
|
+
local file or an in-memory database.
|
|
8
|
+
Its Db works with `inTransaction` from `@statewalker/db-sqlite`. FTS5 is included, with the
|
|
9
|
+
`unicode61`, `porter` and `trigram` tokenizers.
|
|
10
|
+
|
|
11
|
+
## Why it exists
|
|
12
|
+
|
|
13
|
+
It lets code written against `Db` run on SQLite in Node.js, with the same SQL
|
|
14
|
+
features that `@statewalker/db-sqlite-browser` has in the browser. Search and
|
|
15
|
+
storage code can be built and tested in Node.js and shipped to the browser
|
|
16
|
+
unchanged. It needs no native addon or extra download, since the engine ships with Node.js.
|
|
17
|
+
|
|
18
|
+
## How to use
|
|
6
19
|
|
|
7
20
|
```sh
|
|
8
21
|
pnpm add @statewalker/db-sqlite-node
|
|
9
22
|
```
|
|
10
23
|
|
|
11
|
-
|
|
24
|
+
| Import | Gives | Environment |
|
|
25
|
+
| --- | --- | --- |
|
|
26
|
+
| `@statewalker/db-sqlite-node` | `newNodeSqliteDb`; types `Db`, `DbEntry`, `DbOptions` re-exported from `@statewalker/db-api` | Node.js |
|
|
27
|
+
|
|
28
|
+
`newNodeSqliteDb(options?)` returns `Promise<Db>`. It opens `path`, or `:memory:` without one.
|
|
29
|
+
The `Db` implements `query`, `exec` and `close`; it has no `flush` (every commit is on disk).
|
|
30
|
+
Use `?` placeholders. Wrap related writes in `inTransaction(db, async (tx) => ...)` from
|
|
31
|
+
`@statewalker/db-sqlite`.
|
|
32
|
+
|
|
33
|
+
## Examples
|
|
12
34
|
|
|
13
35
|
```ts
|
|
14
36
|
import { newNodeSqliteDb } from "@statewalker/db-sqlite-node";
|
|
15
37
|
|
|
16
|
-
// In-memory (omit `path`) or file-backed persistence.
|
|
17
38
|
const db = await newNodeSqliteDb({ path: "./data.db" });
|
|
18
|
-
await db.exec("CREATE TABLE t (x INTEGER)");
|
|
19
|
-
await db.
|
|
39
|
+
await db.exec("CREATE TABLE IF NOT EXISTS t (x INTEGER)");
|
|
40
|
+
await db.exec("INSERT INTO t VALUES (1), (2)");
|
|
41
|
+
const rows = await db.query<{ x: number }>("SELECT x FROM t WHERE x > ?", [1]);
|
|
42
|
+
await db.close();
|
|
20
43
|
```
|
|
21
44
|
|
|
22
|
-
##
|
|
23
|
-
|
|
24
|
-
- `newNodeSqliteDb(options?)` — opens a local file-backed (`options.path`) or in-memory libSQL database and returns a `Db`.
|
|
45
|
+
## Internals
|
|
25
46
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
47
|
+
- **Calls are queued.** The Db runs one call at a time in call order, and opens transactions
|
|
48
|
+
with `BEGIN IMMEDIATE` (see `@statewalker/db-sqlite`). `node:sqlite` is synchronous, so a long
|
|
49
|
+
statement blocks the event loop while it runs.
|
|
50
|
+
- **`query` runs one statement.** Anything after the first `;` is ignored without an error;
|
|
51
|
+
use `exec` for multi-statement scripts.
|
|
52
|
+
- **Rows are plain objects with a `null` prototype**, BLOBs are `Uint8Array`, integers are
|
|
53
|
+
JavaScript numbers: reading an integer above 2^53 rejects the whole query with `Value is too
|
|
54
|
+
large to be represented as a JavaScript number: 9007199254740993`.
|
|
55
|
+
- **Errors are `node:sqlite`'s.** A path in a missing directory rejects with
|
|
56
|
+
`unable to open database file`; bad SQL rejects with `near "...": syntax error`; a call after
|
|
57
|
+
`close()` rejects with `db-sqlite: the database is closed`.
|
|
58
|
+
- **Node.js 22 prints `ExperimentalWarning: SQLite is an experimental feature`** on first use,
|
|
59
|
+
because it still marks `node:sqlite` experimental. It is harmless; Node.js 24.21 prints
|
|
60
|
+
nothing.
|
|
61
|
+
- **Dependencies:** `@statewalker/db-sqlite` (queue and transactions), `@statewalker/db-api`
|
|
62
|
+
(types). The engine is part of Node.js.
|
|
29
63
|
|
|
30
|
-
##
|
|
64
|
+
## License
|
|
31
65
|
|
|
32
|
-
|
|
33
|
-
- `@statewalker/db-sqlite-browser` — Browser-side counterpart.
|
|
66
|
+
MIT
|
package/dist/index.d.mts
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { Db, Db as Db$1, DbEntry, DbOptions, DbOptions as DbOptions$1 } from "@statewalker/db-api";
|
|
2
2
|
//#region src/node-sqlite-db.d.ts
|
|
3
3
|
/**
|
|
4
|
-
* Create a
|
|
4
|
+
* Create a SQLite {@link Db} on Node.js's built-in `node:sqlite`.
|
|
5
5
|
*
|
|
6
|
-
* @param options.path
|
|
6
|
+
* @param options.path Database file. Omit for an in-memory database.
|
|
7
7
|
*/
|
|
8
8
|
export declare function newNodeSqliteDb(options?: DbOptions$1): Promise<Db$1>;
|
|
9
9
|
//#endregion
|
package/dist/index.mjs
CHANGED
|
@@ -1,27 +1,18 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { DatabaseSync } from "node:sqlite";
|
|
2
|
+
import { newSerialisedSqliteDb } from "@statewalker/db-sqlite";
|
|
2
3
|
//#region src/node-sqlite-db.ts
|
|
3
4
|
/**
|
|
4
|
-
* Create a
|
|
5
|
+
* Create a SQLite {@link Db} on Node.js's built-in `node:sqlite`.
|
|
5
6
|
*
|
|
6
|
-
* @param options.path
|
|
7
|
+
* @param options.path Database file. Omit for an in-memory database.
|
|
7
8
|
*/
|
|
8
9
|
async function newNodeSqliteDb(options) {
|
|
9
|
-
const
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
args: params
|
|
16
|
-
} : sql)).rows;
|
|
17
|
-
},
|
|
18
|
-
async exec(sql) {
|
|
19
|
-
await client.execute(sql);
|
|
20
|
-
},
|
|
21
|
-
async close() {
|
|
22
|
-
client.close();
|
|
23
|
-
}
|
|
24
|
-
};
|
|
10
|
+
const db = new DatabaseSync(options?.path ?? ":memory:");
|
|
11
|
+
return newSerialisedSqliteDb({
|
|
12
|
+
all: (sql, params) => db.prepare(sql).all(...params),
|
|
13
|
+
exec: (sql) => db.exec(sql),
|
|
14
|
+
close: () => db.close()
|
|
15
|
+
});
|
|
25
16
|
}
|
|
26
17
|
//#endregion
|
|
27
18
|
export { newNodeSqliteDb };
|
package/dist/index.mjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.mjs","names":[],"sources":["../src/node-sqlite-db.ts"],"sourcesContent":["import type
|
|
1
|
+
{"version":3,"file":"index.mjs","names":[],"sources":["../src/node-sqlite-db.ts"],"sourcesContent":["import { DatabaseSync, type SQLInputValue } from \"node:sqlite\";\nimport type { Db, DbOptions } from \"@statewalker/db-api\";\nimport { newSerialisedSqliteDb } from \"@statewalker/db-sqlite\";\n\n/**\n * Create a SQLite {@link Db} on Node.js's built-in `node:sqlite`.\n *\n * @param options.path Database file. Omit for an in-memory database.\n */\nexport async function newNodeSqliteDb(options?: DbOptions): Promise<Db> {\n const db = new DatabaseSync(options?.path ?? \":memory:\");\n return newSerialisedSqliteDb({\n all: (sql, params) =>\n db.prepare(sql).all(...(params as SQLInputValue[])) as Record<string, unknown>[],\n exec: (sql) => db.exec(sql),\n close: () => db.close(),\n });\n}\n"],"mappings":";;;;;;;;AASA,eAAsB,gBAAgB,SAAkC;CACtE,MAAM,KAAK,IAAI,aAAa,SAAS,QAAQ,UAAU;CACvD,OAAO,sBAAsB;EAC3B,MAAM,KAAK,WACT,GAAG,QAAQ,GAAG,CAAC,CAAC,IAAI,GAAI,MAA0B;EACpD,OAAO,QAAQ,GAAG,KAAK,GAAG;EAC1B,aAAa,GAAG,MAAM;CACxB,CAAC;AACH"}
|
package/package.json
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statewalker/db-sqlite-node",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
|
-
"description": "
|
|
7
|
-
"
|
|
6
|
+
"description": "SQLite driver for @statewalker/db-api on Node.js's built-in node:sqlite, with transactions through @statewalker/db-sqlite.",
|
|
7
|
+
"bugs": {
|
|
8
|
+
"url": "https://github.com/statewalker/statewalker-db/issues"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://github.com/statewalker/statewalker-db/tree/main/packages/db-sqlite-node#readme",
|
|
8
11
|
"author": {
|
|
9
12
|
"name": "Mikhail Kotelnikov",
|
|
10
13
|
"email": "mikhail.kotelnikov@gmail.com"
|
|
@@ -12,7 +15,8 @@
|
|
|
12
15
|
"license": "MIT",
|
|
13
16
|
"repository": {
|
|
14
17
|
"type": "git",
|
|
15
|
-
"url": "git+
|
|
18
|
+
"url": "git+https://github.com/statewalker/statewalker-db.git",
|
|
19
|
+
"directory": "packages/db-sqlite-node"
|
|
16
20
|
},
|
|
17
21
|
"exports": {
|
|
18
22
|
".": {
|
|
@@ -26,8 +30,8 @@
|
|
|
26
30
|
"src"
|
|
27
31
|
],
|
|
28
32
|
"dependencies": {
|
|
29
|
-
"@
|
|
30
|
-
"@statewalker/db-api": "^0.1.
|
|
33
|
+
"@statewalker/db-sqlite": "^0.1.0",
|
|
34
|
+
"@statewalker/db-api": "^0.1.4"
|
|
31
35
|
},
|
|
32
36
|
"devDependencies": {
|
|
33
37
|
"@types/node": "^26.6.4",
|
|
@@ -37,6 +41,9 @@
|
|
|
37
41
|
"vitest": "^5.0.3",
|
|
38
42
|
"@statewalker/db-tests": "^0.1.1"
|
|
39
43
|
},
|
|
44
|
+
"engines": {
|
|
45
|
+
"node": ">=22.13"
|
|
46
|
+
},
|
|
40
47
|
"sideEffects": false,
|
|
41
48
|
"publishConfig": {
|
|
42
49
|
"access": "public"
|
|
@@ -1,18 +1,13 @@
|
|
|
1
1
|
import type { Db } from "@statewalker/db-api";
|
|
2
|
-
import { runDbConformance } from "@statewalker/db-tests";
|
|
2
|
+
import { runDbConformance, runSqliteTransactionConformance } from "@statewalker/db-tests";
|
|
3
3
|
import { afterEach, describe, expect, it } from "vitest";
|
|
4
4
|
import { newNodeSqliteDb } from "./node-sqlite-db.js";
|
|
5
5
|
|
|
6
|
-
// Common contract
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
// non-enumerable positional keys + length.
|
|
10
|
-
runDbConformance(newNodeSqliteDb, {
|
|
11
|
-
placeholder: "?",
|
|
12
|
-
normalizeRow: (row) => ({ ...row }),
|
|
13
|
-
});
|
|
6
|
+
// Common contract and SQLite transactions come from the shared suites; FTS5 stays here.
|
|
7
|
+
runDbConformance(newNodeSqliteDb, { placeholder: "?" });
|
|
8
|
+
runSqliteTransactionConformance(() => newNodeSqliteDb());
|
|
14
9
|
|
|
15
|
-
//
|
|
10
|
+
// Engine-specific behaviour kept per driver: FTS5 with the default, porter and trigram tokenizers.
|
|
16
11
|
describe("newNodeSqliteDb", () => {
|
|
17
12
|
let db: Db;
|
|
18
13
|
|
|
@@ -23,6 +18,14 @@ describe("newNodeSqliteDb", () => {
|
|
|
23
18
|
});
|
|
24
19
|
|
|
25
20
|
describe("FTS5", () => {
|
|
21
|
+
it("has the trigram tokenizer (substring search)", async () => {
|
|
22
|
+
db = await newNodeSqliteDb();
|
|
23
|
+
await db.exec("CREATE VIRTUAL TABLE g USING fts5(c, tokenize='trigram')");
|
|
24
|
+
await db.exec("INSERT INTO g VALUES ('idx_lefthand')");
|
|
25
|
+
const rows = await db.query<{ c: string }>("SELECT c FROM g WHERE g MATCH 'x_le'");
|
|
26
|
+
expect(rows.map((r) => r.c)).toEqual(["idx_lefthand"]);
|
|
27
|
+
});
|
|
28
|
+
|
|
26
29
|
it("returns empty results for unmatched search terms", async () => {
|
|
27
30
|
db = await newNodeSqliteDb();
|
|
28
31
|
await db.exec("CREATE VIRTUAL TABLE docs2_fts USING fts5(content)");
|
|
@@ -81,67 +84,4 @@ describe("newNodeSqliteDb", () => {
|
|
|
81
84
|
expect(rowids).toContain(3);
|
|
82
85
|
});
|
|
83
86
|
});
|
|
84
|
-
|
|
85
|
-
describe("vector search", () => {
|
|
86
|
-
it("creates index and performs vector similarity search", async () => {
|
|
87
|
-
db = await newNodeSqliteDb();
|
|
88
|
-
|
|
89
|
-
await db.exec("CREATE TABLE embeddings (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
|
|
90
|
-
await db.exec("CREATE INDEX vec_idx ON embeddings (libsql_vector_idx(vec))");
|
|
91
|
-
await db.exec(`
|
|
92
|
-
INSERT INTO embeddings VALUES
|
|
93
|
-
(1, vector32('[1.0, 0.0, 0.0]')),
|
|
94
|
-
(2, vector32('[0.0, 1.0, 0.0]')),
|
|
95
|
-
(3, vector32('[0.0, 0.0, 1.0]'))
|
|
96
|
-
`);
|
|
97
|
-
|
|
98
|
-
const rows = await db.query<{ id: number }>(
|
|
99
|
-
"SELECT e.id FROM vector_top_k('vec_idx', '[1.0, 0.1, 0.0]', 1) AS v JOIN embeddings e ON e.rowid = v.id",
|
|
100
|
-
);
|
|
101
|
-
|
|
102
|
-
expect(rows).toHaveLength(1);
|
|
103
|
-
expect(rows[0]?.id).toBe(1);
|
|
104
|
-
});
|
|
105
|
-
|
|
106
|
-
it("returns k nearest neighbors ordered by distance", async () => {
|
|
107
|
-
db = await newNodeSqliteDb();
|
|
108
|
-
|
|
109
|
-
await db.exec("CREATE TABLE vectors (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
|
|
110
|
-
await db.exec("CREATE INDEX vec_idx2 ON vectors (libsql_vector_idx(vec))");
|
|
111
|
-
await db.exec(`
|
|
112
|
-
INSERT INTO vectors VALUES
|
|
113
|
-
(1, vector32('[1.0, 0.0, 0.0]')),
|
|
114
|
-
(2, vector32('[0.9, 0.1, 0.0]')),
|
|
115
|
-
(3, vector32('[0.0, 1.0, 0.0]')),
|
|
116
|
-
(4, vector32('[0.0, 0.0, 1.0]'))
|
|
117
|
-
`);
|
|
118
|
-
|
|
119
|
-
const rows = await db.query<{ id: number }>(
|
|
120
|
-
"SELECT e.id FROM vector_top_k('vec_idx2', '[1.0, 0.0, 0.0]', 2) AS v JOIN vectors e ON e.rowid = v.id",
|
|
121
|
-
);
|
|
122
|
-
|
|
123
|
-
expect(rows).toHaveLength(2);
|
|
124
|
-
const ids = rows.map((r) => r.id);
|
|
125
|
-
expect(ids).toContain(1);
|
|
126
|
-
expect(ids).toContain(2);
|
|
127
|
-
});
|
|
128
|
-
|
|
129
|
-
it("works without index (brute-force scan)", async () => {
|
|
130
|
-
db = await newNodeSqliteDb();
|
|
131
|
-
|
|
132
|
-
await db.exec("CREATE TABLE vecs_no_idx (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
|
|
133
|
-
await db.exec(`
|
|
134
|
-
INSERT INTO vecs_no_idx VALUES
|
|
135
|
-
(1, vector32('[1.0, 0.0, 0.0]')),
|
|
136
|
-
(2, vector32('[0.0, 1.0, 0.0]'))
|
|
137
|
-
`);
|
|
138
|
-
|
|
139
|
-
const rows = await db.query<{ id: number }>(
|
|
140
|
-
"SELECT id FROM vecs_no_idx ORDER BY vector_distance_cos(vec, vector32('[0.0, 0.9, 0.1]')) LIMIT 1",
|
|
141
|
-
);
|
|
142
|
-
|
|
143
|
-
expect(rows).toHaveLength(1);
|
|
144
|
-
expect(rows[0]?.id).toBe(2);
|
|
145
|
-
});
|
|
146
|
-
});
|
|
147
87
|
});
|
package/src/node-sqlite-db.ts
CHANGED
|
@@ -1,30 +1,18 @@
|
|
|
1
|
-
import type
|
|
2
|
-
import {
|
|
3
|
-
import
|
|
1
|
+
import { DatabaseSync, type SQLInputValue } from "node:sqlite";
|
|
2
|
+
import type { Db, DbOptions } from "@statewalker/db-api";
|
|
3
|
+
import { newSerialisedSqliteDb } from "@statewalker/db-sqlite";
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
|
-
* Create a
|
|
6
|
+
* Create a SQLite {@link Db} on Node.js's built-in `node:sqlite`.
|
|
7
7
|
*
|
|
8
|
-
* @param options.path
|
|
8
|
+
* @param options.path Database file. Omit for an in-memory database.
|
|
9
9
|
*/
|
|
10
10
|
export async function newNodeSqliteDb(options?: DbOptions): Promise<Db> {
|
|
11
|
-
const
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
);
|
|
19
|
-
return result.rows as unknown as T[];
|
|
20
|
-
},
|
|
21
|
-
|
|
22
|
-
async exec(sql: string): Promise<void> {
|
|
23
|
-
await client.execute(sql);
|
|
24
|
-
},
|
|
25
|
-
|
|
26
|
-
async close(): Promise<void> {
|
|
27
|
-
client.close();
|
|
28
|
-
},
|
|
29
|
-
};
|
|
11
|
+
const db = new DatabaseSync(options?.path ?? ":memory:");
|
|
12
|
+
return newSerialisedSqliteDb({
|
|
13
|
+
all: (sql, params) =>
|
|
14
|
+
db.prepare(sql).all(...(params as SQLInputValue[])) as Record<string, unknown>[],
|
|
15
|
+
exec: (sql) => db.exec(sql),
|
|
16
|
+
close: () => db.close(),
|
|
17
|
+
});
|
|
30
18
|
}
|