@statewalker/db-duckdb-node 0.1.2 → 0.1.3

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.
Files changed (2) hide show
  1. package/README.md +44 -11
  2. package/package.json +8 -4
package/README.md CHANGED
@@ -1,27 +1,60 @@
1
1
  # @statewalker/db-duckdb-node
2
2
 
3
- DuckDB Node.js driver implementing `@statewalker/db-api`, backed by `@duckdb/node-api`.
3
+ ## What it is
4
4
 
5
- ## Installation
5
+ A DuckDB driver for Node.js that implements `Db` from `@statewalker/db-api`.
6
+ It uses the native bindings from `@duckdb/node-api` and opens a DuckDB file or
7
+ an in-memory database.
8
+
9
+ ## Why it exists
10
+
11
+ It lets code written against `Db` run on DuckDB in Node.js: servers, CLIs,
12
+ build scripts and tests. The same code runs in the browser on
13
+ `@statewalker/db-duckdb-browser`.
14
+
15
+ ## How to use
6
16
 
7
17
  ```sh
8
18
  pnpm add @statewalker/db-duckdb-node
9
19
  ```
10
20
 
11
- ## Usage
21
+ `@duckdb/node-api` installs a prebuilt native binary for your platform.
22
+
23
+ | Import | Gives | Environment |
24
+ | --- | --- | --- |
25
+ | `@statewalker/db-duckdb-node` | `newNodeDuckDb`; types `Db`, `DbEntry`, `DbOptions` re-exported from `@statewalker/db-api` | Node.js |
26
+
27
+ `newNodeDuckDb(options?)` returns `Promise<Db>`. It opens `options.path`, or
28
+ `:memory:` without a path. The `Db` implements `query`, `exec` and `close`; it
29
+ has no `flush`.
30
+
31
+ ## Examples
12
32
 
13
33
  ```ts
14
- import { createDuckDbNodeClient } from "@statewalker/db-duckdb-node";
34
+ import { newNodeDuckDb } from "@statewalker/db-duckdb-node";
15
35
 
16
- const db = await createDuckDbNodeClient({ path: "./data.duckdb" });
17
- await db.execute("CREATE TABLE t (x INTEGER)");
36
+ const db = await newNodeDuckDb({ path: "./data.duckdb" });
37
+ await db.exec("CREATE TABLE IF NOT EXISTS t (x INTEGER)");
38
+ await db.exec("INSERT INTO t VALUES (1), (2)");
39
+ const rows = await db.query<{ x: number }>("SELECT x FROM t WHERE x > $1", [1]);
40
+ await db.close();
18
41
  ```
19
42
 
20
- ## API
43
+ ## Internals
21
44
 
22
- - `createDuckDbNodeClient(options)` — opens an on-disk or in-memory DuckDB file and returns a `DbClient`.
45
+ - **One instance, one connection.** The factory creates a `DuckDBInstance`
46
+ and a single connection; `close()` closes both synchronously.
47
+ - **Parameters.** With parameters, `query` prepares the statement, binds the
48
+ array and runs it. Both `$1` and `?` placeholders work.
49
+ - **Rows are plain JS objects** (`getRowObjectsJS()`). DuckDB `BIGINT` values,
50
+ including `count(*)`, come back as `bigint`, not `number`.
51
+ - **Errors are DuckDB's.** A bad path rejects with
52
+ `IO Error: Cannot open file "...": No such file or directory`. Bad SQL rejects
53
+ with `Parser Error: ...`. A call after `close()` rejects with
54
+ `Failed to query: connection disconnected`.
55
+ - **Dependencies:** `@duckdb/node-api` (the engine), `@statewalker/db-api`
56
+ (the interface types).
23
57
 
24
- ## Related
58
+ ## License
25
59
 
26
- - `@statewalker/db-api` — interface contract.
27
- - `@statewalker/db-duckdb-browser` — Browser-side counterpart.
60
+ MIT
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "@statewalker/db-duckdb-node",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "DuckDB Node.js driver for @statewalker/db-api using @duckdb/node-api.",
7
- "homepage": "https://github.com/statewalker/statewalker-db",
7
+ "bugs": {
8
+ "url": "https://github.com/statewalker/statewalker-db/issues"
9
+ },
10
+ "homepage": "https://github.com/statewalker/statewalker-db/tree/main/packages/db-duckdb-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-duckdb-node"
16
20
  },
17
21
  "exports": {
18
22
  ".": {
@@ -27,7 +31,7 @@
27
31
  ],
28
32
  "dependencies": {
29
33
  "@duckdb/node-api": "^1.5.5-r.4",
30
- "@statewalker/db-api": "^0.1.2"
34
+ "@statewalker/db-api": "^0.1.3"
31
35
  },
32
36
  "devDependencies": {
33
37
  "@types/node": "^26.6.4",