@ccheever/exact-ibex-runtime 0.1.0

package/src/indexeddb/IDBDatabase.ts

@@ -0,0 +1,343 @@
+/**
+ * IDBDatabase - IndexedDB Database
+ *
+ * Represents an open connection to a database. Backed by a SQLite database.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase
+ */
+
+import { IDBTransaction, type IDBTransactionMode } from './IDBTransaction';
+import { IDBObjectStore, type IDBObjectStoreParameters } from './IDBObjectStore';
+import { IDBIndex } from './IDBIndex';
+import { DOMException, makeDOMStringList, sanitizeName } from './utils';
+
+export class IDBDatabase {
+  readonly name: string;
+  private _version: number;
+  private _objectStores: Map<string, { options: IDBObjectStoreParameters; indexes: Map<string, any> }> = new Map();
+  private _closed = false;
+  /** @internal - SQLite database wrapper */
+  _sqliteDb: any;
+  /** @internal - The active versionchange transaction during upgradeneeded, if any */
+  _upgradeTransaction: IDBTransaction | null = null;
+  /** @internal - EventTarget listeners keyed by event type */
+  private _listeners: Record<string, Function[]> = {};
+
+  onclose: ((event: any) => void) | null = null;
+  onversionchange: ((event: any) => void) | null = null;
+  onerror: ((event: any) => void) | null = null;
+  onabort: ((event: any) => void) | null = null;
+
+  constructor(name: string, version: number, sqliteDb: any) {
+    this.name = name;
+    this._version = version;
+    this._sqliteDb = sqliteDb;
+
+    // Initialize meta tables
+    this._initMeta();
+    // Load existing object store definitions
+    this._loadStoreDefinitions();
+  }
+
+  get version(): number {
+    return this._version;
+  }
+
+  get objectStoreNames(): any {
+    return makeDOMStringList(Array.from(this._objectStores.keys()).sort());
+  }
+
+  addEventListener(type: string, fn: Function): void {
+    if (!this._listeners[type]) this._listeners[type] = [];
+    this._listeners[type].push(fn);
+  }
+
+  removeEventListener(type: string, fn: Function): void {
+    const list = this._listeners[type];
+    if (list) this._listeners[type] = list.filter(f => f !== fn);
+  }
+
+  /**
+   * Create a new object store. Only valid during upgradeneeded.
+   */
+  createObjectStore(name: string, options?: IDBObjectStoreParameters): IDBObjectStore {
+    // Guard: only allowed during an active versionchange transaction
+    if (this._upgradeTransaction && this._upgradeTransaction._state !== 'active') {
+      throw new DOMException(
+        'Can only be called during upgradeneeded',
+        'InvalidStateError',
+      );
+    }
+
+    if (this._objectStores.has(name)) {
+      throw new DOMException(
+        `Object store "${name}" already exists`,
+        'ConstraintError',
+      );
+    }
+
+    const opts: IDBObjectStoreParameters = {
+      keyPath: options?.keyPath ?? null,
+      autoIncrement: options?.autoIncrement ?? false,
+    };
+
+    this._objectStores.set(name, { options: opts, indexes: new Map() });
+
+    // Persist store definition to meta table
+    this._saveStoreMeta(name, opts);
+
+    // Create the store object with a versionchange transaction
+    const txn = this._upgradeTransaction ?? new IDBTransaction(this, [name], 'versionchange');
+    const store = new IDBObjectStore(name, opts, txn, this);
+    return store;
+  }
+
+  /**
+   * Delete an object store. Only valid during upgradeneeded.
+   */
+  deleteObjectStore(name: string): void {
+    // Guard: only allowed during an active versionchange transaction
+    if (this._upgradeTransaction && this._upgradeTransaction._state !== 'active') {
+      throw new DOMException(
+        'Can only be called during upgradeneeded',
+        'InvalidStateError',
+      );
+    }
+
+    if (!this._objectStores.has(name)) {
+      throw new DOMException(
+        `Object store "${name}" does not exist`,
+        'NotFoundError',
+      );
+    }
+
+    // Drop the SQLite table
+    const tableName = `idb_store_${sanitizeName(name)}`;
+    this._exec(`DROP TABLE IF EXISTS "${tableName}"`);
+
+    // Remove from meta
+    this._exec(
+      `DELETE FROM _idb_stores WHERE store_name = ?`,
+      [name]
+    );
+    this._exec(
+      `DELETE FROM _idb_indexes WHERE store_name = ?`,
+      [name]
+    );
+
+    this._objectStores.delete(name);
+  }
+
+  /**
+   * Create a transaction for the given object stores.
+   */
+  transaction(storeNames: string | string[], mode?: IDBTransactionMode): IDBTransaction {
+    this._checkClosed();
+    const names = Array.isArray(storeNames) ? storeNames : [storeNames];
+
+    // Verify all stores exist
+    for (const name of names) {
+      if (!this._objectStores.has(name)) {
+        throw new DOMException(
+          `Object store "${name}" does not exist`,
+          'NotFoundError',
+        );
+      }
+    }
+
+    const txn = new IDBTransaction(this, names, mode ?? 'readonly');
+
+    // Auto-commit after microtasks settle
+    queueMicrotask(() => {
+      queueMicrotask(() => {
+        txn._autoCommit();
+      });
+    });
+
+    return txn;
+  }
+
+  /**
+   * Close the database connection.
+   */
+  close(): void {
+    if (this._closed) return;
+    this._closed = true;
+    if (this._sqliteDb && this._sqliteDb.close) {
+      this._sqliteDb.close();
+    }
+    if (this.onclose) {
+      const event = { type: 'close', target: this };
+      this.onclose(event);
+    }
+  }
+
+  // ================================================================
+  // Internal SQLite operations
+  // ================================================================
+
+  /** @internal */
+  _initMeta(): void {
+    this._exec(`
+      CREATE TABLE IF NOT EXISTS _idb_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT
+      )
+    `);
+    this._exec(`
+      CREATE TABLE IF NOT EXISTS _idb_stores (
+        store_name TEXT PRIMARY KEY,
+        key_path TEXT,
+        auto_increment INTEGER DEFAULT 0
+      )
+    `);
+    this._exec(`
+      CREATE TABLE IF NOT EXISTS _idb_indexes (
+        store_name TEXT,
+        index_name TEXT,
+        key_path TEXT,
+        unique_flag INTEGER DEFAULT 0,
+        multi_entry INTEGER DEFAULT 0,
+        PRIMARY KEY (store_name, index_name)
+      )
+    `);
+  }
+
+  /** @internal */
+  _loadStoreDefinitions(): void {
+    const stores = this._all('SELECT store_name, key_path, auto_increment FROM _idb_stores');
+    for (const row of stores) {
+      const keyPath = row.key_path ? JSON.parse(row.key_path) : null;
+      const opts: IDBObjectStoreParameters = {
+        keyPath,
+        autoIncrement: !!row.auto_increment,
+      };
+      const indexes = new Map<string, any>();
+
+      // Load indexes for this store
+      const idxRows = this._all(
+        'SELECT index_name, key_path, unique_flag, multi_entry FROM _idb_indexes WHERE store_name = ?',
+        [row.store_name]
+      );
+      for (const idx of idxRows) {
+        indexes.set(idx.index_name, {
+          keyPath: JSON.parse(idx.key_path),
+          unique: !!idx.unique_flag,
+          multiEntry: !!idx.multi_entry,
+        });
+      }
+
+      this._objectStores.set(row.store_name, { options: opts, indexes });
+    }
+  }
+
+  /** @internal */
+  _saveStoreMeta(name: string, options: IDBObjectStoreParameters): void {
+    this._exec(
+      `INSERT OR REPLACE INTO _idb_stores (store_name, key_path, auto_increment) VALUES (?, ?, ?)`,
+      [name, JSON.stringify(options.keyPath), options.autoIncrement ? 1 : 0]
+    );
+  }
+
+  /** @internal */
+  _saveIndexMeta(storeName: string, indexName: string, keyPath: string | string[], options: any): void {
+    this._exec(
+      `INSERT OR REPLACE INTO _idb_indexes (store_name, index_name, key_path, unique_flag, multi_entry) VALUES (?, ?, ?, ?, ?)`,
+      [storeName, indexName, JSON.stringify(keyPath), options.unique ? 1 : 0, options.multiEntry ? 1 : 0]
+    );
+    // Update in-memory definition
+    const storeInfo = this._objectStores.get(storeName);
+    if (storeInfo) {
+      storeInfo.indexes.set(indexName, {
+        keyPath,
+        unique: options.unique ?? false,
+        multiEntry: options.multiEntry ?? false,
+      });
+    }
+  }
+
+  /** @internal */
+  _deleteIndexMeta(storeName: string, indexName: string): void {
+    this._exec(
+      `DELETE FROM _idb_indexes WHERE store_name = ? AND index_name = ?`,
+      [storeName, indexName]
+    );
+    const storeInfo = this._objectStores.get(storeName);
+    if (storeInfo) {
+      storeInfo.indexes.delete(indexName);
+    }
+  }
+
+  /** @internal - Get an object store instance for a transaction */
+  _getObjectStore(name: string, transaction: IDBTransaction): IDBObjectStore | null {
+    const storeInfo = this._objectStores.get(name);
+    if (!storeInfo) return null;
+
+    const store = new IDBObjectStore(name, storeInfo.options, transaction, this);
+
+    // Restore indexes
+    for (const [indexName, indexDef] of storeInfo.indexes) {
+      const idx = new IDBIndex(indexName, indexDef.keyPath, indexDef, store);
+      store._indexes.set(indexName, idx);
+    }
+
+    return store;
+  }
+
+  /** @internal */
+  _checkClosed(): void {
+    if (this._closed) {
+      throw new DOMException(
+        'Database connection is closed',
+        'InvalidStateError',
+      );
+    }
+  }
+
+  // ================================================================
+  // SQLite execution wrappers
+  // ================================================================
+
+  /** @internal - Execute a SQL statement */
+  _exec(sql: string, params?: any[]): void {
+    if (this._sqliteDb.exec) {
+      if (params && params.length > 0) {
+        this._sqliteDb.exec(sql, ...params);
+      } else {
+        this._sqliteDb.exec(sql);
+      }
+    } else if (this._sqliteDb.run) {
+      if (params && params.length > 0) {
+        this._sqliteDb.run(sql, ...params);
+      } else {
+        this._sqliteDb.run(sql);
+      }
+    }
+  }
+
+  /** @internal - Query a single row */
+  _get(sql: string, params?: any[]): any {
+    if (this._sqliteDb.query) {
+      const stmt = this._sqliteDb.query(sql);
+      return params ? stmt.get(...params) : stmt.get();
+    }
+    if (this._sqliteDb.prepare) {
+      const stmt = this._sqliteDb.prepare(sql);
+      return params ? stmt.get(...params) : stmt.get();
+    }
+    return null;
+  }
+
+  /** @internal - Query all rows */
+  _all(sql: string, params?: any[]): any[] {
+    if (this._sqliteDb.query) {
+      const stmt = this._sqliteDb.query(sql);
+      return params ? stmt.all(...params) : stmt.all();
+    }
+    if (this._sqliteDb.prepare) {
+      const stmt = this._sqliteDb.prepare(sql);
+      return params ? stmt.all(...params) : stmt.all();
+    }
+    return [];
+  }
+}

package/src/indexeddb/IDBFactory.ts

@@ -0,0 +1,269 @@
+// @ts-nocheck
+/**
+ * IDBFactory - IndexedDB Factory
+ *
+ * The main entry point for IndexedDB. Provides open() and deleteDatabase().
+ * Backed by SQLite via the exact:sqlite module.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/IDBFactory
+ */
+
+import { IDBDatabase } from './IDBDatabase';
+import { IDBOpenDBRequest } from './IDBRequest';
+import { IDBTransaction } from './IDBTransaction';
+import { compareKeys } from './IDBKeyRange';
+import { DOMException } from './utils';
+
+/**
+ * Interface for creating SQLite database instances.
+ * This allows the factory to work with either the real Database class
+ * or a mock for testing.
+ */
+export interface SQLiteDatabaseProvider {
+  create(name: string): any;
+  delete?(name: string): void;
+}
+
+/**
+ * Default provider that uses exact:sqlite Database.
+ */
+class DefaultSQLiteProvider implements SQLiteDatabaseProvider {
+  create(name: string): any {
+    const g = globalThis as any;
+    if (typeof g.__exactSqliteOpen !== 'function' && typeof g.__exactEnsureSqlite === 'function') {
+      g.__exactEnsureSqlite();
+    }
+    if (g.__exactSqliteOpen) {
+      // Import is done lazily to avoid circular dependencies
+      const { Database } = require('../sqlite');
+      return new Database(indexedDbPath(name));
+    }
+    throw new Error(
+      'IndexedDB requires SQLite support. The exact:sqlite native bridge is not available.'
+    );
+  }
+
+  delete(name: string): void {
+    const g = globalThis as any;
+    if (typeof g.__exactUnlink !== 'function' && typeof g.__exactEnsureFs === 'function') {
+      g.__exactEnsureFs();
+    }
+    if (typeof g.__exactUnlink !== 'function') return;
+    for (const path of [indexedDbPath(name), `${indexedDbPath(name)}-wal`, `${indexedDbPath(name)}-shm`]) {
+      try {
+        g.__exactUnlink(path);
+      } catch (_) {}
+    }
+  }
+}
+
+function trimTrailingSlash(path: string): string {
+  return path.replace(/\/+$/, '') || '/';
+}
+
+function indexedDbRoot(): string {
+  const g = globalThis as any;
+  const androidFilesDir = g.__exactAndroidStoragePaths?.filesDir;
+  if (typeof androidFilesDir === 'string' && androidFilesDir.length > 0) {
+    return trimTrailingSlash(androidFilesDir);
+  }
+
+  const env = g.process?.env;
+  const envFilesDir = env?.EXACT_ANDROID_FILES_DIR ?? env?.HOME;
+  if (typeof envFilesDir === 'string' && envFilesDir.length > 0) {
+    return trimTrailingSlash(envFilesDir);
+  }
+
+  return '/tmp';
+}
+
+function ensureIndexedDbDirectory(directory: string): void {
+  const g = globalThis as any;
+  try {
+    if (typeof g.__exactMkdir !== 'function' && typeof g.__exactEnsureFs === 'function') {
+      g.__exactEnsureFs();
+    }
+    if (typeof g.__exactMkdir === 'function') {
+      g.__exactMkdir(directory, true);
+    }
+  } catch (_) {}
+}
+
+function indexedDbPath(name: string): string {
+  // @ref LLP 0008#android-backend-matrix — IndexedDB persists under Android app filesDir.
+  const directory = `${indexedDbRoot()}/.ibex/indexeddb`;
+  ensureIndexedDbDirectory(directory);
+  const encodedName = encodeURIComponent(String(name)) || 'default';
+  return `${directory}/${encodedName}.sqlite`;
+}
+
+function readStoredVersion(sqliteDb: any): number {
+  try {
+    const row = sqliteDb.query('SELECT value FROM _idb_meta WHERE key = ?').get('version');
+    const version = Number(row?.value);
+    return Number.isFinite(version) && version > 0 ? Math.floor(version) : 0;
+  } catch (_) {
+    return 0;
+  }
+}
+
+function writeStoredVersion(sqliteDb: any, version: number): void {
+  try {
+    sqliteDb.run(`
+      CREATE TABLE IF NOT EXISTS _idb_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT
+      )
+    `);
+    sqliteDb.run(
+      'INSERT INTO _idb_meta(key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value',
+      'version',
+      String(version),
+    );
+  } catch (_) {}
+}
+
+export class IDBFactory {
+  /** @internal - Map of database name -> { version, sqliteDb } */
+  private _databases: Map<string, { version: number; sqliteDb: any }> = new Map();
+  /** @internal - SQLite provider for creating database instances */
+  private _sqliteProvider: SQLiteDatabaseProvider;
+
+  constructor(provider?: SQLiteDatabaseProvider) {
+    this._sqliteProvider = provider ?? new DefaultSQLiteProvider();
+  }
+
+  /**
+   * Open (or create) a database with the given name and optional version.
+   *
+   * Returns an IDBOpenDBRequest. Set onupgradeneeded and onsuccess handlers
+   * on the request before the event loop yields.
+   */
+  open(name: string, version?: number): IDBOpenDBRequest<IDBDatabase> {
+    const request = new IDBOpenDBRequest<IDBDatabase>();
+
+    if (
+      version !== undefined &&
+      (version <= 0 || !Number.isFinite(version) || Math.floor(version) !== version)
+    ) {
+      queueMicrotask(() => {
+        request._reject(new TypeError(
+          `The version provided (${version}) is not a valid positive integer.`
+        ));
+      });
+      return request;
+    }
+
+    // Process in a microtask to allow handlers to be attached
+    queueMicrotask(() => {
+      try {
+        const existing = this._databases.get(name);
+
+        let sqliteDb: any;
+        let oldVersion = 0;
+        if (existing) {
+          sqliteDb = existing.sqliteDb;
+          oldVersion = existing.version;
+        } else {
+          sqliteDb = this._sqliteProvider.create(name);
+          oldVersion = readStoredVersion(sqliteDb);
+        }
+        const resolvedVersion = version ?? (oldVersion > 0 ? oldVersion : 1);
+        if (oldVersion > 0 && resolvedVersion < oldVersion) {
+          throw new DOMException(
+            `The requested version (${resolvedVersion}) is less than the existing version (${oldVersion}).`,
+            'VersionError',
+          );
+        }
+
+        const db = new IDBDatabase(name, resolvedVersion, sqliteDb);
+
+        // Set the result on the request before upgradeneeded fires,
+        // because onupgradeneeded handlers access event.target.result
+        // to get a reference to the database.
+        request._setResult(db);
+
+        // Version upgrade needed?
+        if (resolvedVersion > oldVersion) {
+          // Create an upgrade transaction so createObjectStore/deleteObjectStore
+          // can detect that they are being called during upgradeneeded.
+          const storeNames = Array.from((db as any)._objectStores?.keys?.() ?? []);
+          const upgradeTxn = new IDBTransaction(db, storeNames, 'versionchange');
+          db._upgradeTransaction = upgradeTxn;
+
+          // Fire onupgradeneeded synchronously
+          if (request.onupgradeneeded) {
+            const event = {
+              type: 'upgradeneeded',
+              target: request,
+              oldVersion,
+              newVersion: resolvedVersion,
+            };
+            // During upgradeneeded, the database is in a special state
+            // where createObjectStore/deleteObjectStore can be called
+            request.onupgradeneeded(event);
+          }
+
+          // Clear the upgrade transaction after upgradeneeded completes
+          db._upgradeTransaction = null;
+        }
+
+        // Store the database reference
+        this._databases.set(name, { version: resolvedVersion, sqliteDb });
+        writeStoredVersion(sqliteDb, resolvedVersion);
+
+        // Fire onsuccess
+        request._resolveSync(db);
+      } catch (e: any) {
+        request._reject(e);
+      }
+    });
+
+    return request;
+  }
+
+  /**
+   * Delete a database.
+   */
+  deleteDatabase(name: string): IDBOpenDBRequest<undefined> {
+    const request = new IDBOpenDBRequest<undefined>();
+
+    queueMicrotask(() => {
+      try {
+        const existing = this._databases.get(name);
+        if (existing) {
+          // Close the SQLite database
+          if (existing.sqliteDb && existing.sqliteDb.close) {
+            existing.sqliteDb.close();
+          }
+          this._databases.delete(name);
+        }
+        this._sqliteProvider.delete?.(name);
+        request._resolveSync(undefined);
+      } catch (e: any) {
+        request._reject(e);
+      }
+    });
+
+    return request;
+  }
+
+  /**
+   * Compare two keys using IndexedDB key comparison rules.
+   */
+  cmp(first: any, second: any): number {
+    const result = compareKeys(first, second);
+    return result < 0 ? -1 : result > 0 ? 1 : 0;
+  }
+
+  /**
+   * List all databases. Returns a promise.
+   */
+  databases(): Promise<Array<{ name: string; version: number }>> {
+    const result = Array.from(this._databases.entries()).map(([name, info]) => ({
+      name,
+      version: info.version,
+    }));
+    return Promise.resolve(result);
+  }
+}