@cutils/sqlite 0.1.0 → 0.2.0

package/README.md

@@ -112,11 +112,27 @@ no perf claims until the bench cell lands):
 ## Node usage
 
 The npm package ships `dist/esm`. Under Node the emitted `shim_*` calls resolve
-on `globalThis` — `test/koffi-binding.mjs` shows loading
-`build/libcutils_sqlite.so` through [koffi](https://koffi.dev) (built by
-`pnpm build:shared`; the `.so` is linked `-Wl,-Bsymbolic` so the vendored
-amalgamation's `sqlite3_*` symbols can't interpose against a host's sqlite —
-this is load-bearing, Node ≥ 22 exports its own sqlite3 symbols).
+on `globalThis` — an official [koffi](https://koffi.dev) binding loads
+`build/libcutils_sqlite.so` for you:
+
+```sh
+# one-time, inside the installed package (needs a C toolchain):
+npm run build:shared --prefix node_modules/@cutils/sqlite
+```
+
+```ts
+import "koffi"; // ensure the optional peer is installed
+import "@cutils/sqlite/node-binding"; // installs the shim_* globals
+import { Database } from "@cutils/sqlite";
+```
+
+`koffi` is an **optional peer dependency** — install it when you run under
+Node; scriptc builds never see it. The `.so` is linked `-Wl,-Bsymbolic` so the
+vendored amalgamation's `sqlite3_*` symbols can't interpose against a host's
+sqlite — this is load-bearing, Node ≥ 22 exports its own sqlite3 symbols.
+
+Node ≥ 22 is the runtime floor; the test suite also runs there (no
+`using`-syntax — dispose paths are exercised via `[Symbol.dispose]()`).
 
 ## Subset quirks
 

package/dist/esm/node-binding.mjs

@@ -0,0 +1,120 @@
+// Installs the `shim_*` globals the emitted dist/esm/internal/ffi.js calls,
+// backed by the shared build (build/libcutils_sqlite.so) through koffi.
+// The scriptc span ABI means string/bytes params cross as (ptr,len) pairs —
+// koffi can't produce that layout from a JS string, so each binding is
+// wrapped in a JS adapter that encodes the span explicitly. Handles cross
+// as uint64 bigints (pointer-sized on x86_64/aarch64).
+
+import koffi from "koffi";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const dir = path.dirname(fileURLToPath(import.meta.url));
+const lib = koffi.load(path.join(dir, "..", "..", "build", "libcutils_sqlite.so"));
+
+const g = globalThis;
+const enc = new TextEncoder();
+
+const f = {
+  open: lib.func("uint64 shim_open(const uint8_t *path, uint64 plen, int32 flags)"),
+  close: lib.func("int32 shim_close(uint64 db)"),
+  errcode: lib.func("int32 shim_errcode(uint64 db)"),
+  errmsg: lib.func("int32 shim_errmsg(uint64 db, uint8_t *buf, uint64 len)"),
+  inTransaction: lib.func("int32 shim_in_transaction(uint64 db)"),
+  exec: lib.func("int32 shim_exec(uint64 db, const uint8_t *sql, uint64 slen)"),
+  begin: lib.func("int32 shim_begin(uint64 db)"),
+  commit: lib.func("int32 shim_commit(uint64 db)"),
+  rollback: lib.func("int32 shim_rollback(uint64 db)"),
+  savepoint: lib.func(
+    "int32 shim_savepoint(uint64 db, const uint8_t *name, uint64 nlen, int32 op)",
+  ),
+  prepare: lib.func("uint64 shim_prepare(uint64 db, const uint8_t *sql, uint64 slen)"),
+  step: lib.func("int32 shim_step(uint64 stmt)"),
+  reset: lib.func("int32 shim_reset(uint64 stmt)"),
+  finalize: lib.func("int32 shim_finalize(uint64 stmt)"),
+  clearBindings: lib.func("int32 shim_clear_bindings(uint64 stmt)"),
+  stmtReadonly: lib.func("int32 shim_stmt_readonly(uint64 stmt)"),
+  expandedSql: lib.func("int32 shim_expanded_sql(uint64 stmt, uint8_t *buf, uint64 len)"),
+  bindCount: lib.func("int32 shim_bind_count(uint64 stmt)"),
+  bindIndex: lib.func("int32 shim_bind_index(uint64 stmt, const uint8_t *name, uint64 nlen)"),
+  bindInt: lib.func("int32 shim_bind_int(uint64 stmt, int32 idx, int64 val)"),
+  bindDbl: lib.func("int32 shim_bind_dbl(uint64 stmt, int32 idx, double val)"),
+  bindText: lib.func(
+    "int32 shim_bind_text(uint64 stmt, int32 idx, const uint8_t *val, uint64 vlen)",
+  ),
+  bindBlob: lib.func(
+    "int32 shim_bind_blob(uint64 stmt, int32 idx, const uint8_t *val, uint64 vlen)",
+  ),
+  bindNull: lib.func("int32 shim_bind_null(uint64 stmt, int32 idx)"),
+  columnCount: lib.func("int32 shim_column_count(uint64 stmt)"),
+  columnName: lib.func("int32 shim_column_name(uint64 stmt, int32 idx, uint8_t *buf, uint64 len)"),
+  columnMeta: lib.func(
+    "int32 shim_column_meta(uint64 stmt, int32 idx, int32 which, uint8_t *buf, uint64 len)",
+  ),
+  columnType: lib.func("int32 shim_column_type(uint64 stmt, int32 idx)"),
+  columnInt64: lib.func("int64 shim_column_int64(uint64 stmt, int32 idx)"),
+  columnDbl: lib.func("double shim_column_dbl(uint64 stmt, int32 idx)"),
+  columnText: lib.func("int32 shim_column_text(uint64 stmt, int32 idx, uint8_t *buf, uint64 len)"),
+  columnBlob: lib.func("int32 shim_column_blob(uint64 stmt, int32 idx, uint8_t *buf, uint64 len)"),
+  lastInsertRowid: lib.func("int64 shim_last_insert_rowid(uint64 db)"),
+  changes: lib.func("int32 shim_changes(uint64 db)"),
+};
+
+function span(s) {
+  const b = enc.encode(s);
+  return [b, BigInt(b.length)];
+}
+
+g.shim_open = (path, flags) => {
+  const [b, n] = span(path);
+  return f.open(b, n, flags);
+};
+g.shim_close = (db) => f.close(db);
+g.shim_errcode = (db) => f.errcode(db);
+g.shim_errmsg = (db, buf) => f.errmsg(db, buf, BigInt(buf.length));
+g.shim_in_transaction = (db) => f.inTransaction(db);
+g.shim_exec = (db, sql) => {
+  const [b, n] = span(sql);
+  return f.exec(db, b, n);
+};
+g.shim_begin = (db) => f.begin(db);
+g.shim_commit = (db) => f.commit(db);
+g.shim_rollback = (db) => f.rollback(db);
+g.shim_savepoint = (db, name, op) => {
+  const [b, n] = span(name);
+  return f.savepoint(db, b, n, op);
+};
+g.shim_prepare = (db, sql) => {
+  const [b, n] = span(sql);
+  return f.prepare(db, b, n);
+};
+g.shim_step = (stmt) => f.step(stmt);
+g.shim_reset = (stmt) => f.reset(stmt);
+g.shim_finalize = (stmt) => f.finalize(stmt);
+g.shim_clear_bindings = (stmt) => f.clearBindings(stmt);
+g.shim_stmt_readonly = (stmt) => f.stmtReadonly(stmt);
+g.shim_expanded_sql = (stmt, buf) => f.expandedSql(stmt, buf, BigInt(buf.length));
+g.shim_bind_count = (stmt) => f.bindCount(stmt);
+g.shim_bind_index = (stmt, name) => {
+  const [b, n] = span(name);
+  return f.bindIndex(stmt, b, n);
+};
+g.shim_bind_int = (stmt, idx, val) => f.bindInt(stmt, idx, val);
+g.shim_bind_dbl = (stmt, idx, val) => f.bindDbl(stmt, idx, val);
+g.shim_bind_text = (stmt, idx, val) => {
+  const [b, n] = span(val);
+  return f.bindText(stmt, idx, b, n);
+};
+g.shim_bind_blob = (stmt, idx, val) => f.bindBlob(stmt, idx, val, BigInt(val.length));
+g.shim_bind_null = (stmt, idx) => f.bindNull(stmt, idx);
+g.shim_column_count = (stmt) => f.columnCount(stmt);
+g.shim_column_name = (stmt, idx, buf) => f.columnName(stmt, idx, buf, BigInt(buf.length));
+g.shim_column_meta = (stmt, idx, which, buf) =>
+  f.columnMeta(stmt, idx, which, buf, BigInt(buf.length));
+g.shim_column_type = (stmt, idx) => f.columnType(stmt, idx);
+g.shim_column_int64 = (stmt, idx) => f.columnInt64(stmt, idx);
+g.shim_column_dbl = (stmt, idx) => f.columnDbl(stmt, idx);
+g.shim_column_text = (stmt, idx, buf) => f.columnText(stmt, idx, buf, BigInt(buf.length));
+g.shim_column_blob = (stmt, idx, buf) => f.columnBlob(stmt, idx, buf, BigInt(buf.length));
+g.shim_last_insert_rowid = (db) => f.lastInsertRowid(db);
+g.shim_changes = (db) => f.changes(db);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cutils/sqlite",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Embedded SQLite for chttp/scriptc apps — vendored amalgamation, FFI shim, Standard-Schema row seam. Compiles to a single static ELF.",
   "license": "Apache-2.0",
   "repository": {
@@ -22,7 +22,8 @@
       "types": "./dist/esm/index.d.ts",
       "import": "./dist/esm/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./node-binding": "./dist/esm/node-binding.mjs"
   },
   "devDependencies": {
     "@chttp/val": "^0.2.1",
@@ -35,6 +36,14 @@
   "engines": {
     "node": ">=22"
   },
+  "peerDependencies": {
+    "koffi": "^2.14.1"
+  },
+  "peerDependenciesMeta": {
+    "koffi": {
+      "optional": true
+    }
+  },
   "author": "Joaquin Terrasa & contributors",
   "keywords": [
     "sqlite",
@@ -56,9 +65,9 @@
     "build:lib": "ranlib build/libsqlite3-shim.a",
     "build:shared": "cc -O2 -fPIC -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_LOAD_EXTENSION -DSQLITE_ENABLE_COLUMN_METADATA -Wl,-Bsymbolic -shared vendor/shim/sqlite_shim.c vendor/sqlite-amalgamation/sqlite3.c -o build/libcutils_sqlite.so",
     "build:ts": "tsc -p tsconfig.json",
-    "build": "mkdir -p build && npm run build:c && npm run build:sqlite && npm run build:archive && npm run build:lib && npm run build:ts",
+    "build": "mkdir -p build && npm run build:c && npm run build:sqlite && npm run build:archive && npm run build:lib && npm run build:ts && sed 's|\"\\.\\.\", \"build\"|\"..\", \"..\", \"build\"|' test/koffi-binding.mjs > dist/esm/node-binding.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && npm run build:shared && npm run test:c && npm run test:node",
+    "test": "npm run build && npm run build:shared && npm run test:c && npm run test:node && bash test/elf.test.sh",
     "test:c": "cc -O2 -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_LOAD_EXTENSION -DSQLITE_ENABLE_COLUMN_METADATA test/shim.test.c build/libsqlite3-shim.a -o build/shim_test -lm && ./build/shim_test",
     "test:node": "node --test test/*.test.js test/*.test.mjs"
   }

package/vendor/shim/sqlite_shim.c

@@ -235,9 +235,14 @@ int32_t shim_bind_dbl(void *stmt, int32_t idx, double val) {
 }
 
 /* The text span is length-delimited; SQLITE_TRANSIENT copies the bytes
- * inside the call — required because the borrow is call-scoped. */
+ * inside the call — required because the borrow is call-scoped.
+ * An EMPTY span may arrive as a NULL pointer (koffi marshals an empty
+ * Uint8Array as NULL; the ELF span for "" can also carry address 0) and
+ * sqlite3_bind_text(NULL, n) binds SQL NULL — substitute a non-NULL
+ * literal so '' stays ''. */
 int32_t shim_bind_text(void *stmt, int32_t idx, const uint8_t *val,
                        size_t vlen) {
+  if (val == NULL) val = (const uint8_t *)"";
   return (int32_t)sqlite3_bind_text((sqlite3_stmt *)stmt, (int)idx,
                                     (const char *)val, (int)vlen,
                                     SQLITE_TRANSIENT);
@@ -245,6 +250,8 @@ int32_t shim_bind_text(void *stmt, int32_t idx, const uint8_t *val,
 
 int32_t shim_bind_blob(void *stmt, int32_t idx, const uint8_t *val,
                        size_t vlen) {
+  /* Same empty-span NULL trap as shim_bind_text. */
+  if (val == NULL) val = (const uint8_t *)"";
   return (int32_t)sqlite3_bind_blob((sqlite3_stmt *)stmt, (int)idx, val,
                                     (int)vlen, SQLITE_TRANSIENT);
 }