@cutils/sqlite 0.0.0-stage → 0.1.0

package/src/internal/buffer.ts

@@ -0,0 +1,31 @@
+// 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: Uint8Array;
+
+  constructor() {
+    this.buf = new Uint8Array(4096);
+  }
+
+  /** Grow until `cap` bytes fit. */
+  ensure(cap: number): void {
+    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: number): Uint8Array {
+    const out = new Uint8Array(n);
+    for (let i = 0; i < n; i++) {
+      out[i] = this.buf[i];
+    }
+    return out;
+  }
+}

package/src/internal/ffi.ts

@@ -0,0 +1,151 @@
+// 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.
+
+declare function shim_open(path: string, flags: number): bigint;
+declare function shim_close(db: bigint): number;
+declare function shim_errcode(db: bigint): number;
+declare function shim_errmsg(db: bigint, buf: Uint8Array): number;
+declare function shim_in_transaction(db: bigint): number;
+declare function shim_exec(db: bigint, sql: string): number;
+declare function shim_begin(db: bigint): number;
+declare function shim_commit(db: bigint): number;
+declare function shim_rollback(db: bigint): number;
+declare function shim_savepoint(db: bigint, name: string, op: number): number;
+declare function shim_prepare(db: bigint, sql: string): bigint;
+declare function shim_step(stmt: bigint): number;
+declare function shim_reset(stmt: bigint): number;
+declare function shim_finalize(stmt: bigint): number;
+declare function shim_clear_bindings(stmt: bigint): number;
+declare function shim_stmt_readonly(stmt: bigint): number;
+declare function shim_expanded_sql(stmt: bigint, buf: Uint8Array): number;
+declare function shim_bind_count(stmt: bigint): number;
+declare function shim_bind_index(stmt: bigint, name: string): number;
+declare function shim_bind_int(stmt: bigint, idx: number, val: bigint): number;
+declare function shim_bind_dbl(stmt: bigint, idx: number, val: number): number;
+declare function shim_bind_text(stmt: bigint, idx: number, val: string): number;
+declare function shim_bind_blob(stmt: bigint, idx: number, val: Uint8Array): number;
+declare function shim_bind_null(stmt: bigint, idx: number): number;
+declare function shim_column_count(stmt: bigint): number;
+declare function shim_column_name(stmt: bigint, idx: number, buf: Uint8Array): number;
+declare function shim_column_meta(
+  stmt: bigint,
+  idx: number,
+  which: number,
+  buf: Uint8Array,
+): number;
+declare function shim_column_type(stmt: bigint, idx: number): number;
+declare function shim_column_int64(stmt: bigint, idx: number): bigint;
+declare function shim_column_dbl(stmt: bigint, idx: number): number;
+declare function shim_column_text(stmt: bigint, idx: number, buf: Uint8Array): number;
+declare function shim_column_blob(stmt: bigint, idx: number, buf: Uint8Array): number;
+declare function shim_last_insert_rowid(db: bigint): bigint;
+declare function shim_changes(db: bigint): number;
+
+export function ffiOpen(path: string, flags: number): bigint {
+  return shim_open(path, flags);
+}
+export function ffiClose(db: bigint): number {
+  return shim_close(db);
+}
+export function ffiErrcode(db: bigint): number {
+  return shim_errcode(db);
+}
+export function ffiErrmsg(db: bigint, buf: Uint8Array): number {
+  return shim_errmsg(db, buf);
+}
+export function ffiInTransaction(db: bigint): number {
+  return shim_in_transaction(db);
+}
+export function ffiExec(db: bigint, sql: string): number {
+  return shim_exec(db, sql);
+}
+export function ffiBegin(db: bigint): number {
+  return shim_begin(db);
+}
+export function ffiCommit(db: bigint): number {
+  return shim_commit(db);
+}
+export function ffiRollback(db: bigint): number {
+  return shim_rollback(db);
+}
+export function ffiSavepoint(db: bigint, name: string, op: number): number {
+  return shim_savepoint(db, name, op);
+}
+export function ffiPrepare(db: bigint, sql: string): bigint {
+  return shim_prepare(db, sql);
+}
+export function ffiStep(stmt: bigint): number {
+  return shim_step(stmt);
+}
+export function ffiReset(stmt: bigint): number {
+  return shim_reset(stmt);
+}
+export function ffiFinalize(stmt: bigint): number {
+  return shim_finalize(stmt);
+}
+export function ffiClearBindings(stmt: bigint): number {
+  return shim_clear_bindings(stmt);
+}
+export function ffiStmtReadonly(stmt: bigint): number {
+  return shim_stmt_readonly(stmt);
+}
+export function ffiExpandedSql(stmt: bigint, buf: Uint8Array): number {
+  return shim_expanded_sql(stmt, buf);
+}
+export function ffiBindCount(stmt: bigint): number {
+  return shim_bind_count(stmt);
+}
+export function ffiBindIndex(stmt: bigint, name: string): number {
+  return shim_bind_index(stmt, name);
+}
+export function ffiBindInt(stmt: bigint, idx: number, val: bigint): number {
+  return shim_bind_int(stmt, idx, val);
+}
+export function ffiBindDbl(stmt: bigint, idx: number, val: number): number {
+  return shim_bind_dbl(stmt, idx, val);
+}
+export function ffiBindText(stmt: bigint, idx: number, val: string): number {
+  return shim_bind_text(stmt, idx, val);
+}
+export function ffiBindBlob(stmt: bigint, idx: number, val: Uint8Array): number {
+  return shim_bind_blob(stmt, idx, val);
+}
+export function ffiBindNull(stmt: bigint, idx: number): number {
+  return shim_bind_null(stmt, idx);
+}
+export function ffiColumnCount(stmt: bigint): number {
+  return shim_column_count(stmt);
+}
+export function ffiColumnName(stmt: bigint, idx: number, buf: Uint8Array): number {
+  return shim_column_name(stmt, idx, buf);
+}
+export function ffiColumnMeta(stmt: bigint, idx: number, which: number, buf: Uint8Array): number {
+  return shim_column_meta(stmt, idx, which, buf);
+}
+export function ffiColumnType(stmt: bigint, idx: number): number {
+  return shim_column_type(stmt, idx);
+}
+export function ffiColumnInt64(stmt: bigint, idx: number): bigint {
+  return shim_column_int64(stmt, idx);
+}
+export function ffiColumnDbl(stmt: bigint, idx: number): number {
+  return shim_column_dbl(stmt, idx);
+}
+export function ffiColumnText(stmt: bigint, idx: number, buf: Uint8Array): number {
+  return shim_column_text(stmt, idx, buf);
+}
+export function ffiColumnBlob(stmt: bigint, idx: number, buf: Uint8Array): number {
+  return shim_column_blob(stmt, idx, buf);
+}
+export function ffiLastInsertRowid(db: bigint): bigint {
+  return shim_last_insert_rowid(db);
+}
+export function ffiChanges(db: bigint): number {
+  return shim_changes(db);
+}

package/src/internal/savepoint.ts

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

package/src/internal/utf8.ts

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

package/src/types.ts

@@ -0,0 +1,83 @@
+// 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 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 class StdProps {
+  version: number = 0;
+  vendor: string = "";
+
+  validate(input: unknown): unknown {
+    return { value: input, issues: null };
+  }
+}
+
+/** Standard Schema v1 shape (local mirror of the spec). */
+export class StandardSchemaV1 {
+  "~standard": StdProps = new 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/src/validate.ts

@@ -0,0 +1,60 @@
+// 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.ts";
+import { StandardSchemaV1 } from "./types.ts";
+
+interface StdResultLite {
+  value: unknown;
+  issues: unknown;
+}
+
+interface StdIssueLite {
+  message: string;
+}
+
+function summarizeIssues(issues: unknown): string {
+  if (typeof issues !== "object" || issues === null) {
+    return "schema validation failed";
+  }
+  const list = issues as StdIssueLite[];
+  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: StandardSchemaV1, value: unknown): unknown {
+  const res = schema["~standard"].validate(value) as unknown as StdResultLite;
+  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/vendor/README.md

@@ -0,0 +1,48 @@
+# vendor/
+
+Vendored native dependencies for `@cutils/sqlite`. Everything under this
+directory is compiled into the consumer's binary by `scriptc build --ffi`;
+nothing here is a runtime dependency.
+
+## sqlite-amalgamation/
+
+The SQLite amalgamation (`sqlite3.c` + `sqlite3.h`), vendored unmodified from
+upstream. SQLite is dedicated to the public domain
+(<https://www.sqlite.org/copyright.html>), so redistribution inside this package
+needs no license attribution.
+
+- Version: **3.50.4** (see `SQLITE_VERSION`; `SQLITE_VERSION_NUMBER` 3500400)
+- Source: <https://www.sqlite.org/2025/sqlite-amalgamation-3500400.zip>
+- Downloaded: 2026-10-15
+
+SHA-256 checksums (verify with `sha256sum`):
+
+```
+e3f5d6901e7492af4a1fc8c4d745cae84c264942524c3fbfc02b82a5ca8818c8  sqlite3.c
+abd1514e0351f79393d1be882830afdb40a8099e8257f311f0bfdf8486f11bea  sqlite3.h
+```
+
+If these checksums ever differ, the files were modified or corrupted — do not
+ship them; re-vendor from upstream instead.
+
+Compiled with `-O2 -DSQLITE_THREADSAFE=0 -DSQLITE_OMIT_LOAD_EXTENSION
+-DSQLITE_ENABLE_COLUMN_METADATA`:
+
+- `SQLITE_THREADSAFE=0` — single-connection, single-threaded model; matches the
+  wrapper's `Database` (one handle per instance).
+- `SQLITE_OMIT_LOAD_EXTENSION` — no `load_extension`; removes attack surface.
+- `SQLITE_ENABLE_COLUMN_METADATA` — enables `sqlite3_column_table_name` /
+  `column_database_name` / `column_origin_name` for `Stmt.columns()`.
+
+## shim/
+
+`sqlite_shim.c` — the thin C shim (~300 LoC) that adapts the SQLite C API to
+scriptc's FFI ABI (fixed-width signatures, `mutable-bytes` out params). This is
+the only C code maintained in this package; the amalgamation is upstream,
+unmodified.
+
+## manifest.json
+
+The scriptc FFI manifest (`ffi_format: 7`) consumed by
+`scriptc build --ffi` and `scriptc coverage --ffi`. `libraries` points at the
+prebuilt archive `../build/libsqlite3-shim.a` produced by `pnpm build`.

package/vendor/manifest.json

@@ -0,0 +1,166 @@
+{
+  "ffi_format": 7,
+  "functions": [
+    {
+      "name": "shim_open",
+      "symbol": "shim_open",
+      "params": ["string", "i32"],
+      "returns": "pointer"
+    },
+    { "name": "shim_close", "symbol": "shim_close", "params": ["pointer"], "returns": "i32" },
+    { "name": "shim_errcode", "symbol": "shim_errcode", "params": ["pointer"], "returns": "i32" },
+    {
+      "name": "shim_errmsg",
+      "symbol": "shim_errmsg",
+      "params": ["pointer", "mutable-bytes"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_in_transaction",
+      "symbol": "shim_in_transaction",
+      "params": ["pointer"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_exec",
+      "symbol": "shim_exec",
+      "params": ["pointer", "string"],
+      "returns": "i32"
+    },
+    { "name": "shim_begin", "symbol": "shim_begin", "params": ["pointer"], "returns": "i32" },
+    { "name": "shim_commit", "symbol": "shim_commit", "params": ["pointer"], "returns": "i32" },
+    { "name": "shim_rollback", "symbol": "shim_rollback", "params": ["pointer"], "returns": "i32" },
+    {
+      "name": "shim_savepoint",
+      "symbol": "shim_savepoint",
+      "params": ["pointer", "string", "i32"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_prepare",
+      "symbol": "shim_prepare",
+      "params": ["pointer", "string"],
+      "returns": "pointer"
+    },
+    { "name": "shim_step", "symbol": "shim_step", "params": ["pointer"], "returns": "i32" },
+    { "name": "shim_reset", "symbol": "shim_reset", "params": ["pointer"], "returns": "i32" },
+    { "name": "shim_finalize", "symbol": "shim_finalize", "params": ["pointer"], "returns": "i32" },
+    {
+      "name": "shim_clear_bindings",
+      "symbol": "shim_clear_bindings",
+      "params": ["pointer"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_stmt_readonly",
+      "symbol": "shim_stmt_readonly",
+      "params": ["pointer"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_expanded_sql",
+      "symbol": "shim_expanded_sql",
+      "params": ["pointer", "mutable-bytes"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_bind_count",
+      "symbol": "shim_bind_count",
+      "params": ["pointer"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_bind_index",
+      "symbol": "shim_bind_index",
+      "params": ["pointer", "string"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_bind_int",
+      "symbol": "shim_bind_int",
+      "params": ["pointer", "i32", "i64"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_bind_dbl",
+      "symbol": "shim_bind_dbl",
+      "params": ["pointer", "i32", "f64"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_bind_text",
+      "symbol": "shim_bind_text",
+      "params": ["pointer", "i32", "string"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_bind_blob",
+      "symbol": "shim_bind_blob",
+      "params": ["pointer", "i32", "bytes"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_bind_null",
+      "symbol": "shim_bind_null",
+      "params": ["pointer", "i32"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_column_count",
+      "symbol": "shim_column_count",
+      "params": ["pointer"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_column_name",
+      "symbol": "shim_column_name",
+      "params": ["pointer", "i32", "mutable-bytes"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_column_meta",
+      "symbol": "shim_column_meta",
+      "params": ["pointer", "i32", "i32", "mutable-bytes"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_column_type",
+      "symbol": "shim_column_type",
+      "params": ["pointer", "i32"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_column_int64",
+      "symbol": "shim_column_int64",
+      "params": ["pointer", "i32"],
+      "returns": "i64"
+    },
+    {
+      "name": "shim_column_dbl",
+      "symbol": "shim_column_dbl",
+      "params": ["pointer", "i32"],
+      "returns": "f64"
+    },
+    {
+      "name": "shim_column_text",
+      "symbol": "shim_column_text",
+      "params": ["pointer", "i32", "mutable-bytes"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_column_blob",
+      "symbol": "shim_column_blob",
+      "params": ["pointer", "i32", "mutable-bytes"],
+      "returns": "i32"
+    },
+    {
+      "name": "shim_last_insert_rowid",
+      "symbol": "shim_last_insert_rowid",
+      "params": ["pointer"],
+      "returns": "i64"
+    },
+    { "name": "shim_changes", "symbol": "shim_changes", "params": ["pointer"], "returns": "i32" }
+  ],
+  "libraries": ["../build/libsqlite3-shim.a"],
+  "system_libraries": ["m"]
+}