@trestleinc/replicate 0.1.0 → 1.1.0

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

@@ -0,0 +1,128 @@
+/**
+ * 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/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Persistence layer exports.
+ *
+ * Provides swappable storage backends for Y.Doc and key-value data.
+ */
+export type { Persistence, PersistenceProvider, KeyValueStore } from './types.js';
+export type { SqlitePersistenceOptions } from './sqlite.js';
+export type { SqlJsStatic } from './sqlite-browser.js';
+export type { SqliteAdapter } from './sqlite-level.js';
+
+// Internal imports for the persistence object
+import { indexeddbPersistence } from './indexeddb.js';
+import { memoryPersistence } from './memory.js';
+import { sqlitePersistence } from './sqlite.js';
+import { createBrowserSqlitePersistence } from './sqlite-browser.js';
+import { createReactNativeSqlitePersistence } from './sqlite-rn.js';
+
+/**
+ * Persistence API - nested object pattern for ergonomic access.
+ *
+ * @example
+ * ```typescript
+ * import { persistence } from '@trestleinc/replicate/client';
+ *
+ * // Browser SQLite (recommended for web)
+ * const p = await persistence.sqlite.browser(SQL, 'myapp');
+ *
+ * // React Native SQLite
+ * const p = await persistence.sqlite.native(db, 'myapp');
+ *
+ * // IndexedDB fallback
+ * const p = persistence.indexeddb('myapp');
+ *
+ * // In-memory (testing)
+ * const p = persistence.memory();
+ * ```
+ */
+export const persistence = {
+  /** IndexedDB-backed persistence (browser) */
+  indexeddb: indexeddbPersistence,
+
+  /** In-memory persistence (testing/ephemeral) */
+  memory: memoryPersistence,
+
+  /** SQLite persistence variants */
+  sqlite: {
+    /** Browser SQLite with OPFS (sql.js) */
+    browser: createBrowserSqlitePersistence,
+    /** React Native SQLite (op-sqlite) */
+    native: createReactNativeSqlitePersistence,
+    /** Custom SQLite adapter */
+    create: sqlitePersistence,
+  },
+} as const;

package/src/client/persistence/indexeddb.ts

@@ -0,0 +1,110 @@
+/**
+ * IndexedDB persistence implementation for browser environments.
+ *
+ * Uses y-indexeddb for Y.Doc persistence and browser-level for key-value storage.
+ * browser-level is an abstract-level database backed by IndexedDB.
+ */
+import type * as Y from 'yjs';
+import { IndexeddbPersistence } from 'y-indexeddb';
+import { BrowserLevel } from 'browser-level';
+import type { Persistence, PersistenceProvider, KeyValueStore } from './types.js';
+
+/**
+ * browser-level backed key-value store.
+ *
+ * Uses the Level ecosystem for consistent API across browser and React Native.
+ */
+class BrowserLevelKeyValueStore implements KeyValueStore {
+  private db: BrowserLevel<string, string>;
+
+  constructor(dbName: string) {
+    this.db = new BrowserLevel(dbName);
+  }
+
+  async get<T>(key: string): Promise<T | undefined> {
+    try {
+      const value = await this.db.get(key);
+      if (value === undefined) {
+        return undefined;
+      }
+      return JSON.parse(value) as T;
+    } catch (err: any) {
+      // Level throws LEVEL_NOT_FOUND error for missing keys
+      if (err.code === 'LEVEL_NOT_FOUND') {
+        return undefined;
+      }
+      throw err;
+    }
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    await this.db.put(key, JSON.stringify(value));
+  }
+
+  async del(key: string): Promise<void> {
+    try {
+      await this.db.del(key);
+    } catch (err: any) {
+      // Ignore not found errors on delete
+      if (err.code !== 'LEVEL_NOT_FOUND') {
+        throw err;
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.db.close();
+  }
+}
+
+/**
+ * IndexedDB persistence provider wrapping y-indexeddb.
+ */
+class IndexedDBPersistenceProvider implements PersistenceProvider {
+  private persistence: IndexeddbPersistence;
+  readonly whenSynced: Promise<void>;
+
+  constructor(collection: string, ydoc: Y.Doc) {
+    this.persistence = new IndexeddbPersistence(collection, ydoc);
+
+    // Handle race: check synced state before attaching listener
+    // If database is empty or fast, synced event may fire before we attach
+    this.whenSynced = new Promise((resolve) => {
+      if (this.persistence.synced) {
+        // Already synced - resolve immediately
+        resolve();
+      } else {
+        // Not yet synced - wait for event (use once to prevent listener accumulation)
+        this.persistence.once('synced', () => resolve());
+      }
+    });
+  }
+
+  destroy(): void {
+    this.persistence.destroy();
+  }
+}
+
+/**
+ * Create an IndexedDB persistence factory.
+ *
+ * Uses y-indexeddb for Y.Doc persistence and browser-level for metadata storage.
+ *
+ * @param dbName - Name for the LevelDB database (default: 'replicate-kv')
+ *
+ * @example
+ * ```typescript
+ * convexCollectionOptions<Task>({
+ *   // ... other options
+ *   persistence: indexeddbPersistence(),
+ * });
+ * ```
+ */
+export function indexeddbPersistence(dbName = 'replicate-kv'): Persistence {
+  const kv = new BrowserLevelKeyValueStore(dbName);
+  return {
+    createDocPersistence: (collection: string, ydoc: Y.Doc) =>
+      new IndexedDBPersistenceProvider(collection, ydoc),
+    kv,
+  };
+}

package/src/client/persistence/memory.ts

@@ -0,0 +1,61 @@
+/**
+ * In-memory persistence implementation for testing.
+ *
+ * State is not persisted across sessions - useful for tests and development.
+ */
+import type * as Y from 'yjs';
+import type { Persistence, PersistenceProvider, KeyValueStore } from './types.js';
+
+/**
+ * In-memory key-value store.
+ */
+class MemoryKeyValueStore implements KeyValueStore {
+  private store = new Map<string, unknown>();
+
+  async get<T>(key: string): Promise<T | undefined> {
+    return this.store.get(key) as T | undefined;
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    this.store.set(key, value);
+  }
+
+  async del(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+}
+
+/**
+ * No-op persistence provider for in-memory usage.
+ *
+ * The Y.Doc is kept in memory without persistence.
+ */
+class MemoryPersistenceProvider implements PersistenceProvider {
+  readonly whenSynced = Promise.resolve();
+
+  destroy(): void {
+    // No resources to clean up
+  }
+}
+
+/**
+ * Create an in-memory persistence factory.
+ *
+ * Useful for testing where you don't want IndexedDB side effects.
+ *
+ * @example
+ * ```typescript
+ * // In tests
+ * convexCollectionOptions<Task>({
+ *   // ... other options
+ *   persistence: memoryPersistence(),
+ * });
+ * ```
+ */
+export function memoryPersistence(): Persistence {
+  const kv = new MemoryKeyValueStore();
+  return {
+    createDocPersistence: (_collection: string, _ydoc: Y.Doc) => new MemoryPersistenceProvider(),
+    kv,
+  };
+}

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

@@ -0,0 +1,107 @@
+/**
+ * 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 });
+}