@cutils/sqlite 0.0.0-stage → 0.2.0

package/dist/esm/internal/buffer.d.ts

@@ -0,0 +1,8 @@
+export declare class Scratch {
+    buf: Uint8Array;
+    constructor();
+    /** Grow until `cap` bytes fit. */
+    ensure(cap: number): void;
+    /** Copy the first `n` bytes out (for blob returns — scratch is reused). */
+    copyOut(n: number): Uint8Array;
+}

package/dist/esm/internal/buffer.js

@@ -0,0 +1,27 @@
+// Reusable scratch buffer for the shim's mutable-bytes out params.
+// Strings/blobs arrive as "required bytes" return values; when the buffer is
+// too small it doubles until the call fits.
+export class Scratch {
+    buf;
+    constructor() {
+        this.buf = new Uint8Array(4096);
+    }
+    /** Grow until `cap` bytes fit. */
+    ensure(cap) {
+        let n = this.buf.length;
+        while (n < cap) {
+            n = n * 2;
+        }
+        if (n !== this.buf.length) {
+            this.buf = new Uint8Array(n);
+        }
+    }
+    /** Copy the first `n` bytes out (for blob returns — scratch is reused). */
+    copyOut(n) {
+        const out = new Uint8Array(n);
+        for (let i = 0; i < n; i++) {
+            out[i] = this.buf[i];
+        }
+        return out;
+    }
+}

package/dist/esm/internal/ffi.d.ts

@@ -0,0 +1,34 @@
+export declare function ffiOpen(path: string, flags: number): bigint;
+export declare function ffiClose(db: bigint): number;
+export declare function ffiErrcode(db: bigint): number;
+export declare function ffiErrmsg(db: bigint, buf: Uint8Array): number;
+export declare function ffiInTransaction(db: bigint): number;
+export declare function ffiExec(db: bigint, sql: string): number;
+export declare function ffiBegin(db: bigint): number;
+export declare function ffiCommit(db: bigint): number;
+export declare function ffiRollback(db: bigint): number;
+export declare function ffiSavepoint(db: bigint, name: string, op: number): number;
+export declare function ffiPrepare(db: bigint, sql: string): bigint;
+export declare function ffiStep(stmt: bigint): number;
+export declare function ffiReset(stmt: bigint): number;
+export declare function ffiFinalize(stmt: bigint): number;
+export declare function ffiClearBindings(stmt: bigint): number;
+export declare function ffiStmtReadonly(stmt: bigint): number;
+export declare function ffiExpandedSql(stmt: bigint, buf: Uint8Array): number;
+export declare function ffiBindCount(stmt: bigint): number;
+export declare function ffiBindIndex(stmt: bigint, name: string): number;
+export declare function ffiBindInt(stmt: bigint, idx: number, val: bigint): number;
+export declare function ffiBindDbl(stmt: bigint, idx: number, val: number): number;
+export declare function ffiBindText(stmt: bigint, idx: number, val: string): number;
+export declare function ffiBindBlob(stmt: bigint, idx: number, val: Uint8Array): number;
+export declare function ffiBindNull(stmt: bigint, idx: number): number;
+export declare function ffiColumnCount(stmt: bigint): number;
+export declare function ffiColumnName(stmt: bigint, idx: number, buf: Uint8Array): number;
+export declare function ffiColumnMeta(stmt: bigint, idx: number, which: number, buf: Uint8Array): number;
+export declare function ffiColumnType(stmt: bigint, idx: number): number;
+export declare function ffiColumnInt64(stmt: bigint, idx: number): bigint;
+export declare function ffiColumnDbl(stmt: bigint, idx: number): number;
+export declare function ffiColumnText(stmt: bigint, idx: number, buf: Uint8Array): number;
+export declare function ffiColumnBlob(stmt: bigint, idx: number, buf: Uint8Array): number;
+export declare function ffiLastInsertRowid(db: bigint): bigint;
+export declare function ffiChanges(db: bigint): number;

package/dist/esm/internal/ffi.js

@@ -0,0 +1,110 @@
+// declare-function bindings for vendor/shim/sqlite_shim.c.
+// These must match vendor/manifest.json exactly (names, arity, types).
+// Span ABI: `string` params marshal as (ptr,len) — the declares pass only
+// the JS string; `mutable-bytes` out params marshal as (buf,len) — the
+// declares pass only the Uint8Array. Thin exported wrappers re-expose the
+// bindings: ambient declarations cannot be exported. Under plain Node the
+// emitted calls resolve on globalThis — test/koffi-binding.mjs installs
+// matching globals loaded through koffi.
+export function ffiOpen(path, flags) {
+    return shim_open(path, flags);
+}
+export function ffiClose(db) {
+    return shim_close(db);
+}
+export function ffiErrcode(db) {
+    return shim_errcode(db);
+}
+export function ffiErrmsg(db, buf) {
+    return shim_errmsg(db, buf);
+}
+export function ffiInTransaction(db) {
+    return shim_in_transaction(db);
+}
+export function ffiExec(db, sql) {
+    return shim_exec(db, sql);
+}
+export function ffiBegin(db) {
+    return shim_begin(db);
+}
+export function ffiCommit(db) {
+    return shim_commit(db);
+}
+export function ffiRollback(db) {
+    return shim_rollback(db);
+}
+export function ffiSavepoint(db, name, op) {
+    return shim_savepoint(db, name, op);
+}
+export function ffiPrepare(db, sql) {
+    return shim_prepare(db, sql);
+}
+export function ffiStep(stmt) {
+    return shim_step(stmt);
+}
+export function ffiReset(stmt) {
+    return shim_reset(stmt);
+}
+export function ffiFinalize(stmt) {
+    return shim_finalize(stmt);
+}
+export function ffiClearBindings(stmt) {
+    return shim_clear_bindings(stmt);
+}
+export function ffiStmtReadonly(stmt) {
+    return shim_stmt_readonly(stmt);
+}
+export function ffiExpandedSql(stmt, buf) {
+    return shim_expanded_sql(stmt, buf);
+}
+export function ffiBindCount(stmt) {
+    return shim_bind_count(stmt);
+}
+export function ffiBindIndex(stmt, name) {
+    return shim_bind_index(stmt, name);
+}
+export function ffiBindInt(stmt, idx, val) {
+    return shim_bind_int(stmt, idx, val);
+}
+export function ffiBindDbl(stmt, idx, val) {
+    return shim_bind_dbl(stmt, idx, val);
+}
+export function ffiBindText(stmt, idx, val) {
+    return shim_bind_text(stmt, idx, val);
+}
+export function ffiBindBlob(stmt, idx, val) {
+    return shim_bind_blob(stmt, idx, val);
+}
+export function ffiBindNull(stmt, idx) {
+    return shim_bind_null(stmt, idx);
+}
+export function ffiColumnCount(stmt) {
+    return shim_column_count(stmt);
+}
+export function ffiColumnName(stmt, idx, buf) {
+    return shim_column_name(stmt, idx, buf);
+}
+export function ffiColumnMeta(stmt, idx, which, buf) {
+    return shim_column_meta(stmt, idx, which, buf);
+}
+export function ffiColumnType(stmt, idx) {
+    return shim_column_type(stmt, idx);
+}
+export function ffiColumnInt64(stmt, idx) {
+    return shim_column_int64(stmt, idx);
+}
+export function ffiColumnDbl(stmt, idx) {
+    return shim_column_dbl(stmt, idx);
+}
+export function ffiColumnText(stmt, idx, buf) {
+    return shim_column_text(stmt, idx, buf);
+}
+export function ffiColumnBlob(stmt, idx, buf) {
+    return shim_column_blob(stmt, idx, buf);
+}
+export function ffiLastInsertRowid(db) {
+    return shim_last_insert_rowid(db);
+}
+export function ffiChanges(db) {
+    return shim_changes(db);
+}

package/dist/esm/internal/savepoint.d.ts

@@ -0,0 +1 @@
+export declare function nextSavepoint(): string;

package/dist/esm/internal/savepoint.js

@@ -0,0 +1,7 @@
+// Savepoint name generation for nested transactions.
+// Names must satisfy the shim's identifier whitelist [A-Za-z0-9_].
+let counter = 0;
+export function nextSavepoint() {
+    counter += 1;
+    return "sp_" + String(counter);
+}

package/dist/esm/internal/utf8.d.ts

@@ -0,0 +1,3 @@
+export declare function utf8Encode(s: string): Uint8Array;
+/** Decode the first `n` bytes of `buf` as UTF-8. */
+export declare function utf8Decode(buf: Uint8Array, n: number): string;

package/dist/esm/internal/utf8.js

@@ -0,0 +1,10 @@
+// string <-> UTF-8 helpers over TextEncoder/TextDecoder (subset-clean).
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export function utf8Encode(s) {
+    return encoder.encode(s);
+}
+/** Decode the first `n` bytes of `buf` as UTF-8. */
+export function utf8Decode(buf, n) {
+    return decoder.decode(buf.slice(0, n));
+}

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/dist/esm/types.d.ts

@@ -0,0 +1,66 @@
+/** Standard Typed `types` member shape (valibot-style). */
+export interface StdTypes<Input, Output> {
+    input: Input;
+    output: Output;
+}
+/**
+ * Standard Schema `~standard` props — a CLASS, not an interface:
+ * interface-typed class fields erase to `unknown` under scriptc (SC1090),
+ * so the seam shape is declared as classes (the same trick `@chttp/val`
+ * uses). Structurally every conforming validator still satisfies it:
+ * `version` is `number` (not literal `1`, so `@chttp/val`'s
+ * `version: number` field assigns) and `validate` returns `unknown` so
+ * both sync results and spec-conformant `Result | Promise<Result>`
+ * signatures are compatible. Async validators are rejected at call time.
+ */
+export declare class StdProps {
+    version: number;
+    vendor: string;
+    validate(input: unknown): unknown;
+}
+/** Standard Schema v1 shape (local mirror of the spec). */
+export declare class StandardSchemaV1 {
+    "~standard": StdProps;
+}
+/**
+ * Row output inference: reads the optional `types` member when the schema
+ * carries it (valibot and other spec-complete validators), else `unknown`
+ * (`@chttp/val` today — its coarse inference is a val-side ticket).
+ */
+export type InferOutput<S extends StandardSchemaV1> = S extends {
+    "~standard": {
+        types: {
+            output: infer O;
+        };
+    };
+} ? O : unknown;
+/** A value SQLite can store / return. */
+export type SqlValue = number | bigint | string | null | Uint8Array;
+/** A bindable value; booleans bind as INTEGER 0/1. */
+export type BindValue = SqlValue | boolean;
+/** A row as returned by `get`/`all` before schema validation. */
+export type Row = Record<string, SqlValue>;
+/** Write-side parameters for named binds (`@x`, `:x`, `$x`). */
+export type BindRecord = Record<string, BindValue>;
+export interface RunResult {
+    changes: number;
+    lastInsertRowid: number;
+}
+export interface OpenOpts {
+    /** Open read-only (fails if the file does not exist). */
+    readonly?: boolean;
+    /** Fail instead of creating the file when it does not exist. */
+    fileMustExist?: boolean;
+}
+export interface ColumnInfo {
+    /** Column name as the statement returns it. */
+    name: string;
+    /** Origin column name, or null for expressions / metadata off. */
+    column: string | null;
+    /** Origin table name. */
+    table: string | null;
+    /** Origin database name ("main", "temp", or an ATTACH alias). */
+    database: string | null;
+    /** Declared column type from the DDL, or null for expressions. */
+    type: string | null;
+}

package/dist/esm/types.js

@@ -0,0 +1,29 @@
+// Public value/row types and the Standard Schema v1 seam types.
+//
+// The Standard Schema types are a LOCAL MIRROR of `@standard-schema/spec`,
+// not an import: scriptc 0.3.3 refuses to analyze the spec package's shipped
+// JS even for a type-only import, so the package owns a structural copy of
+// the spec surface (props + validate signature + InferOutput inference).
+// Structurally every conforming validator satisfies it — `@chttp/val` schemas,
+// valibot schemas, anything with `~standard.validate`.
+/**
+ * Standard Schema `~standard` props — a CLASS, not an interface:
+ * interface-typed class fields erase to `unknown` under scriptc (SC1090),
+ * so the seam shape is declared as classes (the same trick `@chttp/val`
+ * uses). Structurally every conforming validator still satisfies it:
+ * `version` is `number` (not literal `1`, so `@chttp/val`'s
+ * `version: number` field assigns) and `validate` returns `unknown` so
+ * both sync results and spec-conformant `Result | Promise<Result>`
+ * signatures are compatible. Async validators are rejected at call time.
+ */
+export class StdProps {
+    version = 0;
+    vendor = "";
+    validate(input) {
+        return { value: input, issues: null };
+    }
+}
+/** Standard Schema v1 shape (local mirror of the spec). */
+export class StandardSchemaV1 {
+    "~standard" = new StdProps();
+}

package/dist/esm/validate.d.ts

@@ -0,0 +1,7 @@
+import { StandardSchemaV1 } from "./types.ts";
+/**
+ * Run `schema["~standard"].validate(value)` synchronously. Returns the
+ * validator's (possibly transformed) output. Throws `SqliteError` with
+ * `code: "VALIDATION"` on failure.
+ */
+export declare function validateRow(schema: StandardSchemaV1, value: unknown): unknown;

package/dist/esm/validate.js

@@ -0,0 +1,44 @@
+// Standard-Schema seam: `schema["~standard"].validate(row)` with structural
+// result handling — val returns `{ value, issues: null }`, spec-conformant
+// validators return `{ value }` (issues member absent) or `{ issues }`.
+// A Promise result (async validator) is rejected: this FFI surface is sync.
+import { SqliteError } from "./errors.js";
+function summarizeIssues(issues) {
+    if (typeof issues !== "object" || issues === null) {
+        return "schema validation failed";
+    }
+    const list = issues;
+    const first = list[0];
+    if (typeof first !== "object" || first === null) {
+        return "schema validation failed";
+    }
+    let msg = first.message;
+    if (typeof msg !== "string" || msg.length === 0) {
+        msg = "schema validation failed";
+    }
+    if (list.length > 1) {
+        return msg + " (+" + String(list.length - 1) + " more issues)";
+    }
+    return msg;
+}
+/**
+ * Run `schema["~standard"].validate(value)` synchronously. Returns the
+ * validator's (possibly transformed) output. Throws `SqliteError` with
+ * `code: "VALIDATION"` on failure.
+ */
+export function validateRow(schema, value) {
+    const res = schema["~standard"].validate(value);
+    if (typeof res !== "object" || res === null) {
+        throw new SqliteError("VALIDATION", "validator returned a non-standard result");
+    }
+    // Promise results (async validators) land here: no `value`/`issues`
+    // members, so both checks below fail into the non-standard throw.
+    const iss = res.issues;
+    if (iss !== null && typeof iss !== "undefined") {
+        throw new SqliteError("VALIDATION", summarizeIssues(iss));
+    }
+    if (typeof res.value === "undefined") {
+        throw new SqliteError("VALIDATION", "validator returned a non-standard result (async validators are not supported)");
+    }
+    return res.value;
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@cutils/sqlite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/sigilco/cutils.git",
+    "directory": "packages/sqlite"
+  },
+  "files": [
+    "dist",
+    "src",
+    "vendor",
+    "build/libsqlite3-shim.a"
+  ],
+  "type": "module",
+  "main": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json",
+    "./node-binding": "./dist/esm/node-binding.mjs"
+  },
+  "devDependencies": {
+    "@chttp/val": "^0.2.1",
+    "@standard-schema/spec": "^1.1.0",
+    "@types/node": "^24.0.0",
+    "koffi": "^2.14.1",
+    "typescript": "^5.9.0",
+    "valibot": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "koffi": "^2.14.1"
+  },
+  "peerDependenciesMeta": {
+    "koffi": {
+      "optional": true
+    }
+  },
+  "author": "Joaquin Terrasa & contributors",
+  "keywords": [
+    "sqlite",
+    "database",
+    "standard-schema",
+    "scriptc",
+    "native",
+    "elf"
+  ],
+  "homepage": "https://github.com/sigilco/cutils/tree/main/packages/sqlite#readme",
+  "bugs": {
+    "url": "https://github.com/sigilco/cutils/issues"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build:c": "cc -O2 -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_LOAD_EXTENSION -DSQLITE_ENABLE_COLUMN_METADATA -c vendor/shim/sqlite_shim.c -o build/sqlite_shim.o",
+    "build:sqlite": "cc -O2 -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_LOAD_EXTENSION -DSQLITE_ENABLE_COLUMN_METADATA -c vendor/sqlite-amalgamation/sqlite3.c -o build/sqlite3.o",
+    "build:archive": "ar rcs build/libsqlite3-shim.a build/sqlite_shim.o build/sqlite3.o",
+    "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 && 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 && 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/src/errors.ts

@@ -0,0 +1,108 @@
+// SqliteError + the numeric-result-code → name mapping.
+
+export class SqliteError extends Error {
+  code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "SqliteError";
+    this.code = code;
+  }
+}
+
+// Primary result codes (rc & 0xFF) plus the constraint extended codes —
+// the names better-sqlite3 users will recognize from `err.code`.
+export function sqliteCodeName(rc: number): string {
+  switch (rc) {
+    case 275:
+      return "SQLITE_CONSTRAINT_CHECK";
+    case 531:
+      return "SQLITE_CONSTRAINT_COMMITHOOK";
+    case 787:
+      return "SQLITE_CONSTRAINT_FOREIGNKEY";
+    case 803:
+      return "SQLITE_CONSTRAINT_FUNCTION";
+    case 1027:
+      return "SQLITE_CONSTRAINT_TRIGGER";
+    case 1043:
+      return "SQLITE_CONSTRAINT_VTAB";
+    case 1299:
+      return "SQLITE_CONSTRAINT_NOTNULL";
+    case 1555:
+      return "SQLITE_CONSTRAINT_PRIMARYKEY";
+    case 2067:
+      return "SQLITE_CONSTRAINT_UNIQUE";
+    case 2579:
+      return "SQLITE_CONSTRAINT_ROWID";
+    case 2835:
+      return "SQLITE_CONSTRAINT_PINNED";
+    case 3091:
+      return "SQLITE_CONSTRAINT_DATATYPE";
+    default:
+      break;
+  }
+  const primary = rc & 255;
+  switch (primary) {
+    case 1:
+      return "SQLITE_ERROR";
+    case 2:
+      return "SQLITE_INTERNAL";
+    case 3:
+      return "SQLITE_PERM";
+    case 4:
+      return "SQLITE_ABORT";
+    case 5:
+      return "SQLITE_BUSY";
+    case 6:
+      return "SQLITE_LOCKED";
+    case 7:
+      return "SQLITE_NOMEM";
+    case 8:
+      return "SQLITE_READONLY";
+    case 9:
+      return "SQLITE_INTERRUPT";
+    case 10:
+      return "SQLITE_IOERR";
+    case 11:
+      return "SQLITE_CORRUPT";
+    case 12:
+      return "SQLITE_NOTFOUND";
+    case 13:
+      return "SQLITE_FULL";
+    case 14:
+      return "SQLITE_CANTOPEN";
+    case 15:
+      return "SQLITE_PROTOCOL";
+    case 16:
+      return "SQLITE_EMPTY";
+    case 17:
+      return "SQLITE_SCHEMA";
+    case 18:
+      return "SQLITE_TOOBIG";
+    case 19:
+      return "SQLITE_CONSTRAINT";
+    case 20:
+      return "SQLITE_MISMATCH";
+    case 21:
+      return "SQLITE_MISUSE";
+    case 22:
+      return "SQLITE_NOLFS";
+    case 23:
+      return "SQLITE_AUTH";
+    case 24:
+      return "SQLITE_FORMAT";
+    case 25:
+      return "SQLITE_RANGE";
+    case 26:
+      return "SQLITE_NOTADB";
+    case 27:
+      return "SQLITE_NOTICE";
+    case 28:
+      return "SQLITE_WARNING";
+    case 100:
+      return "SQLITE_ROW";
+    case 101:
+      return "SQLITE_DONE";
+    default:
+      return "SQLITE_ERROR";
+  }
+}