@statewalker/db-sqlite-node 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kotelnikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @statewalker/db-sqlite-node
+
+libSQL/SQLite Node.js driver implementing `@statewalker/db-api`, backed by `@libsql/client`.
+
+## Installation
+
+```sh
+pnpm add @statewalker/db-sqlite-node
+```
+
+## Usage
+
+```ts
+import { newNodeSqliteDb } from "@statewalker/db-sqlite-node";
+
+// In-memory (omit `path`) or file-backed persistence.
+const db = await newNodeSqliteDb({ path: "./data.db" });
+await db.exec("CREATE TABLE t (x INTEGER)");
+await db.query("SELECT * FROM t");
+```
+
+## API
+
+- `newNodeSqliteDb(options?)` — opens a local file-backed (`options.path`) or in-memory libSQL database and returns a `Db`.
+
+> Note: the underlying `@libsql/client` also supports remote Turso-cloud connections
+> (`libsql://…turso.io` + `authToken`). That is a libSQL/Turso *product* feature and is
+> out of scope for this package, which targets local/in-memory SQLite.
+
+## Related
+
+- `@statewalker/db-api` — interface contract.
+- `@statewalker/db-sqlite-browser` — Browser-side counterpart.

package/dist/index.d.mts

@@ -0,0 +1,11 @@
+import { Db, Db as Db$1, DbEntry, DbOptions, DbOptions as DbOptions$1 } from "@statewalker/db-api";
+//#region src/node-sqlite-db.d.ts
+/**
+ * Create a libSQL-backed {@link Db} using the native Node.js client.
+ *
+ * @param options.path  File path for persistent storage. Omit for in-memory.
+ */
+declare function newNodeSqliteDb(options?: DbOptions$1): Promise<Db$1>;
+//#endregion
+export { type Db, type DbEntry, type DbOptions, newNodeSqliteDb };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/node-sqlite-db.ts"],"mappings":";;;;;;;iBASsB,gBAAgB,UAAU,cAAY,QAAQ"}

package/dist/index.mjs

@@ -0,0 +1,29 @@
+import { createClient } from "@libsql/client";
+//#region src/node-sqlite-db.ts
+/**
+* Create a libSQL-backed {@link Db} using the native Node.js client.
+*
+* @param options.path  File path for persistent storage. Omit for in-memory.
+*/
+async function newNodeSqliteDb(options) {
+	const url = options?.path ? `file:${options.path}` : ":memory:";
+	const client = createClient({ url });
+	return {
+		async query(sql, params) {
+			return (await client.execute(params && params.length > 0 ? {
+				sql,
+				args: params
+			} : sql)).rows;
+		},
+		async exec(sql) {
+			await client.execute(sql);
+		},
+		async close() {
+			client.close();
+		}
+	};
+}
+//#endregion
+export { newNodeSqliteDb };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@statewalker/db-sqlite-node",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "libSQL/SQLite client driver for @statewalker/db-api, targeting Node.js environments.",
+  "homepage": "https://github.com/statewalker/statewalker-db",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/statewalker/statewalker-db.git"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@libsql/client": "^0.17.4",
+    "@statewalker/db-api": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@statewalker/db-tests": "0.1.1"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "lint": "biome check --write .",
+    "format": "biome format --write ."
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
+export { newNodeSqliteDb } from "./node-sqlite-db.js";

package/src/node-sqlite-db.test.ts

@@ -0,0 +1,147 @@
+import type { Db } from "@statewalker/db-api";
+import { runDbConformance } from "@statewalker/db-tests";
+import { afterEach, describe, expect, it } from "vitest";
+import { newNodeSqliteDb } from "./node-sqlite-db.js";
+
+// Common contract (CRUD, parameter binding, cardinality, close, file
+// persistence, error paths) is covered by the shared conformance suite.
+// libsql dialect: `?` placeholder; the spread normalizer drops libsql Row's
+// non-enumerable positional keys + length.
+runDbConformance(newNodeSqliteDb, {
+  placeholder: "?",
+  normalizeRow: (row) => ({ ...row }),
+});
+
+// Dialect-specific behavior kept per-adapter: libsql FTS5 + native vector index.
+describe("newNodeSqliteDb", () => {
+  let db: Db;
+
+  afterEach(async () => {
+    if (db) {
+      await db.close();
+    }
+  });
+
+  describe("FTS5", () => {
+    it("returns empty results for unmatched search terms", async () => {
+      db = await newNodeSqliteDb();
+      await db.exec("CREATE VIRTUAL TABLE docs2_fts USING fts5(content)");
+      await db.exec(
+        "INSERT INTO docs2_fts (rowid, content) VALUES (1, 'hello world'), (2, 'goodbye world')",
+      );
+
+      const rows = await db.query<{ content: string }>(
+        "SELECT content FROM docs2_fts WHERE docs2_fts MATCH 'nonexistent'",
+      );
+      expect(rows).toHaveLength(0);
+    });
+
+    it("searches across multiple text columns", async () => {
+      db = await newNodeSqliteDb();
+      await db.exec("CREATE VIRTUAL TABLE articles_fts USING fts5(title, body, tokenize='porter')");
+      await db.exec(`
+        INSERT INTO articles_fts (rowid, title, body) VALUES
+          (1, 'Travel Guide', 'Visit the beautiful lakes of Switzerland'),
+          (2, 'Cooking Tips', 'How to make a perfect lake trout'),
+          (3, 'Programming', 'Learn about SQL databases')
+      `);
+
+      const rows = await db.query<{ rowid: number; title: string; score: number }>(`
+        SELECT rowid, title, bm25(articles_fts) AS score
+        FROM articles_fts
+        WHERE articles_fts MATCH 'lake'
+        ORDER BY score
+      `);
+      expect(rows).toHaveLength(2);
+      const titles = rows.map((r) => r.title);
+      expect(titles).toContain("Travel Guide");
+      expect(titles).toContain("Cooking Tips");
+    });
+
+    it("creates an FTS5 index and performs full-text search", async () => {
+      db = await newNodeSqliteDb();
+      await db.exec("CREATE VIRTUAL TABLE docs_fts USING fts5(content)");
+      await db.exec(`
+        INSERT INTO docs_fts (rowid, content) VALUES
+          (1, 'the quick brown fox jumps over the lazy dog'),
+          (2, 'a lazy cat sleeps on the mat'),
+          (3, 'the fox and the hound are friends')
+      `);
+
+      const rows = await db.query<{ rowid: number; content: string; score: number }>(`
+        SELECT rowid, content, bm25(docs_fts) AS score
+        FROM docs_fts
+        WHERE docs_fts MATCH 'fox'
+        ORDER BY score
+      `);
+
+      expect(rows.length).toBeGreaterThanOrEqual(1);
+      const rowids = rows.map((r) => r.rowid);
+      expect(rowids).toContain(1);
+      expect(rowids).toContain(3);
+    });
+  });
+
+  describe("vector search", () => {
+    it("creates index and performs vector similarity search", async () => {
+      db = await newNodeSqliteDb();
+
+      await db.exec("CREATE TABLE embeddings (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
+      await db.exec("CREATE INDEX vec_idx ON embeddings (libsql_vector_idx(vec))");
+      await db.exec(`
+        INSERT INTO embeddings VALUES
+          (1, vector32('[1.0, 0.0, 0.0]')),
+          (2, vector32('[0.0, 1.0, 0.0]')),
+          (3, vector32('[0.0, 0.0, 1.0]'))
+      `);
+
+      const rows = await db.query<{ id: number }>(
+        "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",
+      );
+
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.id).toBe(1);
+    });
+
+    it("returns k nearest neighbors ordered by distance", async () => {
+      db = await newNodeSqliteDb();
+
+      await db.exec("CREATE TABLE vectors (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
+      await db.exec("CREATE INDEX vec_idx2 ON vectors (libsql_vector_idx(vec))");
+      await db.exec(`
+        INSERT INTO vectors VALUES
+          (1, vector32('[1.0, 0.0, 0.0]')),
+          (2, vector32('[0.9, 0.1, 0.0]')),
+          (3, vector32('[0.0, 1.0, 0.0]')),
+          (4, vector32('[0.0, 0.0, 1.0]'))
+      `);
+
+      const rows = await db.query<{ id: number }>(
+        "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",
+      );
+
+      expect(rows).toHaveLength(2);
+      const ids = rows.map((r) => r.id);
+      expect(ids).toContain(1);
+      expect(ids).toContain(2);
+    });
+
+    it("works without index (brute-force scan)", async () => {
+      db = await newNodeSqliteDb();
+
+      await db.exec("CREATE TABLE vecs_no_idx (id INTEGER PRIMARY KEY, vec F32_BLOB(3))");
+      await db.exec(`
+        INSERT INTO vecs_no_idx VALUES
+          (1, vector32('[1.0, 0.0, 0.0]')),
+          (2, vector32('[0.0, 1.0, 0.0]'))
+      `);
+
+      const rows = await db.query<{ id: number }>(
+        "SELECT id FROM vecs_no_idx ORDER BY vector_distance_cos(vec, vector32('[0.0, 0.9, 0.1]')) LIMIT 1",
+      );
+
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.id).toBe(2);
+    });
+  });
+});

package/src/node-sqlite-db.ts

@@ -0,0 +1,30 @@
+import type { InValue } from "@libsql/client";
+import { createClient } from "@libsql/client";
+import type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
+
+/**
+ * Create a libSQL-backed {@link Db} using the native Node.js client.
+ *
+ * @param options.path  File path for persistent storage. Omit for in-memory.
+ */
+export async function newNodeSqliteDb(options?: DbOptions): Promise<Db> {
+  const url = options?.path ? `file:${options.path}` : ":memory:";
+  const client = createClient({ url });
+
+  return {
+    async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {
+      const result = await client.execute(
+        params && params.length > 0 ? { sql, args: params as InValue[] } : sql,
+      );
+      return result.rows as unknown as T[];
+    },
+
+    async exec(sql: string): Promise<void> {
+      await client.execute(sql);
+    },
+
+    async close(): Promise<void> {
+      client.close();
+    },
+  };
+}