quiverdb 0.5.0

package/README.md

@@ -0,0 +1,108 @@
+# quiverdb
+
+Bun-native SQLite wrapper binding for Quiver via bun:ffi.
+
+## Requirements
+
+- Bun >= 1.0.0
+- `libquiver.dll` and `libquiver_c.dll` in system PATH
+
+## Installation
+
+```bash
+bun add quiverdb
+```
+
+The native Quiver DLLs must be compiled separately and available in your system PATH. See the Quiver project build instructions for details.
+
+## DLL Setup
+
+This binding loads the Quiver C API library (`libquiver_c.dll`) at runtime via `bun:ffi`. The core library (`libquiver.dll`) is a dependency that must also be loadable.
+
+Options for making the DLLs available:
+
+1. Add the `build/bin/` directory to your system PATH
+2. Copy both DLLs to a directory already in PATH
+3. Place both DLLs alongside your application entry point
+
+## Quick Start
+
+```typescript
+import { Database } from "quiverdb";
+
+const db = Database.fromSchema("my.db", "schema.sql");
+db.createElement("Items", { label: "Item 1", value: 42 });
+
+const values = db.readScalarIntegers("Items", "value");
+console.log(values); // [42]
+
+db.close();
+```
+
+## API Methods
+
+### Lifecycle
+
+- `Database.fromSchema(dbPath, schemaPath)` -- Create database from SQL schema file
+- `Database.fromMigrations(dbPath, migrationsPath)` -- Create database from migrations directory
+- `close()` -- Close the database connection
+
+### Create / Delete
+
+- `createElement(collection, data)` -- Create element, returns numeric ID
+- `deleteElement(collection, id)` -- Delete element by ID
+
+### Read (bulk)
+
+- `readScalarIntegers(collection, attribute)` -- Read all integer scalars
+- `readScalarFloats(collection, attribute)` -- Read all float scalars
+- `readScalarStrings(collection, attribute)` -- Read all string scalars
+
+### Read (by ID)
+
+- `readScalarIntegerById(collection, attribute, id)` -- Read integer or null
+- `readScalarFloatById(collection, attribute, id)` -- Read float or null
+- `readScalarStringById(collection, attribute, id)` -- Read string or null
+
+### Read (IDs)
+
+- `readElementIds(collection)` -- Read all element IDs in a collection
+
+### Query
+
+- `queryString(sql, params?)` -- Query returning string or null
+- `queryInteger(sql, params?)` -- Query returning integer or null
+- `queryFloat(sql, params?)` -- Query returning float or null
+
+Parameters are passed as an array of `number | string | null`.
+
+### Transaction
+
+- `beginTransaction()` -- Begin explicit transaction
+- `commit()` -- Commit current transaction
+- `rollback()` -- Rollback current transaction
+- `inTransaction()` -- Check if transaction is active
+
+## Types
+
+Exported types available for TypeScript consumers:
+
+- `ScalarValue` -- `number | bigint | string | null`
+- `ArrayValue` -- `number[] | bigint[] | string[]`
+- `Value` -- `ScalarValue | ArrayValue`
+- `ElementData` -- `Record<string, Value | undefined>`
+- `QueryParam` -- `number | string | null`
+- `QuiverError` -- Error class for all Quiver operations
+
+## Development
+
+```bash
+bun test         # Run all tests
+bun run typecheck # TypeScript type checking (tsc --noEmit)
+bun run lint     # Biome linting
+bun run format   # Biome formatting (auto-fix)
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "quiverdb",
+  "version": "0.5.0",
+  "description": "Bun-native SQLite wrapper binding for Quiver via bun:ffi",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "sqlite",
+    "database",
+    "ffi",
+    "bun",
+    "quiver"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "format": "biome format --write"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@types/bun": "^1.3.10",
+    "typescript": "^5.9.3"
+  }
+}

package/src/create.ts

@@ -0,0 +1,128 @@
+import { type Pointer, ptr } from "bun:ffi";
+import { Database } from "./database";
+import { check, QuiverError } from "./errors";
+import { allocPointerOut, readPointerOut, toCString } from "./ffi-helpers";
+import { getSymbols } from "./loader";
+import type { ElementData, Value } from "./types";
+
+declare module "./database" {
+  interface Database {
+    createElement(collection: string, data: ElementData): number;
+    deleteElement(collection: string, id: number): void;
+  }
+}
+
+type Symbols = ReturnType<typeof getSymbols>;
+
+function setElementArray(lib: Symbols, elemPtr: Pointer, name: string, values: unknown[]): void {
+  const cName = toCString(name);
+
+  if (values.length === 0) {
+    // Empty array: pass null pointer with count 0
+    check(lib.quiver_element_set_array_integer(elemPtr, cName, null, 0));
+    return;
+  }
+
+  const first = values[0];
+
+  if (typeof first === "bigint") {
+    const arr = BigInt64Array.from(values as bigint[], (v) => BigInt(v));
+    check(lib.quiver_element_set_array_integer(elemPtr, cName, ptr(arr), values.length));
+    return;
+  }
+
+  if (typeof first === "number") {
+    const allIntegers = (values as number[]).every((v) => Number.isInteger(v));
+    if (allIntegers) {
+      const arr = BigInt64Array.from(values as number[], (v) => BigInt(v));
+      check(lib.quiver_element_set_array_integer(elemPtr, cName, ptr(arr), values.length));
+    } else {
+      const arr = Float64Array.from(values as number[]);
+      check(lib.quiver_element_set_array_float(elemPtr, cName, ptr(arr), values.length));
+    }
+    return;
+  }
+
+  if (typeof first === "string") {
+    // Build pointer table: BigInt64Array of pointers to each string buffer
+    const buffers = (values as string[]).map((s) => toCString(s));
+    const ptrTable = new BigInt64Array(buffers.length);
+    for (let i = 0; i < buffers.length; i++) {
+      ptrTable[i] = BigInt(ptr(buffers[i]));
+    }
+    check(lib.quiver_element_set_array_string(elemPtr, cName, ptr(ptrTable), values.length));
+    return;
+  }
+
+  throw new QuiverError(`Unsupported array element type for '${name}': ${typeof first}`);
+}
+
+function setElementField(lib: Symbols, elemPtr: Pointer, name: string, value: Value): void {
+  const cName = toCString(name);
+
+  if (value === null) {
+    check(lib.quiver_element_set_null(elemPtr, cName));
+    return;
+  }
+
+  if (typeof value === "bigint") {
+    check(lib.quiver_element_set_integer(elemPtr, cName, value));
+    return;
+  }
+
+  if (typeof value === "number") {
+    if (Number.isInteger(value)) {
+      check(lib.quiver_element_set_integer(elemPtr, cName, value));
+    } else {
+      check(lib.quiver_element_set_float(elemPtr, cName, value));
+    }
+    return;
+  }
+
+  if (typeof value === "string") {
+    check(lib.quiver_element_set_string(elemPtr, cName, toCString(value)));
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    setElementArray(lib, elemPtr, name, value);
+    return;
+  }
+
+  throw new QuiverError(`Unsupported value type for '${name}': ${typeof value}`);
+}
+
+Database.prototype.createElement = function (
+  this: Database,
+  collection: string,
+  data: ElementData,
+): number {
+  const lib = getSymbols();
+  const handle = this._handle; // triggers ensureOpen
+
+  // Create element handle
+  const outElem = allocPointerOut();
+  check(lib.quiver_element_create(ptr(outElem)));
+  const elemPtr = readPointerOut(outElem);
+
+  try {
+    // Set fields from data object
+    for (const [key, value] of Object.entries(data)) {
+      if (value === undefined) continue;
+      setElementField(lib, elemPtr, key, value);
+    }
+
+    // Create element in database
+    const outId = new BigInt64Array(1);
+    check(lib.quiver_database_create_element(handle, toCString(collection), elemPtr, ptr(outId)));
+
+    return Number(outId[0]);
+  } finally {
+    lib.quiver_element_destroy(elemPtr);
+  }
+};
+
+Database.prototype.deleteElement = function (this: Database, collection: string, id: number): void {
+  const lib = getSymbols();
+  check(lib.quiver_database_delete_element(this._handle, toCString(collection), id));
+};

package/src/database.ts

@@ -0,0 +1,68 @@
+import { type Pointer, ptr } from "bun:ffi";
+import { check, QuiverError } from "./errors";
+import { allocPointerOut, makeDefaultOptions, readPointerOut, toCString } from "./ffi-helpers";
+import { getSymbols } from "./loader";
+
+export class Database {
+  private _ptr: Pointer;
+  private _closed = false;
+
+  private constructor(nativePtr: Pointer) {
+    this._ptr = nativePtr;
+  }
+
+  static fromSchema(dbPath: string, schemaPath: string): Database {
+    const lib = getSymbols();
+    const options = makeDefaultOptions();
+    const outDb = allocPointerOut();
+
+    check(
+      lib.quiver_database_from_schema(
+        toCString(dbPath),
+        toCString(schemaPath),
+        ptr(options),
+        ptr(outDb),
+      ),
+    );
+
+    const dbPtr = readPointerOut(outDb);
+    return new Database(dbPtr);
+  }
+
+  static fromMigrations(dbPath: string, migrationsPath: string): Database {
+    const lib = getSymbols();
+    const options = makeDefaultOptions();
+    const outDb = allocPointerOut();
+
+    check(
+      lib.quiver_database_from_migrations(
+        toCString(dbPath),
+        toCString(migrationsPath),
+        ptr(options),
+        ptr(outDb),
+      ),
+    );
+
+    const dbPtr = readPointerOut(outDb);
+    return new Database(dbPtr);
+  }
+
+  close(): void {
+    if (this._closed) return;
+    const lib = getSymbols();
+    check(lib.quiver_database_close(this._ptr));
+    this._closed = true;
+  }
+
+  private ensureOpen(): void {
+    if (this._closed) {
+      throw new QuiverError("Database is closed");
+    }
+  }
+
+  /** @internal */
+  get _handle(): Pointer {
+    this.ensureOpen();
+    return this._ptr;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,24 @@
+import { CString } from "bun:ffi";
+import { getSymbols } from "./loader";
+
+export class QuiverError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "QuiverError";
+  }
+}
+
+export function check(err: number): void {
+  if (err !== 0) {
+    const lib = getSymbols();
+    const errPtr = lib.quiver_get_last_error();
+    if (errPtr) {
+      const detail = new CString(errPtr).toString();
+      if (detail) {
+        throw new QuiverError(detail);
+      }
+    }
+    console.warn("check: C API returned error but quiver_get_last_error() is empty");
+    throw new QuiverError("Unknown error");
+  }
+}

package/src/ffi-helpers.ts

@@ -0,0 +1,48 @@
+import { type Pointer, ptr, read } from "bun:ffi";
+
+/**
+ * Construct the 8-byte quiver_database_options_t struct manually.
+ * Layout: offset 0 = int32 read_only (default 0), offset 4 = int32 console_level (default 1 = QUIVER_LOG_INFO).
+ * DO NOT call quiver_database_options_default() -- it returns struct by value which bun:ffi cannot handle.
+ */
+export function makeDefaultOptions(): Uint8Array {
+  const buf = new ArrayBuffer(8);
+  const view = new Int32Array(buf);
+  view[0] = 0; // read_only = false
+  view[1] = 1; // console_level = QUIVER_LOG_INFO
+  return new Uint8Array(buf);
+}
+
+/**
+ * Allocate a 1-element BigInt64Array (8 bytes) to receive a quiver_database_t** out-parameter.
+ * Caller passes ptr(result) to the FFI function.
+ */
+export function allocPointerOut(): BigInt64Array {
+  return new BigInt64Array(1);
+}
+
+/**
+ * Read the pointer value from an out-parameter buffer.
+ * Dereferences the pointer stored at offset 0 of the typed array.
+ * Returns a branded Pointer suitable for passing to FFI functions.
+ * read.ptr() returns number at runtime; the cast to Pointer satisfies bun:ffi type signatures.
+ */
+export function readPointerOut(buf: BigInt64Array): Pointer {
+  return read.ptr(ptr(buf), 0) as unknown as Pointer;
+}
+
+/**
+ * Read a pointer at the given byte offset from a base pointer.
+ * Wraps read.ptr() with a cast to the branded Pointer type.
+ */
+export function readPtrAt(base: Pointer, byteOffset: number): Pointer {
+  return read.ptr(base, byteOffset) as unknown as Pointer;
+}
+
+/**
+ * Encode a JS string as null-terminated UTF-8 for the C API.
+ * Returns a Buffer suitable for passing as FFIType.ptr.
+ */
+export function toCString(str: string): Buffer {
+  return Buffer.from(`${str}\0`);
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+import "./create";
+import "./read";
+import "./query";
+import "./transaction";
+
+export { Database } from "./database";
+export { QuiverError } from "./errors";
+export type { ArrayValue, ElementData, QueryParam, ScalarValue, Value } from "./types";

package/src/loader.ts

@@ -0,0 +1,286 @@
+import { dlopen, FFIType, suffix } from "bun:ffi";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { QuiverError } from "./errors";
+
+const CORE_LIB = `libquiver.${suffix}`;
+const C_API_LIB = `libquiver_c.${suffix}`;
+
+/**
+ * Pre-load a DLL on Windows using kernel32 LoadLibraryA.
+ * bun:ffi dlopen() requires at least one symbol, so it cannot be used
+ * for dependency-only pre-loading (libquiver.dll has no C API symbols).
+ * This is the equivalent of Python's os.add_dll_directory() approach.
+ */
+function preloadWindows(dllPath: string): void {
+  const kernel32 = dlopen("kernel32.dll", {
+    LoadLibraryA: { args: [FFIType.ptr], returns: FFIType.ptr },
+  });
+  kernel32.symbols.LoadLibraryA(Buffer.from(`${dllPath}\0`));
+}
+
+const symbols = {
+  quiver_version: {
+    args: [],
+    returns: FFIType.cstring,
+  },
+  quiver_get_last_error: {
+    args: [],
+    returns: FFIType.ptr,
+  },
+  quiver_clear_last_error: {
+    args: [],
+    returns: FFIType.void,
+  },
+  quiver_database_from_schema: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_from_migrations: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_close: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
+
+  // Element lifecycle
+  quiver_element_create: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_element_destroy: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
+
+  // Element scalar setters
+  quiver_element_set_integer: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.i64],
+    returns: FFIType.i32,
+  },
+  quiver_element_set_float: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.f64],
+    returns: FFIType.i32,
+  },
+  quiver_element_set_string: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_element_set_null: {
+    args: [FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+
+  // Element array setters
+  quiver_element_set_array_integer: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  quiver_element_set_array_float: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  quiver_element_set_array_string: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.i32],
+    returns: FFIType.i32,
+  },
+
+  // Database CRUD
+  quiver_database_create_element: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_delete_element: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.i64],
+    returns: FFIType.i32,
+  },
+
+  // Read scalar arrays
+  quiver_database_read_scalar_integers: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_read_scalar_floats: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_read_scalar_strings: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+
+  // Read scalar by ID
+  quiver_database_read_scalar_integer_by_id: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.i64, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_read_scalar_float_by_id: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.i64, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_read_scalar_string_by_id: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.i64, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+
+  // Read element IDs
+  quiver_database_read_element_ids: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+
+  // Free functions
+  quiver_database_free_integer_array: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_free_float_array: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_free_string_array: {
+    args: [FFIType.ptr, FFIType.u64],
+    returns: FFIType.i32,
+  },
+  quiver_database_free_string: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
+
+  // Query operations (plain)
+  quiver_database_query_string: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_query_integer: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_query_float: {
+    args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+
+  // Query operations (parameterized)
+  quiver_database_query_string_params: {
+    args: [
+      FFIType.ptr,
+      FFIType.ptr,
+      FFIType.ptr,
+      FFIType.ptr,
+      FFIType.u64,
+      FFIType.ptr,
+      FFIType.ptr,
+    ],
+    returns: FFIType.i32,
+  },
+  quiver_database_query_integer_params: {
+    args: [
+      FFIType.ptr,
+      FFIType.ptr,
+      FFIType.ptr,
+      FFIType.ptr,
+      FFIType.u64,
+      FFIType.ptr,
+      FFIType.ptr,
+    ],
+    returns: FFIType.i32,
+  },
+  quiver_database_query_float_params: {
+    args: [
+      FFIType.ptr,
+      FFIType.ptr,
+      FFIType.ptr,
+      FFIType.ptr,
+      FFIType.u64,
+      FFIType.ptr,
+      FFIType.ptr,
+    ],
+    returns: FFIType.i32,
+  },
+
+  // Transaction control
+  quiver_database_begin_transaction: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_commit: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_rollback: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
+  quiver_database_in_transaction: {
+    args: [FFIType.ptr, FFIType.ptr],
+    returns: FFIType.i32,
+  },
+} as const;
+
+type Library = ReturnType<typeof dlopen<typeof symbols>>;
+
+let _library: Library | null = null;
+
+function getSearchPaths(): string[] {
+  const paths: string[] = [];
+
+  // Walk up from import.meta.dir (bindings/js/src/) looking for build/bin/
+  let dir = import.meta.dir;
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, "build", "bin");
+    if (existsSync(join(candidate, C_API_LIB))) {
+      paths.push(candidate);
+    }
+    dir = dirname(dir);
+  }
+
+  return paths;
+}
+
+export function loadLibrary(): Library {
+  if (_library) return _library;
+
+  const searchPaths = getSearchPaths();
+
+  for (const dir of searchPaths) {
+    const corePath = join(dir, CORE_LIB);
+    const cApiPath = join(dir, C_API_LIB);
+    if (!existsSync(cApiPath)) continue;
+
+    try {
+      // Windows: pre-load core library (dependency chain)
+      if (suffix === "dll" && existsSync(corePath)) {
+        preloadWindows(corePath);
+      }
+      _library = dlopen(cApiPath, symbols);
+      return _library;
+    } catch {}
+  }
+
+  // Fallback: try system PATH (bare library name)
+  try {
+    if (suffix === "dll") {
+      try {
+        preloadWindows(CORE_LIB);
+      } catch {
+        // Core lib may already be loaded or not needed on this platform
+      }
+    }
+    _library = dlopen(C_API_LIB, symbols);
+    return _library;
+  } catch {
+    // Fall through to error
+  }
+
+  const searched =
+    searchPaths.length > 0 ? `${searchPaths.join(", ")}, system PATH` : "system PATH";
+
+  throw new QuiverError(`Cannot load native library '${C_API_LIB}'. Searched: ${searched}`);
+}
+
+export function getSymbols(): Library["symbols"] {
+  return loadLibrary().symbols;
+}

package/src/query.ts

@@ -0,0 +1,164 @@
+import { CString, ptr } from "bun:ffi";
+import { Database } from "./database";
+import { check } from "./errors";
+import { allocPointerOut, readPointerOut, toCString } from "./ffi-helpers";
+import { getSymbols } from "./loader";
+import type { QueryParam } from "./types";
+
+declare module "./database" {
+  interface Database {
+    queryString(sql: string, params?: QueryParam[]): string | null;
+    queryInteger(sql: string, params?: QueryParam[]): number | null;
+    queryFloat(sql: string, params?: QueryParam[]): number | null;
+  }
+}
+
+// C API data type enum values (from include/quiver/c/database.h)
+const DATA_TYPE_INTEGER = 0;
+const DATA_TYPE_FLOAT = 1;
+const DATA_TYPE_STRING = 2;
+const DATA_TYPE_NULL = 4;
+
+interface MarshaledParams {
+  types: Int32Array;
+  values: BigInt64Array;
+  _keepalive: unknown[];
+}
+
+function marshalParams(params: QueryParam[]): MarshaledParams {
+  const n = params.length;
+  const types = new Int32Array(n);
+  const values = new BigInt64Array(n);
+  const keepalive: unknown[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const p = params[i];
+    if (p === null) {
+      types[i] = DATA_TYPE_NULL;
+      values[i] = 0n;
+    } else if (typeof p === "number") {
+      if (Number.isInteger(p)) {
+        types[i] = DATA_TYPE_INTEGER;
+        const buf = new BigInt64Array([BigInt(p)]);
+        keepalive.push(buf);
+        values[i] = BigInt(ptr(buf));
+      } else {
+        types[i] = DATA_TYPE_FLOAT;
+        const buf = new Float64Array([p]);
+        keepalive.push(buf);
+        values[i] = BigInt(ptr(buf));
+      }
+    } else if (typeof p === "string") {
+      types[i] = DATA_TYPE_STRING;
+      const buf = toCString(p);
+      keepalive.push(buf);
+      values[i] = BigInt(ptr(buf));
+    }
+  }
+
+  return { types, values, _keepalive: keepalive };
+}
+
+Database.prototype.queryString = function (
+  this: Database,
+  sql: string,
+  params?: QueryParam[],
+): string | null {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outValue = allocPointerOut();
+  const outHasValue = new Int32Array(1);
+
+  if (params && params.length > 0) {
+    const marshaled = marshalParams(params);
+    check(
+      lib.quiver_database_query_string_params(
+        handle,
+        toCString(sql),
+        ptr(marshaled.types),
+        ptr(marshaled.values),
+        params.length,
+        ptr(outValue),
+        ptr(outHasValue),
+      ),
+    );
+  } else {
+    check(
+      lib.quiver_database_query_string(handle, toCString(sql), ptr(outValue), ptr(outHasValue)),
+    );
+  }
+
+  if (outHasValue[0] === 0) return null;
+
+  const strPtr = readPointerOut(outValue);
+  const result = new CString(strPtr).toString();
+  lib.quiver_database_free_string(strPtr);
+  return result;
+};
+
+Database.prototype.queryInteger = function (
+  this: Database,
+  sql: string,
+  params?: QueryParam[],
+): number | null {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outValue = new BigInt64Array(1);
+  const outHasValue = new Int32Array(1);
+
+  if (params && params.length > 0) {
+    const marshaled = marshalParams(params);
+    check(
+      lib.quiver_database_query_integer_params(
+        handle,
+        toCString(sql),
+        ptr(marshaled.types),
+        ptr(marshaled.values),
+        params.length,
+        ptr(outValue),
+        ptr(outHasValue),
+      ),
+    );
+  } else {
+    check(
+      lib.quiver_database_query_integer(handle, toCString(sql), ptr(outValue), ptr(outHasValue)),
+    );
+  }
+
+  if (outHasValue[0] === 0) return null;
+  return Number(outValue[0]);
+};
+
+Database.prototype.queryFloat = function (
+  this: Database,
+  sql: string,
+  params?: QueryParam[],
+): number | null {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outValue = new Float64Array(1);
+  const outHasValue = new Int32Array(1);
+
+  if (params && params.length > 0) {
+    const marshaled = marshalParams(params);
+    check(
+      lib.quiver_database_query_float_params(
+        handle,
+        toCString(sql),
+        ptr(marshaled.types),
+        ptr(marshaled.values),
+        params.length,
+        ptr(outValue),
+        ptr(outHasValue),
+      ),
+    );
+  } else {
+    check(lib.quiver_database_query_float(handle, toCString(sql), ptr(outValue), ptr(outHasValue)));
+  }
+
+  if (outHasValue[0] === 0) return null;
+  return outValue[0];
+};

package/src/read.ts

@@ -0,0 +1,231 @@
+import { CString, ptr, toArrayBuffer } from "bun:ffi";
+import { Database } from "./database";
+import { check } from "./errors";
+import { allocPointerOut, readPointerOut, readPtrAt, toCString } from "./ffi-helpers";
+import { getSymbols } from "./loader";
+
+declare module "./database" {
+  interface Database {
+    readScalarIntegers(collection: string, attribute: string): number[];
+    readScalarFloats(collection: string, attribute: string): number[];
+    readScalarStrings(collection: string, attribute: string): string[];
+    readScalarIntegerById(collection: string, attribute: string, id: number): number | null;
+    readScalarFloatById(collection: string, attribute: string, id: number): number | null;
+    readScalarStringById(collection: string, attribute: string, id: number): string | null;
+    readElementIds(collection: string): number[];
+  }
+}
+
+Database.prototype.readScalarIntegers = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+): number[] {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outValues = allocPointerOut();
+  const outCount = new BigUint64Array(1);
+
+  check(
+    lib.quiver_database_read_scalar_integers(
+      handle,
+      toCString(collection),
+      toCString(attribute),
+      ptr(outValues),
+      ptr(outCount),
+    ),
+  );
+
+  const count = Number(outCount[0]);
+  if (count === 0) return [];
+
+  const valuesPtr = readPointerOut(outValues);
+  const buffer = toArrayBuffer(valuesPtr, 0, count * 8);
+  const bigInts = new BigInt64Array(buffer);
+  const result: number[] = new Array(count);
+  for (let i = 0; i < count; i++) {
+    result[i] = Number(bigInts[i]);
+  }
+
+  lib.quiver_database_free_integer_array(valuesPtr);
+  return result;
+};
+
+Database.prototype.readScalarFloats = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+): number[] {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outValues = allocPointerOut();
+  const outCount = new BigUint64Array(1);
+
+  check(
+    lib.quiver_database_read_scalar_floats(
+      handle,
+      toCString(collection),
+      toCString(attribute),
+      ptr(outValues),
+      ptr(outCount),
+    ),
+  );
+
+  const count = Number(outCount[0]);
+  if (count === 0) return [];
+
+  const valuesPtr = readPointerOut(outValues);
+  const buffer = toArrayBuffer(valuesPtr, 0, count * 8);
+  const result = Array.from(new Float64Array(buffer));
+
+  lib.quiver_database_free_float_array(valuesPtr);
+  return result;
+};
+
+Database.prototype.readScalarStrings = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+): string[] {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outValues = allocPointerOut();
+  const outCount = new BigUint64Array(1);
+
+  check(
+    lib.quiver_database_read_scalar_strings(
+      handle,
+      toCString(collection),
+      toCString(attribute),
+      ptr(outValues),
+      ptr(outCount),
+    ),
+  );
+
+  const count = Number(outCount[0]);
+  if (count === 0) return [];
+
+  const arrPtr = readPointerOut(outValues);
+  const result: string[] = new Array(count);
+  for (let i = 0; i < count; i++) {
+    const strPtr = readPtrAt(arrPtr, i * 8);
+    result[i] = new CString(strPtr).toString();
+  }
+
+  lib.quiver_database_free_string_array(arrPtr, count);
+  return result;
+};
+
+Database.prototype.readScalarIntegerById = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+  id: number,
+): number | null {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outValue = new BigInt64Array(1);
+  const outHasValue = new Int32Array(1);
+
+  check(
+    lib.quiver_database_read_scalar_integer_by_id(
+      handle,
+      toCString(collection),
+      toCString(attribute),
+      id,
+      ptr(outValue),
+      ptr(outHasValue),
+    ),
+  );
+
+  if (outHasValue[0] === 0) return null;
+  return Number(outValue[0]);
+};
+
+Database.prototype.readScalarFloatById = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+  id: number,
+): number | null {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outValue = new Float64Array(1);
+  const outHasValue = new Int32Array(1);
+
+  check(
+    lib.quiver_database_read_scalar_float_by_id(
+      handle,
+      toCString(collection),
+      toCString(attribute),
+      id,
+      ptr(outValue),
+      ptr(outHasValue),
+    ),
+  );
+
+  if (outHasValue[0] === 0) return null;
+  return outValue[0];
+};
+
+Database.prototype.readScalarStringById = function (
+  this: Database,
+  collection: string,
+  attribute: string,
+  id: number,
+): string | null {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outValue = allocPointerOut();
+  const outHasValue = new Int32Array(1);
+
+  check(
+    lib.quiver_database_read_scalar_string_by_id(
+      handle,
+      toCString(collection),
+      toCString(attribute),
+      id,
+      ptr(outValue),
+      ptr(outHasValue),
+    ),
+  );
+
+  if (outHasValue[0] === 0) return null;
+
+  const strPtr = readPointerOut(outValue);
+  const result = new CString(strPtr).toString();
+  lib.quiver_database_free_string(strPtr);
+  return result;
+};
+
+Database.prototype.readElementIds = function (this: Database, collection: string): number[] {
+  const lib = getSymbols();
+  const handle = this._handle;
+
+  const outIds = allocPointerOut();
+  const outCount = new BigUint64Array(1);
+
+  check(
+    lib.quiver_database_read_element_ids(handle, toCString(collection), ptr(outIds), ptr(outCount)),
+  );
+
+  const count = Number(outCount[0]);
+  if (count === 0) return [];
+
+  const idsPtr = readPointerOut(outIds);
+  const buffer = toArrayBuffer(idsPtr, 0, count * 8);
+  const bigInts = new BigInt64Array(buffer);
+  const result: number[] = new Array(count);
+  for (let i = 0; i < count; i++) {
+    result[i] = Number(bigInts[i]);
+  }
+
+  lib.quiver_database_free_integer_array(idsPtr);
+  return result;
+};

package/src/transaction.ts

@@ -0,0 +1,35 @@
+import { ptr } from "bun:ffi";
+import { Database } from "./database";
+import { check } from "./errors";
+import { getSymbols } from "./loader";
+
+declare module "./database" {
+  interface Database {
+    beginTransaction(): void;
+    commit(): void;
+    rollback(): void;
+    inTransaction(): boolean;
+  }
+}
+
+Database.prototype.beginTransaction = function (this: Database): void {
+  const lib = getSymbols();
+  check(lib.quiver_database_begin_transaction(this._handle));
+};
+
+Database.prototype.commit = function (this: Database): void {
+  const lib = getSymbols();
+  check(lib.quiver_database_commit(this._handle));
+};
+
+Database.prototype.rollback = function (this: Database): void {
+  const lib = getSymbols();
+  check(lib.quiver_database_rollback(this._handle));
+};
+
+Database.prototype.inTransaction = function (this: Database): boolean {
+  const lib = getSymbols();
+  const outActive = new Uint8Array(1);
+  check(lib.quiver_database_in_transaction(this._handle, ptr(outActive)));
+  return outActive[0] !== 0;
+};

package/src/types.ts

@@ -0,0 +1,5 @@
+export type ScalarValue = number | bigint | string | null;
+export type ArrayValue = number[] | bigint[] | string[];
+export type Value = ScalarValue | ArrayValue;
+export type ElementData = Record<string, Value | undefined>;
+export type QueryParam = number | string | null;

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["@types/bun"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}