@statewalker/db-duckdb-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,27 @@
+# @statewalker/db-duckdb-node
+
+DuckDB Node.js driver implementing `@statewalker/db-api`, backed by `@duckdb/node-api`.
+
+## Installation
+
+```sh
+pnpm add @statewalker/db-duckdb-node
+```
+
+## Usage
+
+```ts
+import { createDuckDbNodeClient } from "@statewalker/db-duckdb-node";
+
+const db = await createDuckDbNodeClient({ path: "./data.duckdb" });
+await db.execute("CREATE TABLE t (x INTEGER)");
+```
+
+## API
+
+- `createDuckDbNodeClient(options)` — opens an on-disk or in-memory DuckDB file and returns a `DbClient`.
+
+## Related
+
+- `@statewalker/db-api` — interface contract.
+- `@statewalker/db-duckdb-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-duckdb.d.ts
+/**
+ * Create a DuckDB-backed {@link Db} using native Node.js bindings.
+ *
+ * @param options.path  File path for persistent storage. Omit for in-memory.
+ */
+declare function newNodeDuckDb(options?: DbOptions$1): Promise<Db$1>;
+//#endregion
+export { type Db, type DbEntry, type DbOptions, newNodeDuckDb };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

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

package/dist/index.mjs

@@ -0,0 +1,32 @@
+import { DuckDBInstance } from "@duckdb/node-api";
+//#region src/node-duckdb.ts
+/**
+* Create a DuckDB-backed {@link Db} using native Node.js bindings.
+*
+* @param options.path  File path for persistent storage. Omit for in-memory.
+*/
+async function newNodeDuckDb(options) {
+	const instance = await DuckDBInstance.create(options?.path ?? ":memory:");
+	const connection = await instance.connect();
+	return {
+		async query(sql, params) {
+			if (params && params.length > 0) {
+				const prepared = await connection.prepare(sql);
+				prepared.bind(params);
+				return (await prepared.runAndReadAll()).getRowObjectsJS();
+			}
+			return (await connection.runAndReadAll(sql)).getRowObjectsJS();
+		},
+		async exec(sql) {
+			await connection.run(sql);
+		},
+		async close() {
+			connection.closeSync();
+			instance.closeSync();
+		}
+	};
+}
+//#endregion
+export { newNodeDuckDb };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/node-duckdb.ts"],"sourcesContent":["import type { DuckDBValue } from \"@duckdb/node-api\";\nimport { DuckDBInstance } from \"@duckdb/node-api\";\nimport type { Db, DbEntry, DbOptions } from \"@statewalker/db-api\";\n\n/**\n * Create a DuckDB-backed {@link Db} using native Node.js bindings.\n *\n * @param options.path  File path for persistent storage. Omit for in-memory.\n */\nexport async function newNodeDuckDb(options?: DbOptions): Promise<Db> {\n  const instance = await DuckDBInstance.create(options?.path ?? \":memory:\");\n  const connection = await instance.connect();\n\n  return {\n    async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {\n      if (params && params.length > 0) {\n        const prepared = await connection.prepare(sql);\n        prepared.bind(params as DuckDBValue[]);\n        const reader = await prepared.runAndReadAll();\n        return reader.getRowObjectsJS() as T[];\n      }\n      const reader = await connection.runAndReadAll(sql);\n      return reader.getRowObjectsJS() as T[];\n    },\n\n    async exec(sql: string): Promise<void> {\n      await connection.run(sql);\n    },\n\n    async close(): Promise<void> {\n      connection.closeSync();\n      instance.closeSync();\n    },\n  };\n}\n"],"mappings":";;;;;;;AASA,eAAsB,cAAc,SAAkC;CACpE,MAAM,WAAW,MAAM,eAAe,OAAO,SAAS,QAAQ,UAAU;CACxE,MAAM,aAAa,MAAM,SAAS,QAAQ;CAE1C,OAAO;EACL,MAAM,MAAmB,KAAa,QAAkC;GACtE,IAAI,UAAU,OAAO,SAAS,GAAG;IAC/B,MAAM,WAAW,MAAM,WAAW,QAAQ,GAAG;IAC7C,SAAS,KAAK,MAAuB;IAErC,QAAO,MADc,SAAS,cAAc,EAAA,CAC9B,gBAAgB;GAChC;GAEA,QAAO,MADc,WAAW,cAAc,GAAG,EAAA,CACnC,gBAAgB;EAChC;EAEA,MAAM,KAAK,KAA4B;GACrC,MAAM,WAAW,IAAI,GAAG;EAC1B;EAEA,MAAM,QAAuB;GAC3B,WAAW,UAAU;GACrB,SAAS,UAAU;EACrB;CACF;AACF"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@statewalker/db-duckdb-node",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "DuckDB Node.js driver for @statewalker/db-api using @duckdb/node-api.",
+  "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": {
+    "@duckdb/node-api": "^1.5.5-r.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 { newNodeDuckDb } from "./node-duckdb.js";

package/src/node-duckdb.test.ts

@@ -0,0 +1,172 @@
+import type { Db } from "@statewalker/db-api";
+import { runDbConformance } from "@statewalker/db-tests";
+import { afterEach, describe, expect, it } from "vitest";
+import { newNodeDuckDb } from "./node-duckdb.js";
+
+// Common contract (CRUD, parameter binding, cardinality, close, file
+// persistence, error paths) is covered by the shared conformance suite.
+// duckdb dialect: `$1` placeholder; rows are already plain, so the spread
+// normalizer is an identity-style copy.
+runDbConformance(newNodeDuckDb, {
+  placeholder: "$1",
+  normalizeRow: (row) => ({ ...row }),
+});
+
+// Dialect-specific behavior kept per-adapter: DuckDB FTS extension + VSS/HNSW.
+describe("newNodeDuckDb", () => {
+  let db: Db;
+
+  afterEach(async () => {
+    if (db) {
+      await db.close();
+    }
+  });
+
+  describe("FTS extension", () => {
+    it("returns empty results for unmatched search terms", async () => {
+      db = await newNodeDuckDb();
+      await db.exec("INSTALL fts");
+      await db.exec("LOAD fts");
+      await db.exec("CREATE TABLE docs2 (id INTEGER, content VARCHAR)");
+      await db.exec("INSERT INTO docs2 VALUES (1, 'hello world'), (2, 'goodbye world')");
+      await db.exec("PRAGMA create_fts_index('docs2', 'id', 'content')");
+
+      const rows = await db.query<{ id: number; score: number | null }>(`
+        SELECT id, score FROM (
+          SELECT *, fts_main_docs2.match_bm25(id, 'nonexistent') AS score FROM docs2
+        ) sq WHERE score IS NOT NULL
+      `);
+      expect(rows).toHaveLength(0);
+    });
+
+    it("searches across multiple text columns", async () => {
+      db = await newNodeDuckDb();
+      await db.exec("INSTALL fts");
+      await db.exec("LOAD fts");
+      await db.exec("CREATE TABLE articles (id INTEGER, title VARCHAR, body VARCHAR)");
+      await db.exec(`
+        INSERT INTO articles 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')
+      `);
+      await db.exec("PRAGMA create_fts_index('articles', 'id', 'title', 'body')");
+
+      const rows = await db.query<{ id: number; score: number | null }>(`
+        SELECT id, score FROM (
+          SELECT *, fts_main_articles.match_bm25(id, 'lake') AS score FROM articles
+        ) sq WHERE score IS NOT NULL
+      `);
+      expect(rows.length).toBe(2);
+      const ids = rows.map((r) => r.id);
+      expect(ids).toContain(1);
+      expect(ids).toContain(2);
+    });
+
+    it("creates an FTS index and performs full-text search", async () => {
+      db = await newNodeDuckDb();
+
+      await db.exec("INSTALL fts");
+      await db.exec("LOAD fts");
+
+      await db.exec("CREATE TABLE docs (id INTEGER, content VARCHAR)");
+      await db.exec(`
+        INSERT INTO docs 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')
+      `);
+
+      await db.exec("PRAGMA create_fts_index('docs', 'id', 'content')");
+
+      const rows = await db.query<{
+        id: number;
+        content: string;
+        score: number | null;
+      }>(`
+        SELECT id, content, score
+        FROM (
+          SELECT *, fts_main_docs.match_bm25(id, 'fox') AS score
+          FROM docs
+        ) sq
+        WHERE score IS NOT NULL
+        ORDER BY score
+      `);
+
+      expect(rows.length).toBeGreaterThanOrEqual(1);
+      const ids = rows.map((r) => r.id);
+      expect(ids).toContain(1);
+      expect(ids).toContain(3);
+    });
+  });
+
+  describe("VSS extension", () => {
+    it("creates HNSW index and performs vector similarity search", async () => {
+      db = await newNodeDuckDb();
+
+      await db.exec("INSTALL vss");
+      await db.exec("LOAD vss");
+
+      await db.exec("CREATE TABLE embeddings (id INTEGER, vec FLOAT[3])");
+      await db.exec(`
+        INSERT INTO embeddings VALUES
+          (1, [1.0, 0.0, 0.0]),
+          (2, [0.0, 1.0, 0.0]),
+          (3, [0.0, 0.0, 1.0])
+      `);
+
+      await db.exec("CREATE INDEX vec_idx ON embeddings USING HNSW (vec)");
+
+      const rows = await db.query<{ id: number }>(
+        "SELECT id FROM embeddings ORDER BY array_distance(vec, [1.0, 0.1, 0.0]::FLOAT[3]) LIMIT 1",
+      );
+
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.id).toBe(1);
+    });
+
+    it("returns k nearest neighbors ordered by distance", async () => {
+      db = await newNodeDuckDb();
+      await db.exec("INSTALL vss");
+      await db.exec("LOAD vss");
+
+      await db.exec("CREATE TABLE vectors (id INTEGER, vec FLOAT[3])");
+      await db.exec(`
+        INSERT INTO vectors VALUES
+          (1, [1.0, 0.0, 0.0]),
+          (2, [0.9, 0.1, 0.0]),
+          (3, [0.0, 1.0, 0.0]),
+          (4, [0.0, 0.0, 1.0])
+      `);
+      await db.exec("CREATE INDEX vec_idx2 ON vectors USING HNSW (vec)");
+
+      const rows = await db.query<{ id: number }>(
+        "SELECT id FROM vectors ORDER BY array_distance(vec, [1.0, 0.0, 0.0]::FLOAT[3]) LIMIT 2",
+      );
+
+      expect(rows).toHaveLength(2);
+      expect(rows[0]?.id).toBe(1);
+      expect(rows[1]?.id).toBe(2);
+    });
+
+    it("works without HNSW index (brute-force scan)", async () => {
+      db = await newNodeDuckDb();
+      await db.exec("INSTALL vss");
+      await db.exec("LOAD vss");
+
+      await db.exec("CREATE TABLE vecs_no_idx (id INTEGER, vec FLOAT[3])");
+      await db.exec(`
+        INSERT INTO vecs_no_idx VALUES
+          (1, [1.0, 0.0, 0.0]),
+          (2, [0.0, 1.0, 0.0])
+      `);
+
+      const rows = await db.query<{ id: number }>(
+        "SELECT id FROM vecs_no_idx ORDER BY array_distance(vec, [0.0, 0.9, 0.1]::FLOAT[3]) LIMIT 1",
+      );
+
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.id).toBe(2);
+    });
+  });
+});

package/src/node-duckdb.ts

@@ -0,0 +1,35 @@
+import type { DuckDBValue } from "@duckdb/node-api";
+import { DuckDBInstance } from "@duckdb/node-api";
+import type { Db, DbEntry, DbOptions } from "@statewalker/db-api";
+
+/**
+ * Create a DuckDB-backed {@link Db} using native Node.js bindings.
+ *
+ * @param options.path  File path for persistent storage. Omit for in-memory.
+ */
+export async function newNodeDuckDb(options?: DbOptions): Promise<Db> {
+  const instance = await DuckDBInstance.create(options?.path ?? ":memory:");
+  const connection = await instance.connect();
+
+  return {
+    async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {
+      if (params && params.length > 0) {
+        const prepared = await connection.prepare(sql);
+        prepared.bind(params as DuckDBValue[]);
+        const reader = await prepared.runAndReadAll();
+        return reader.getRowObjectsJS() as T[];
+      }
+      const reader = await connection.runAndReadAll(sql);
+      return reader.getRowObjectsJS() as T[];
+    },
+
+    async exec(sql: string): Promise<void> {
+      await connection.run(sql);
+    },
+
+    async close(): Promise<void> {
+      connection.closeSync();
+      instance.closeSync();
+    },
+  };
+}