@statewalker/db-sqlite-node 0.1.1 → 0.2.1

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,61 @@
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 libSQL/SQLite driver for Node.js that implements `Db` from
6
+ `@statewalker/db-api`. It uses `@libsql/client` with a local file or an
7
+ in-memory database. libSQL includes FTS5 full-text search and vector search
8
+ (`F32_BLOB`, `vector32`, `libsql_vector_idx`, `vector_top_k`).
9
+
10
+ ## Why it exists
11
+
12
+ It lets code written against `Db` run on SQLite in Node.js, with the same SQL
13
+ features that `@statewalker/db-sqlite-browser` has in the browser. Search and
14
+ storage code can be built and tested in Node.js and shipped to the browser
15
+ unchanged.
16
+
17
+ ## How to use
6
18
 
7
19
  ```sh
8
20
  pnpm add @statewalker/db-sqlite-node
9
21
  ```
10
22
 
11
- ## Usage
23
+ | Import | Gives | Environment |
24
+ | --- | --- | --- |
25
+ | `@statewalker/db-sqlite-node` | `newNodeSqliteDb`; types `Db`, `DbEntry`, `DbOptions` re-exported from `@statewalker/db-api` | Node.js |
26
+
27
+ `newNodeSqliteDb(options?)` returns `Promise<Db>`. It opens `file:<path>`, or
28
+ `:memory:` without a path. The `Db` implements `query`, `exec` and `close`; it
29
+ has no `flush`. Use `?` placeholders.
30
+
31
+ ## Examples
12
32
 
13
33
  ```ts
14
34
  import { newNodeSqliteDb } from "@statewalker/db-sqlite-node";
15
35
 
16
- // In-memory (omit `path`) or file-backed persistence.
17
36
  const db = await newNodeSqliteDb({ path: "./data.db" });
18
- await db.exec("CREATE TABLE t (x INTEGER)");
19
- await db.query("SELECT * FROM t");
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]);
40
+ await db.close();
20
41
  ```
21
42
 
22
- ## API
23
-
24
- - `newNodeSqliteDb(options?)` — opens a local file-backed (`options.path`) or in-memory libSQL database and returns a `Db`.
25
-
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.
29
-
30
- ## Related
31
-
32
- - `@statewalker/db-api` — interface contract.
33
- - `@statewalker/db-sqlite-browser` — Browser-side counterpart.
43
+ ## Internals
44
+
45
+ - **Local only.** The driver builds the client URL itself (`file:<path>` or
46
+ `:memory:`), so remote libSQL servers (`libsql://` URLs with an auth token)
47
+ cannot be reached through it.
48
+ - **Rows are libSQL `Row` objects.** Named columns are enumerable; positional
49
+ keys and `length` are also present but non-enumerable. `{ ...row }` and
50
+ `JSON.stringify(row)` give only the named columns, while `row.length` and
51
+ `row[0]` still work.
52
+ - **Errors are libSQL's.** A path that cannot be opened rejects with
53
+ `ConnectionFailed("Unable to open connection to local database ...: 14")`.
54
+ Bad SQL rejects with `SQLITE_ERROR: near "...": syntax error`. A call after
55
+ `close()` rejects with `CLIENT_CLOSED: The client is closed`.
56
+ - **Dependencies:** `@libsql/client` (the engine), `@statewalker/db-api` (the
57
+ interface types).
58
+
59
+ ## License
60
+
61
+ MIT
package/dist/index.d.mts CHANGED
@@ -5,7 +5,7 @@ import { Db, Db as Db$1, DbEntry, DbOptions, DbOptions as DbOptions$1 } from "@s
5
5
  *
6
6
  * @param options.path File path for persistent storage. Omit for in-memory.
7
7
  */
8
- declare function newNodeSqliteDb(options?: DbOptions$1): Promise<Db$1>;
8
+ export declare function newNodeSqliteDb(options?: DbOptions$1): Promise<Db$1>;
9
9
  //#endregion
10
- export { type Db, type DbEntry, type DbOptions, newNodeSqliteDb };
10
+ export type { Db, DbEntry, DbOptions };
11
11
  //# sourceMappingURL=index.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../src/node-sqlite-db.ts"],"mappings":";;;;;;;iBASsB,gBAAgB,UAAU,cAAY,QAAQ"}
1
+ {"version":3,"file":"index.d.mts","names":["DbOptions","Db"],"sources":["../src/node-sqlite-db.ts"],"mappings":";;;;;;;wBASsB,gBAAgB,UAAUA,cAAY,QAAQC"}
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "@statewalker/db-sqlite-node",
3
- "version": "0.1.1",
3
+ "version": "0.2.1",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "libSQL/SQLite client driver for @statewalker/db-api, targeting Node.js environments.",
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-sqlite-node#readme",
8
11
  "author": {
9
12
  "name": "Mikhail Kotelnikov",
10
13
  "email": "mikhail.kotelnikov@gmail.com"
@@ -12,26 +15,31 @@
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
- ".": "./src/index.ts"
22
+ ".": {
23
+ "source": "./src/index.ts",
24
+ "types": "./dist/index.d.mts",
25
+ "import": "./dist/index.mjs"
26
+ }
19
27
  },
20
28
  "files": [
21
29
  "dist",
22
30
  "src"
23
31
  ],
24
32
  "dependencies": {
25
- "@libsql/client": "^0.17.4",
26
- "@statewalker/db-api": "0.1.1"
33
+ "@libsql/client": "^0.18.0",
34
+ "@statewalker/db-api": "^0.1.3"
27
35
  },
28
36
  "devDependencies": {
29
- "@types/node": "^26.2.0",
37
+ "@types/node": "^26.6.4",
30
38
  "rimraf": "^6.1.3",
31
- "tsdown": "^0.22.14",
39
+ "tsdown": "^0.23.0",
32
40
  "typescript": "^7.0.2",
33
- "vitest": "^4.1.10",
34
- "@statewalker/db-tests": "0.1.1"
41
+ "vitest": "^5.0.3",
42
+ "@statewalker/db-tests": "^0.1.1"
35
43
  },
36
44
  "sideEffects": false,
37
45
  "publishConfig": {