@trestleinc/replicate 1.1.0 → 1.1.2-preview.0

package/src/client/persistence/adapters/sqljs.ts

@@ -1,128 +0,0 @@
-/**
- * sql.js adapter wrapper for browser SQLite.
- *
- * The consuming app imports sql.js and creates the database,
- * then passes it to this wrapper.
- *
- * @example
- * ```typescript
- * import initSqlJs from 'sql.js';
- * import { SqlJsAdapter } from '@trestleinc/replicate/client';
- *
- * const SQL = await initSqlJs({ locateFile: f => `/wasm/${f}` });
- * const db = new SQL.Database();
- * const adapter = new SqlJsAdapter(db, {
- *   onPersist: async (data) => {
- *     // Persist to OPFS, localStorage, etc.
- *   }
- * });
- * ```
- */
-import type { SqliteAdapter } from '../sqlite-level.js';
-
-/**
- * Interface for sql.js Database.
- * Consumer must install sql.js and pass a Database instance.
- */
-export interface SqlJsDatabase {
-  run(sql: string, params?: unknown[]): void;
-  prepare(sql: string): {
-    bind(params?: unknown[]): void;
-    step(): boolean;
-    getAsObject(): Record<string, unknown>;
-    free(): void;
-  };
-  export(): Uint8Array;
-  close(): void;
-}
-
-/**
- * Options for the SqlJsAdapter.
- */
-export interface SqlJsAdapterOptions {
-  /**
-   * Callback to persist database after write operations.
-   * Called with the exported database bytes.
-   *
-   * @example OPFS persistence
-   * ```typescript
-   * onPersist: async (data) => {
-   *   const root = await navigator.storage.getDirectory();
-   *   const handle = await root.getFileHandle('myapp.sqlite', { create: true });
-   *   const writable = await handle.createWritable();
-   *   await writable.write(data.buffer);
-   *   await writable.close();
-   * }
-   * ```
-   */
-  onPersist?: (data: Uint8Array) => Promise<void>;
-}
-
-/**
- * Wraps a sql.js Database as a SqliteAdapter.
- *
- * @example
- * ```typescript
- * import initSqlJs from 'sql.js';
- * import { SqlJsAdapter } from '@trestleinc/replicate/client';
- *
- * const SQL = await initSqlJs();
- * const db = new SQL.Database();
- * const adapter = new SqlJsAdapter(db);
- * ```
- */
-export class SqlJsAdapter implements SqliteAdapter {
-  private db: SqlJsDatabase;
-  private onPersist?: (data: Uint8Array) => Promise<void>;
-
-  constructor(db: SqlJsDatabase, options: SqlJsAdapterOptions = {}) {
-    this.db = db;
-    this.onPersist = options.onPersist;
-  }
-
-  async execute(sql: string, params?: unknown[]): Promise<{ rows: Record<string, unknown>[] }> {
-    const rows: Record<string, unknown>[] = [];
-
-    // Handle statements that don't return data
-    if (
-      sql.trim().toUpperCase().startsWith('CREATE') ||
-      sql.trim().toUpperCase().startsWith('INSERT') ||
-      sql.trim().toUpperCase().startsWith('UPDATE') ||
-      sql.trim().toUpperCase().startsWith('DELETE') ||
-      sql.trim().toUpperCase().startsWith('BEGIN') ||
-      sql.trim().toUpperCase().startsWith('COMMIT') ||
-      sql.trim().toUpperCase().startsWith('ROLLBACK')
-    ) {
-      this.db.run(sql, params);
-      await this.persist();
-      return { rows };
-    }
-
-    // Handle SELECT statements
-    const stmt = this.db.prepare(sql);
-    if (params && params.length > 0) {
-      stmt.bind(params);
-    }
-
-    while (stmt.step()) {
-      rows.push(stmt.getAsObject());
-    }
-    stmt.free();
-
-    return { rows };
-  }
-
-  close(): void {
-    this.db.close();
-  }
-
-  /**
-   * Persist database using the onPersist callback if provided.
-   */
-  private async persist(): Promise<void> {
-    if (this.onPersist) {
-      const data = this.db.export();
-      await this.onPersist(new Uint8Array(data));
-    }
-  }
-}

package/src/client/persistence/sqlite-browser.ts

@@ -1,107 +0,0 @@
-/**
- * Browser SQLite persistence helper using sql.js and OPFS.
- *
- * Handles all the boilerplate for browser SQLite:
- * - Loading existing database from OPFS
- * - Persisting to OPFS on every write
- * - Creating the SqlJsAdapter
- *
- * @example
- * ```typescript
- * import { createBrowserSqlitePersistence } from '@trestleinc/replicate/client';
- * import initSqlJs from 'sql.js';
- *
- * const SQL = await initSqlJs({ locateFile: f => `https://sql.js.org/dist/${f}` });
- * const persistence = await createBrowserSqlitePersistence(SQL, 'myapp');
- * ```
- */
-import { SqlJsAdapter, type SqlJsDatabase } from './adapters/sqljs.js';
-import { sqlitePersistence } from './sqlite.js';
-import type { Persistence } from './types.js';
-
-/**
- * Interface for the sql.js module (the result of initSqlJs).
- */
-export interface SqlJsStatic {
-  Database: new (data?: ArrayLike<number>) => SqlJsDatabase;
-}
-
-/**
- * Load existing database from OPFS if available.
- */
-async function loadFromOPFS(dbName: string): Promise<Uint8Array | null> {
-  try {
-    const root = await navigator.storage.getDirectory();
-    const handle = await root.getFileHandle(`${dbName}.sqlite`);
-    const file = await handle.getFile();
-    const buffer = await file.arrayBuffer();
-    return new Uint8Array(buffer);
-  } catch {
-    // File doesn't exist yet
-    return null;
-  }
-}
-
-/**
- * Save database to OPFS for durable storage.
- */
-function createOPFSSaver(dbName: string): (data: Uint8Array) => Promise<void> {
-  return async (data: Uint8Array): Promise<void> => {
-    try {
-      const root = await navigator.storage.getDirectory();
-      const handle = await root.getFileHandle(`${dbName}.sqlite`, { create: true });
-      const writable = await handle.createWritable();
-      // Copy to a new ArrayBuffer to satisfy TypeScript's strict ArrayBuffer type
-      const buffer = new ArrayBuffer(data.length);
-      new Uint8Array(buffer).set(data);
-      await writable.write(buffer);
-      await writable.close();
-    } catch {
-      // Silently fail - OPFS may not be available
-    }
-  };
-}
-
-/**
- * Create browser SQLite persistence with OPFS storage.
- *
- * This helper handles all the OPFS boilerplate:
- * - Loads existing database from OPFS on init
- * - Persists to OPFS after every write operation
- *
- * @param SQL - The initialized sql.js module (from `await initSqlJs()`)
- * @param dbName - Name for the database (used for OPFS filename: `{dbName}.sqlite`)
- *
- * @example
- * ```typescript
- * import { createBrowserSqlitePersistence } from '@trestleinc/replicate/client';
- * import initSqlJs from 'sql.js';
- *
- * const SQL = await initSqlJs({ locateFile: f => `https://sql.js.org/dist/${f}` });
- * const persistence = await createBrowserSqlitePersistence(SQL, 'intervals');
- *
- * // Use in collection options
- * convexCollectionOptions<Task>({
- *   // ...
- *   persistence,
- * });
- * ```
- */
-export async function createBrowserSqlitePersistence(
-  SQL: SqlJsStatic,
-  dbName: string
-): Promise<Persistence> {
-  // Load existing database from OPFS if available
-  const existingData = await loadFromOPFS(dbName);
-
-  // Create database (with existing data if found)
-  const db = existingData ? new SQL.Database(existingData) : new SQL.Database();
-
-  // Create adapter with OPFS persistence
-  const adapter = new SqlJsAdapter(db, {
-    onPersist: createOPFSSaver(dbName),
-  });
-
-  // Create and return persistence
-  return sqlitePersistence({ adapter, dbName });
-}

package/src/client/persistence/sqlite-level.ts

@@ -1,407 +0,0 @@
-/**
- * SQLite-backed abstract-level implementation.
- *
- * Provides a LevelDB-compatible key-value store backed by SQLite,
- * enabling y-leveldb to work with SQLite databases.
- *
- * Supports both browser (sql.js WASM) and React Native (op-sqlite).
- */
-import {
-  AbstractLevel,
-  AbstractIterator,
-  AbstractKeyIterator,
-  AbstractValueIterator,
-} from 'abstract-level';
-
-/**
- * Interface for SQLite database operations.
- * Abstracts over sql.js (browser) and op-sqlite (React Native).
- */
-export interface SqliteAdapter {
-  execute(sql: string, params?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
-  close(): void;
-}
-
-interface SqliteLevelOptions {
-  /** Custom SQLite adapter (for testing or alternative backends) */
-  adapter?: SqliteAdapter;
-  /** Value encoding (default: 'utf8') */
-  valueEncoding?: string;
-  keyEncoding?: string;
-}
-
-/**
- * SQLite-backed implementation of abstract-level.
- *
- * Uses a simple key-value table with lexicographic ordering:
- * CREATE TABLE entries (key BLOB PRIMARY KEY, value BLOB)
- */
-export class SqliteLevel<K = string, V = string> extends AbstractLevel<K, V> {
-  private adapter: SqliteAdapter | null = null;
-  private adapterFactory: (() => Promise<SqliteAdapter>) | null = null;
-
-  constructor(_location: string, options?: SqliteLevelOptions) {
-    super(
-      {
-        encodings: { utf8: true, buffer: true, view: true },
-        seek: true,
-        permanence: true,
-        createIfMissing: true,
-        errorIfExists: false,
-        additionalMethods: {},
-      },
-      {
-        keyEncoding: options?.keyEncoding ?? 'utf8',
-        valueEncoding: options?.valueEncoding ?? 'utf8',
-      }
-    );
-
-    if (options?.adapter) {
-      this.adapter = options.adapter;
-    }
-  }
-
-  /**
-   * Set the adapter factory for deferred initialization.
-   * Call this before open() to configure the SQLite backend.
-   */
-  setAdapterFactory(factory: () => Promise<SqliteAdapter>): void {
-    this.adapterFactory = factory;
-  }
-
-  async _open(): Promise<void> {
-    if (!this.adapter) {
-      if (this.adapterFactory) {
-        this.adapter = await this.adapterFactory();
-      } else {
-        throw new Error('No SQLite adapter configured. Call setAdapterFactory() before open().');
-      }
-    }
-
-    // Create the entries table if it doesn't exist
-    await this.adapter.execute(`
-      CREATE TABLE IF NOT EXISTS entries (
-        key BLOB PRIMARY KEY,
-        value BLOB NOT NULL
-      )
-    `);
-
-    // Create index for range queries (lexicographic ordering)
-    await this.adapter.execute(`
-      CREATE INDEX IF NOT EXISTS entries_key_idx ON entries (key)
-    `);
-  }
-
-  async _close(): Promise<void> {
-    if (this.adapter) {
-      this.adapter.close();
-      this.adapter = null;
-    }
-  }
-
-  async _get(key: K): Promise<V | undefined> {
-    if (!this.adapter) throw new Error('Database not open');
-
-    const keyBytes = this.encodeKey(key);
-    const result = await this.adapter.execute('SELECT value FROM entries WHERE key = ?', [
-      keyBytes,
-    ]);
-
-    if (result.rows.length === 0) {
-      return undefined;
-    }
-
-    return this.decodeValue(result.rows[0].value as Uint8Array);
-  }
-
-  async _put(key: K, value: V): Promise<void> {
-    if (!this.adapter) throw new Error('Database not open');
-
-    const keyBytes = this.encodeKey(key);
-    const valueBytes = this.encodeValue(value);
-
-    await this.adapter.execute('INSERT OR REPLACE INTO entries (key, value) VALUES (?, ?)', [
-      keyBytes,
-      valueBytes,
-    ]);
-  }
-
-  async _del(key: K): Promise<void> {
-    if (!this.adapter) throw new Error('Database not open');
-
-    const keyBytes = this.encodeKey(key);
-    await this.adapter.execute('DELETE FROM entries WHERE key = ?', [keyBytes]);
-  }
-
-  async _batch(
-    operations: Array<{ type: 'put'; key: K; value: V } | { type: 'del'; key: K }>
-  ): Promise<void> {
-    if (!this.adapter) throw new Error('Database not open');
-
-    // Execute all operations in a transaction
-    await this.adapter.execute('BEGIN TRANSACTION');
-
-    try {
-      for (const op of operations) {
-        if (op.type === 'put') {
-          const keyBytes = this.encodeKey(op.key);
-          const valueBytes = this.encodeValue(op.value);
-          await this.adapter.execute('INSERT OR REPLACE INTO entries (key, value) VALUES (?, ?)', [
-            keyBytes,
-            valueBytes,
-          ]);
-        } else if (op.type === 'del') {
-          const keyBytes = this.encodeKey(op.key);
-          await this.adapter.execute('DELETE FROM entries WHERE key = ?', [keyBytes]);
-        }
-      }
-      await this.adapter.execute('COMMIT');
-    } catch (error) {
-      await this.adapter.execute('ROLLBACK');
-      throw error;
-    }
-  }
-
-  async _clear(): Promise<void> {
-    if (!this.adapter) throw new Error('Database not open');
-    await this.adapter.execute('DELETE FROM entries');
-  }
-
-  _iterator(options: Record<string, unknown>): AbstractIterator<typeof this, K, V> {
-    if (!this.adapter) throw new Error('Database not open');
-    return new SqliteIterator(this, this.adapter, options) as unknown as AbstractIterator<
-      typeof this,
-      K,
-      V
-    >;
-  }
-
-  _keys(options: Record<string, unknown>): AbstractKeyIterator<typeof this, K> {
-    if (!this.adapter) throw new Error('Database not open');
-    return new SqliteKeyIterator(this, this.adapter, options) as unknown as AbstractKeyIterator<
-      typeof this,
-      K
-    >;
-  }
-
-  _values(options: Record<string, unknown>): AbstractValueIterator<typeof this, K, V> {
-    if (!this.adapter) throw new Error('Database not open');
-    return new SqliteValueIterator(this, this.adapter, options) as unknown as AbstractValueIterator<
-      typeof this,
-      K,
-      V
-    >;
-  }
-
-  // Helper methods for encoding/decoding
-  private encodeKey(key: K): Uint8Array {
-    if (key instanceof Uint8Array) {
-      return key;
-    }
-    if (typeof key === 'string') {
-      return new TextEncoder().encode(key);
-    }
-    return new TextEncoder().encode(String(key));
-  }
-
-  private encodeValue(value: V): Uint8Array {
-    if (value instanceof Uint8Array) {
-      return value;
-    }
-    if (typeof value === 'string') {
-      return new TextEncoder().encode(value);
-    }
-    return new TextEncoder().encode(JSON.stringify(value));
-  }
-
-  private decodeValue(bytes: Uint8Array): V {
-    return new TextDecoder().decode(bytes) as V;
-  }
-}
-
-/**
- * Iterator for key-value pairs.
- */
-class SqliteIterator<K, V> extends AbstractIterator<SqliteLevel<K, V>, K, V> {
-  private adapter: SqliteAdapter;
-  private options: Record<string, unknown>;
-  private rows: Array<{ key: Uint8Array; value: Uint8Array }> | null = null;
-  private index = 0;
-
-  constructor(db: SqliteLevel<K, V>, adapter: SqliteAdapter, options: Record<string, unknown>) {
-    super(db, options);
-    this.adapter = adapter;
-    this.options = options;
-  }
-
-  async _next(): Promise<[K, V] | undefined> {
-    if (this.rows === null) {
-      await this.loadRows();
-    }
-
-    if (this.rows && this.index < this.rows.length) {
-      const row = this.rows[this.index++];
-      const key = new TextDecoder().decode(row.key) as K;
-      const value = new TextDecoder().decode(row.value) as V;
-      return [key, value];
-    }
-
-    return undefined;
-  }
-
-  async _nextv(size: number): Promise<Array<[K, V]>> {
-    if (this.rows === null) {
-      await this.loadRows();
-    }
-
-    const result: Array<[K, V]> = [];
-    while (this.rows && this.index < this.rows.length && result.length < size) {
-      const row = this.rows[this.index++];
-      const key = new TextDecoder().decode(row.key) as K;
-      const value = new TextDecoder().decode(row.value) as V;
-      result.push([key, value]);
-    }
-    return result;
-  }
-
-  private async loadRows(): Promise<void> {
-    const { reverse, limit, gt, gte, lt, lte } = this.options as {
-      reverse?: boolean;
-      limit?: number;
-      gt?: K;
-      gte?: K;
-      lt?: K;
-      lte?: K;
-    };
-
-    let sql = 'SELECT key, value FROM entries';
-    const params: unknown[] = [];
-    const conditions: string[] = [];
-
-    if (gt !== undefined) {
-      conditions.push('key > ?');
-      params.push(this.encodeKey(gt));
-    }
-    if (gte !== undefined) {
-      conditions.push('key >= ?');
-      params.push(this.encodeKey(gte));
-    }
-    if (lt !== undefined) {
-      conditions.push('key < ?');
-      params.push(this.encodeKey(lt));
-    }
-    if (lte !== undefined) {
-      conditions.push('key <= ?');
-      params.push(this.encodeKey(lte));
-    }
-
-    if (conditions.length > 0) {
-      sql += ` WHERE ${conditions.join(' AND ')}`;
-    }
-
-    sql += ` ORDER BY key ${reverse ? 'DESC' : 'ASC'}`;
-
-    if (limit !== undefined && limit >= 0) {
-      sql += ` LIMIT ${limit}`;
-    }
-
-    const result = await this.adapter.execute(sql, params);
-    this.rows = result.rows as Array<{ key: Uint8Array; value: Uint8Array }>;
-  }
-
-  private encodeKey(key: K): Uint8Array {
-    if (key instanceof Uint8Array) {
-      return key;
-    }
-    if (typeof key === 'string') {
-      return new TextEncoder().encode(key);
-    }
-    return new TextEncoder().encode(String(key));
-  }
-}
-
-/**
- * Iterator for keys only.
- */
-class SqliteKeyIterator<K, V> extends AbstractKeyIterator<SqliteLevel<K, V>, K> {
-  private adapter: SqliteAdapter;
-  private options: Record<string, unknown>;
-  private rows: Array<{ key: Uint8Array }> | null = null;
-  private index = 0;
-
-  constructor(db: SqliteLevel<K, V>, adapter: SqliteAdapter, options: Record<string, unknown>) {
-    super(db, options);
-    this.adapter = adapter;
-    this.options = options;
-  }
-
-  async _next(): Promise<K | undefined> {
-    if (this.rows === null) {
-      await this.loadRows();
-    }
-
-    if (this.rows && this.index < this.rows.length) {
-      const row = this.rows[this.index++];
-      return new TextDecoder().decode(row.key) as K;
-    }
-
-    return undefined;
-  }
-
-  private async loadRows(): Promise<void> {
-    const { reverse, limit } = this.options as { reverse?: boolean; limit?: number };
-
-    let sql = 'SELECT key FROM entries';
-    sql += ` ORDER BY key ${reverse ? 'DESC' : 'ASC'}`;
-
-    if (limit !== undefined && limit >= 0) {
-      sql += ` LIMIT ${limit}`;
-    }
-
-    const result = await this.adapter.execute(sql);
-    this.rows = result.rows as Array<{ key: Uint8Array }>;
-  }
-}
-
-/**
- * Iterator for values only.
- */
-class SqliteValueIterator<K, V> extends AbstractValueIterator<SqliteLevel<K, V>, K, V> {
-  private adapter: SqliteAdapter;
-  private options: Record<string, unknown>;
-  private rows: Array<{ value: Uint8Array }> | null = null;
-  private index = 0;
-
-  constructor(db: SqliteLevel<K, V>, adapter: SqliteAdapter, options: Record<string, unknown>) {
-    super(db, options);
-    this.adapter = adapter;
-    this.options = options;
-  }
-
-  async _next(): Promise<V | undefined> {
-    if (this.rows === null) {
-      await this.loadRows();
-    }
-
-    if (this.rows && this.index < this.rows.length) {
-      const row = this.rows[this.index++];
-      return new TextDecoder().decode(row.value) as V;
-    }
-
-    return undefined;
-  }
-
-  private async loadRows(): Promise<void> {
-    const { reverse, limit } = this.options as { reverse?: boolean; limit?: number };
-
-    let sql = 'SELECT value FROM entries';
-    sql += ` ORDER BY key ${reverse ? 'DESC' : 'ASC'}`;
-
-    if (limit !== undefined && limit >= 0) {
-      sql += ` LIMIT ${limit}`;
-    }
-
-    const result = await this.adapter.execute(sql);
-    this.rows = result.rows as Array<{ value: Uint8Array }>;
-  }
-}

package/src/client/persistence/sqlite-rn.ts

@@ -1,44 +0,0 @@
-/**
- * React Native SQLite persistence helper using op-sqlite.
- *
- * @example
- * ```typescript
- * import { createReactNativeSqlitePersistence } from '@trestleinc/replicate/client';
- * import { open } from '@op-engineering/op-sqlite';
- *
- * const db = open({ name: 'myapp.db' });
- * const persistence = await createReactNativeSqlitePersistence(db, 'myapp');
- * ```
- */
-import { OPSqliteAdapter, type OPSQLiteDatabase } from './adapters/opsqlite.js';
-import { sqlitePersistence } from './sqlite.js';
-import type { Persistence } from './types.js';
-
-/**
- * Create React Native SQLite persistence using op-sqlite.
- *
- * @param db - The opened op-sqlite database instance
- * @param dbName - Name for internal database identification
- *
- * @example
- * ```typescript
- * import { createReactNativeSqlitePersistence } from '@trestleinc/replicate/client';
- * import { open } from '@op-engineering/op-sqlite';
- *
- * const db = open({ name: 'myapp.db' });
- * const persistence = await createReactNativeSqlitePersistence(db, 'myapp');
- *
- * // Use in collection options
- * convexCollectionOptions<Task>({
- *   // ...
- *   persistence,
- * });
- * ```
- */
-export async function createReactNativeSqlitePersistence(
-  db: OPSQLiteDatabase,
-  dbName: string
-): Promise<Persistence> {
-  const adapter = new OPSqliteAdapter(db);
-  return sqlitePersistence({ adapter, dbName });
-}