@ccheever/exact-ibex-runtime 0.1.0

package/src/sqlite/Database.ts

@@ -0,0 +1,456 @@
+/**
+ * SQLite Database for the Ibex runtime.
+ *
+ * API matches bun:sqlite's Database class with cr-sqlite extension support.
+ *
+ * @see https://bun.sh/docs/api/sqlite
+ * @see https://vlcn.io/docs/cr-sqlite/intro
+ */
+
+import { Statement, type Changes } from './Statement';
+
+const g = globalThis as any;
+
+export interface DatabaseOptions {
+  /** Open the database as read-only. */
+  readonly?: boolean;
+  /** Create the database if it doesn't exist (default: true). */
+  create?: boolean;
+  /** Open for read-write (default: true). */
+  readwrite?: boolean;
+  /** Return integers as BigInt instead of Number. */
+  safeIntegers?: boolean;
+  /** Strict parameter binding (no prefix needed, errors on missing params). */
+  strict?: boolean;
+}
+
+export class Database {
+  /** @internal */
+  _handle: any;
+  /** @internal */
+  _closed = false;
+  /** @internal */
+  _queryCache = new Map<string, Statement>();
+  /** @internal */
+  _options: DatabaseOptions;
+  /** @internal */
+  _crSqliteLoaded = false;
+
+  /** The filename of the database. */
+  readonly filename: string;
+
+  /**
+   * Create or open a SQLite database.
+   *
+   * @param filename Path to the database file.
+   *   - `:memory:` or `""` or omitted for in-memory database
+   * @param options Database options or raw SQLite open flags
+   */
+  constructor(filename?: string, options?: number | DatabaseOptions) {
+    this.filename = filename ?? ':memory:';
+
+    if (typeof options === 'number') {
+      this._options = {};
+    } else {
+      this._options = options ?? {};
+    }
+
+    if (!g.__exactSqliteOpen) {
+      throw new Error(
+        'exact:sqlite native bridge not available. ' +
+        'The exact:sqlite module requires the Ibex runtime with SQLite support.'
+      );
+    }
+
+    const flags = typeof options === 'number' ? options : undefined;
+    this._handle = g.__exactSqliteOpen(this.filename, {
+      readonly: this._options.readonly ?? false,
+      create: this._options.create ?? true,
+      readwrite: this._options.readwrite ?? true,
+      safeIntegers: this._options.safeIntegers ?? false,
+      flags,
+    });
+
+    // Enable WAL mode by default for better concurrent access
+    this.run('PRAGMA journal_mode = WAL');
+    this.run('PRAGMA foreign_keys = ON');
+  }
+
+  /**
+   * The native SQLite handle.
+   */
+  get handle(): any {
+    return this._handle;
+  }
+
+  /**
+   * Whether the database is currently in a transaction.
+   */
+  get inTransaction(): boolean {
+    this._checkClosed();
+    if (g.__exactSqliteInTransaction) {
+      return g.__exactSqliteInTransaction(this._handle);
+    }
+    return false;
+  }
+
+  /**
+   * Prepare and cache a SQL statement.
+   * Returns the cached statement if the same SQL was previously queried.
+   */
+  query<R = any, P extends any[] = any[]>(sql: string): Statement<R, P> {
+    this._checkClosed();
+    let stmt = this._queryCache.get(sql);
+    if (!stmt) {
+      stmt = new Statement(this._handle, sql);
+      this._queryCache.set(sql, stmt);
+    }
+    return stmt as Statement<R, P>;
+  }
+
+  /**
+   * Prepare a SQL statement WITHOUT caching.
+   * Creates a fresh Statement each time.
+   */
+  prepare<R = any, P extends any[] = any[]>(sql: string): Statement<R, P> {
+    this._checkClosed();
+    return new Statement<R, P>(this._handle, sql);
+  }
+
+  /**
+   * Execute a SQL statement directly.
+   * Supports multi-statement SQL (e.g., "SELECT 1; SELECT 2;").
+   *
+   * @returns Changes info with `changes` and `lastInsertRowid`
+   */
+  run(sql: string, ...bindings: any[]): Changes {
+    this._checkClosed();
+    if (g.__exactSqliteExec) {
+      const params = bindings.length === 1 && typeof bindings[0] === 'object' && bindings[0] !== null && !(bindings[0] instanceof Uint8Array)
+        ? bindings[0]
+        : bindings.length > 0 ? bindings : undefined;
+      return g.__exactSqliteExec(this._handle, sql, params);
+    }
+    // Fallback: use prepare + run
+    const stmt = this.prepare(sql);
+    try {
+      return stmt.run(...bindings);
+    } finally {
+      stmt.finalize();
+    }
+  }
+
+  /**
+   * Alias for run().
+   */
+  exec(sql: string, ...bindings: any[]): Changes {
+    return this.run(sql, ...bindings);
+  }
+
+  /**
+   * Create a transaction wrapper function.
+   *
+   * @returns A callable function that wraps execution in BEGIN/COMMIT.
+   *   If the function throws, the transaction is rolled back.
+   *   The returned function has `.deferred()`, `.immediate()`, and `.exclusive()` variants.
+   */
+  transaction<T extends (...args: any[]) => any>(fn: T): T & {
+    deferred: T;
+    immediate: T;
+    exclusive: T;
+  } {
+    this._checkClosed();
+    const db = this;
+
+    const wrapTransaction = (beginStatement: string) => {
+      return function (this: any, ...args: any[]) {
+        // Nested transactions use savepoints
+        if (db.inTransaction) {
+          const savepointName = `_sp_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+          db.run(`SAVEPOINT "${savepointName}"`);
+          try {
+            const result = fn.apply(this, args);
+            db.run(`RELEASE "${savepointName}"`);
+            return result;
+          } catch (e) {
+            db.run(`ROLLBACK TO "${savepointName}"`);
+            db.run(`RELEASE "${savepointName}"`);
+            throw e;
+          }
+        }
+
+        db.run(beginStatement);
+        try {
+          const result = fn.apply(this, args);
+          db.run('COMMIT');
+          return result;
+        } catch (e) {
+          db.run('ROLLBACK');
+          throw e;
+        }
+      } as any;
+    };
+
+    const txnFn = wrapTransaction('BEGIN') as any;
+    txnFn.deferred = wrapTransaction('BEGIN DEFERRED');
+    txnFn.immediate = wrapTransaction('BEGIN IMMEDIATE');
+    txnFn.exclusive = wrapTransaction('BEGIN EXCLUSIVE');
+
+    return txnFn;
+  }
+
+  /**
+   * Close the database connection.
+   * @param throwOnError If true, throws on close errors (default: false)
+   */
+  close(throwOnError = false): void {
+    if (this._closed) return;
+
+    // Finalize cr-sqlite before closing (needs db still open)
+    if (this._crSqliteLoaded) {
+      try {
+        this.run('SELECT crsql_finalize()');
+      } catch {
+        // Ignore errors during cleanup
+      }
+    }
+
+    this._closed = true;
+
+    // Finalize cached statements
+    for (const stmt of this._queryCache.values()) {
+      stmt.finalize();
+    }
+    this._queryCache.clear();
+
+    if (g.__exactSqliteClose) {
+      try {
+        g.__exactSqliteClose(this._handle);
+      } catch (e) {
+        if (throwOnError) throw e;
+      }
+    }
+  }
+
+  /**
+   * Serialize the database to a Buffer/Uint8Array.
+   * @param name Database name (default: "main")
+   */
+  serialize(name?: string): Uint8Array {
+    this._checkClosed();
+    if (!g.__exactSqliteSerialize) {
+      throw new Error('Database serialization not supported in this build');
+    }
+    return g.__exactSqliteSerialize(this._handle, name ?? 'main');
+  }
+
+  /**
+   * Load a SQLite extension.
+   * @param path Path to the extension shared library
+   * @param entryPoint Optional entry point function name
+   */
+  loadExtension(path: string, entryPoint?: string): void {
+    this._checkClosed();
+    if (!g.__exactSqliteLoadExtension) {
+      throw new Error('Extension loading not supported in this build');
+    }
+    g.__exactSqliteLoadExtension(this._handle, path, entryPoint);
+  }
+
+  /**
+   * Advanced sqlite3_file_control interface.
+   */
+  fileControl(cmd: number, value?: any): any;
+  fileControl(zDbName: string, cmd: number, value?: any): any;
+  fileControl(...args: any[]): any {
+    this._checkClosed();
+    if (!g.__exactSqliteFileControl) {
+      throw new Error('fileControl not supported in this build');
+    }
+    return g.__exactSqliteFileControl(this._handle, ...args);
+  }
+
+  // ================================================================
+  // cr-sqlite extension support
+  // ================================================================
+
+  /**
+   * Load and initialize the cr-sqlite extension for CRDT-based replication.
+   *
+   * After calling this, you can use:
+   * - `db.run("SELECT crsql_as_crr('table_name')")` to make a table a CRR
+   * - `db.query("SELECT * FROM crsql_changes WHERE db_version > ?")` to get changes
+   * - `db.run("INSERT INTO crsql_changes ...")` to apply changes from another peer
+   *
+   * @see https://vlcn.io/docs/cr-sqlite/intro
+   */
+  enableCrSqlite(): void {
+    this._checkClosed();
+    if (this._crSqliteLoaded) return;
+
+    if (g.__exactCrSqlitePath) {
+      this.loadExtension(g.__exactCrSqlitePath());
+    } else if (g.__exactSqliteLoadCrSqlite) {
+      g.__exactSqliteLoadCrSqlite(this._handle);
+    } else {
+      throw new Error(
+        'cr-sqlite extension not available. ' +
+        'The Ibex runtime must be built with cr-sqlite support.'
+      );
+    }
+    this._crSqliteLoaded = true;
+  }
+
+  /**
+   * Get the unique site ID for this database (cr-sqlite).
+   * Each database instance has a unique identifier for replication.
+   */
+  getSiteId(): Uint8Array {
+    this._checkClosed();
+    this._requireCrSqlite();
+    const result = this.query<{ id: Uint8Array }>('SELECT crsql_site_id() as id').get();
+    return result!.id;
+  }
+
+  /**
+   * Get the current database version (cr-sqlite logical clock).
+   */
+  getDbVersion(): number | bigint {
+    this._checkClosed();
+    this._requireCrSqlite();
+    const result = this.query<{ version: number }>('SELECT crsql_db_version() as version').get();
+    return result!.version;
+  }
+
+  /**
+   * Mark a table as a Conflict-free Replicated Relation (CRR).
+   * This adds CRDT metadata and triggers for automatic conflict resolution.
+   *
+   * @param tableName Name of the existing table to make a CRR
+   */
+  markAsCrr(tableName: string): void {
+    this._checkClosed();
+    this._requireCrSqlite();
+    this.run(`SELECT crsql_as_crr('${tableName}')`);
+  }
+
+  /**
+   * Get changesets since a given database version.
+   * Used for syncing with other peers.
+   *
+   * @param sinceVersion Get changes after this version (0 for all changes)
+   * @param excludeSiteId Optional site ID to exclude (optimization for bilateral sync)
+   */
+  getChanges(sinceVersion: number | bigint = 0, excludeSiteId?: Uint8Array): any[] {
+    this._checkClosed();
+    this._requireCrSqlite();
+
+    if (excludeSiteId) {
+      return this.query(
+        `SELECT "table", "pk", "cid", "val", "col_version", "db_version", "site_id", "cl", "seq"
+         FROM crsql_changes
+         WHERE db_version > ? AND site_id IS NOT ?`
+      ).all(sinceVersion, excludeSiteId);
+    }
+
+    return this.query(
+      `SELECT "table", "pk", "cid", "val", "col_version", "db_version", "site_id", "cl", "seq"
+       FROM crsql_changes
+       WHERE db_version > ?`
+    ).all(sinceVersion);
+  }
+
+  /**
+   * Apply a changeset from another peer.
+   * The changeset should be the output of getChanges() from another database.
+   *
+   * @param changes Array of change rows from getChanges()
+   */
+  applyChanges(changes: any[]): void {
+    this._checkClosed();
+    this._requireCrSqlite();
+
+    const insert = this.prepare(
+      `INSERT INTO crsql_changes ("table", "pk", "cid", "val", "col_version", "db_version", "site_id", "cl", "seq")
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    );
+
+    const applyAll = this.transaction((changes: any[]) => {
+      for (const change of changes) {
+        insert.run(
+          change.table, change.pk, change.cid, change.val,
+          change.col_version, change.db_version, change.site_id,
+          change.cl, change.seq
+        );
+      }
+    });
+
+    try {
+      applyAll(changes);
+    } finally {
+      insert.finalize();
+    }
+  }
+
+  // ================================================================
+  // Static methods
+  // ================================================================
+
+  /**
+   * Create or open a SQLite database (alias for constructor).
+   */
+  static open(filename?: string, options?: number | DatabaseOptions): Database {
+    return new Database(filename, options);
+  }
+
+  /**
+   * Create a database from serialized data.
+   */
+  static deserialize(data: Uint8Array, options?: boolean | DatabaseOptions): Database {
+    if (!g.__exactSqliteDeserialize) {
+      throw new Error('Database deserialization not supported in this build');
+    }
+
+    const isReadOnly = typeof options === 'boolean' ? options : (options as DatabaseOptions)?.readonly ?? false;
+    const handle = g.__exactSqliteDeserialize(data, isReadOnly);
+
+    const db = Object.create(Database.prototype) as Database;
+    db._handle = handle;
+    db._closed = false;
+    db._queryCache = new Map();
+    db._options = typeof options === 'object' ? options : { readonly: isReadOnly };
+    (db as any).filename = ':memory:';
+    db._crSqliteLoaded = false;
+    return db;
+  }
+
+  [Symbol.dispose](): void {
+    this.close();
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'Database';
+  }
+
+  // ================================================================
+  // Internal helpers
+  // ================================================================
+
+  /** @internal */
+  private _checkClosed(): void {
+    if (this._closed) {
+      throw new Error('Database is closed');
+    }
+  }
+
+  /** @internal */
+  private _requireCrSqlite(): void {
+    if (!this._crSqliteLoaded) {
+      throw new Error(
+        'cr-sqlite is not loaded. Call db.enableCrSqlite() first.'
+      );
+    }
+  }
+}
+
+export default Database;

package/src/sqlite/Statement.ts

@@ -0,0 +1,206 @@
+/**
+ * SQLite Statement for the Ibex runtime.
+ *
+ * Prepared statement wrapping native SQLite3 operations.
+ * API matches bun:sqlite's Statement class.
+ *
+ * @see https://bun.sh/docs/api/sqlite#statement
+ */
+
+const g = globalThis as any;
+
+export interface Changes {
+  changes: number;
+  lastInsertRowid: number | bigint;
+}
+
+type SQLBindings = string | number | bigint | boolean | null | Uint8Array;
+type SQLParams = SQLBindings | Record<string, SQLBindings>;
+
+export class Statement<ReturnType = unknown, ParamsType extends any[] = any[]> {
+  /** @internal */
+  _handle: any;
+  /** @internal */
+  _db: any;
+  /** @internal */
+  _sql: string;
+  /** @internal */
+  _finalized = false;
+  /** @internal */
+  _columnTypes: (string | null)[] = [];
+  /** @internal */
+  _declaredTypes: (string | null)[] = [];
+  /** @internal */
+  _readOnly = true;
+  /** @internal */
+  _executed = false;
+
+  /** Column names of the result set. */
+  columnNames: string[] = [];
+
+  /** Number of parameters expected by the statement. */
+  paramsCount = 0;
+
+  /** The native handle. */
+  get native(): any {
+    return {
+      columns: [...this.columnNames],
+      columnsCount: this.columnNames.length,
+    };
+  }
+
+  /** Column types based on actual values. */
+  get columnTypes(): (string | null)[] {
+    if (!this._readOnly) {
+      throw new Error('columnTypes is not available for non-read-only statements');
+    }
+    return this._columnTypes;
+  }
+
+  /** Types from CREATE TABLE schema. */
+  get declaredTypes(): (string | null)[] {
+    if (this._readOnly && !this._executed) {
+      throw new Error('Statement must be executed before accessing declaredTypes');
+    }
+    return this._declaredTypes;
+  }
+
+  /** @internal */
+  constructor(dbHandle: any, sql: string) {
+    this._db = dbHandle;
+    this._sql = sql;
+
+    if (!g.__exactSqlitePrepare) {
+      throw new Error(
+        'exact:sqlite native bridge not available. ' +
+        'The exact:sqlite module requires the Ibex runtime with SQLite support.'
+      );
+    }
+
+    const result = g.__exactSqlitePrepare(dbHandle, sql);
+    this._handle = result.handle;
+    this.columnNames = result.columnNames || [];
+    this._declaredTypes = result.declaredTypes || [];
+    this.paramsCount = result.paramsCount || 0;
+    this._readOnly = result.readOnly !== false;
+  }
+
+  /**
+   * Execute the statement and return all matching rows as objects.
+   */
+  all(...params: ParamsType): ReturnType[] {
+    this._checkFinalized();
+    const bindings = this._normalizeParams(params);
+    const result = g.__exactSqliteAll(this._handle, bindings);
+    this._recordExecution(result);
+    return result.rows;
+  }
+
+  /**
+   * Execute the statement and return the first matching row as an object.
+   * Returns null if no rows match.
+   */
+  get(...params: ParamsType): ReturnType | null {
+    this._checkFinalized();
+    const bindings = this._normalizeParams(params);
+    const result = g.__exactSqliteGet(this._handle, bindings);
+    this._recordExecution(result);
+    return result.row ?? null;
+  }
+
+  /**
+   * Execute the statement. Returns changes info.
+   */
+  run(...params: ParamsType): Changes {
+    this._checkFinalized();
+    const bindings = this._normalizeParams(params);
+    const result = g.__exactSqliteRun(this._handle, bindings);
+    this._executed = true;
+    return result;
+  }
+
+  /**
+   * Execute the statement and return all rows as arrays of values (no keys).
+   */
+  values(...params: ParamsType): unknown[][] {
+    this._checkFinalized();
+    const bindings = this._normalizeParams(params);
+    const result = g.__exactSqliteValues(this._handle, bindings);
+    this._recordExecution(result);
+    return result.rows;
+  }
+
+  /**
+   * Destroy the statement and free resources.
+   * Once finalized, the statement cannot be used again.
+   */
+  finalize(): void {
+    if (this._finalized) return;
+    this._finalized = true;
+    if (g.__exactSqliteFinalize) {
+      g.__exactSqliteFinalize(this._handle);
+    }
+  }
+
+  /**
+   * Return the expanded SQL with most recent bound values.
+   */
+  toString(): string {
+    this._checkFinalized();
+    if (g.__exactSqliteExpandedSql) {
+      return g.__exactSqliteExpandedSql(this._handle);
+    }
+    return this._sql;
+  }
+
+  /**
+   * Map results to class instances.
+   * Uses Object.create (NOT new) - constructor is NOT called.
+   */
+  as<T>(Class: new (...args: any[]) => T): Statement<T, ParamsType> {
+    const wrapped = Object.create(this);
+    const origAll = this.all.bind(this);
+    const origGet = this.get.bind(this);
+
+    wrapped.all = function (...params: any[]) {
+      const rows = origAll(...params);
+      return rows.map((row: any) => Object.assign(Object.create(Class.prototype), row));
+    };
+
+    wrapped.get = function (...params: any[]) {
+      const row = origGet(...params);
+      if (row === null) return null;
+      return Object.assign(Object.create(Class.prototype), row);
+    };
+
+    return wrapped;
+  }
+
+  [Symbol.dispose](): void {
+    this.finalize();
+  }
+
+  /** @internal */
+  private _checkFinalized(): void {
+    if (this._finalized) {
+      throw new Error('Statement has been finalized and cannot be used');
+    }
+  }
+
+  /** @internal */
+  private _normalizeParams(params: any[]): any {
+    if (params.length === 0) return undefined;
+    if (params.length === 1 && typeof params[0] === 'object' && params[0] !== null && !(params[0] instanceof Uint8Array)) {
+      return params[0]; // Named parameters
+    }
+    return params; // Positional parameters
+  }
+
+  /** @internal */
+  private _recordExecution(result: any): void {
+    this._executed = true;
+    this._columnTypes = Array.isArray(result?.columnTypes) ? result.columnTypes : [];
+  }
+}
+
+export default Statement;