@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 CHANGED
@@ -1,33 +1,66 @@
1
1
  # @statewalker/db-sqlite-node
2
2
 
3
- libSQL/SQLite Node.js driver implementing `@statewalker/db-api`, backed by `@libsql/client`.
3
+ ## What it is
4
4
 
5
- ## Installation
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
- ## Usage
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.query("SELECT * FROM t");
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
- ## API
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
- > Note: the underlying `@libsql/client` also supports remote Turso-cloud connections
27
- > (`libsql://…turso.io` + `authToken`). That is a libSQL/Turso *product* feature and is
28
- > out of scope for this package, which targets local/in-memory SQLite.
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
- ## Related
64
+ ## License
31
65
 
32
- - `@statewalker/db-api` — interface contract.
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 libSQL-backed {@link Db} using the native Node.js client.
4
+ * Create a SQLite {@link Db} on Node.js's built-in `node:sqlite`.
5
5
  *
6
- * @param options.path File path for persistent storage. Omit for in-memory.
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 { createClient } from "@libsql/client";
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 libSQL-backed {@link Db} using the native Node.js client.
5
+ * Create a SQLite {@link Db} on Node.js's built-in `node:sqlite`.
5
6
  *
6
- * @param options.path File path for persistent storage. Omit for in-memory.
7
+ * @param options.path Database file. Omit for an in-memory database.
7
8
  */
8
9
  async function newNodeSqliteDb(options) {
9
- const url = options?.path ? `file:${options.path}` : ":memory:";
10
- const client = createClient({ url });
11
- return {
12
- async query(sql, params) {
13
- return (await client.execute(params && params.length > 0 ? {
14
- sql,
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 };
@@ -1 +1 @@
1
- {"version":3,"file":"index.mjs","names":[],"sources":["../src/node-sqlite-db.ts"],"sourcesContent":["import type { InValue } from \"@libsql/client\";\nimport { createClient } from \"@libsql/client\";\nimport type { Db, DbEntry, DbOptions } from \"@statewalker/db-api\";\n\n/**\n * Create a libSQL-backed {@link Db} using the native Node.js client.\n *\n * @param options.path File path for persistent storage. Omit for in-memory.\n */\nexport async function newNodeSqliteDb(options?: DbOptions): Promise<Db> {\n const url = options?.path ? `file:${options.path}` : \":memory:\";\n const client = createClient({ url });\n\n return {\n async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {\n const result = await client.execute(\n params && params.length > 0 ? { sql, args: params as InValue[] } : sql,\n );\n return result.rows as unknown as T[];\n },\n\n async exec(sql: string): Promise<void> {\n await client.execute(sql);\n },\n\n async close(): Promise<void> {\n client.close();\n },\n };\n}\n"],"mappings":";;;;;;;AASA,eAAsB,gBAAgB,SAAkC;CACtE,MAAM,MAAM,SAAS,OAAO,QAAQ,QAAQ,SAAS;CACrD,MAAM,SAAS,aAAa,EAAE,IAAI,CAAC;CAEnC,OAAO;EACL,MAAM,MAAmB,KAAa,QAAkC;GAItE,QAAO,MAHc,OAAO,QAC1B,UAAU,OAAO,SAAS,IAAI;IAAE;IAAK,MAAM;GAAoB,IAAI,GACrE,EAAA,CACc;EAChB;EAEA,MAAM,KAAK,KAA4B;GACrC,MAAM,OAAO,QAAQ,GAAG;EAC1B;EAEA,MAAM,QAAuB;GAC3B,OAAO,MAAM;EACf;CACF;AACF"}
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.2.0",
3
+ "version": "0.3.0",
4
4
  "private": false,
5
5
  "type": "module",
6
- "description": "libSQL/SQLite client driver for @statewalker/db-api, targeting Node.js environments.",
7
- "homepage": "https://github.com/statewalker/statewalker-db",
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+ssh://git@github.com/statewalker/statewalker-db.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
- "@libsql/client": "^0.18.0",
30
- "@statewalker/db-api": "^0.1.2"
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 (CRUD, parameter binding, cardinality, close, file
7
- // persistence, error paths) is covered by the shared conformance suite.
8
- // libsql dialect: `?` placeholder; the spread normalizer drops libsql Row's
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
- // Dialect-specific behavior kept per-adapter: libsql FTS5 + native vector index.
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
  });
@@ -1,30 +1,18 @@
1
- import type { InValue } from "@libsql/client";
2
- import { createClient } from "@libsql/client";
3
- import type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
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 libSQL-backed {@link Db} using the native Node.js client.
6
+ * Create a SQLite {@link Db} on Node.js's built-in `node:sqlite`.
7
7
  *
8
- * @param options.path File path for persistent storage. Omit for in-memory.
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 url = options?.path ? `file:${options.path}` : ":memory:";
12
- const client = createClient({ url });
13
-
14
- return {
15
- async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {
16
- const result = await client.execute(
17
- params && params.length > 0 ? { sql, args: params as InValue[] } : sql,
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
  }