@trestleinc/replicate 0.1.0 → 1.1.0

package/dist/client/collection.d.ts

@@ -1,94 +1,96 @@
+import * as Y from 'yjs';
+import type { Persistence } from '$/client/persistence/types.js';
 import type { ConvexClient } from 'convex/browser';
 import type { FunctionReference } from 'convex/server';
 import type { CollectionConfig, Collection } from '@tanstack/db';
-/**
- * Configuration for convexCollectionOptions (Step 1)
- * All params go here - they'll be used to create the collection config
- */
+import type { ProseFields } from '$/shared/types.js';
+/** Server-rendered material data for SSR hydration */
+export type Materialized<T> = {
+    documents: ReadonlyArray<T>;
+    checkpoint?: {
+        lastModified: number;
+    };
+    count?: number;
+    crdtBytes?: ArrayBuffer;
+};
+/** Configuration for creating a Convex-backed collection */
 export interface ConvexCollectionOptionsConfig<T extends object> {
-    /** Function to extract unique key from items */
     getKey: (item: T) => string | number;
-    /** Optional initial data to populate collection */
-    initialData?: ReadonlyArray<T>;
-    /** Convex client instance */
+    material?: Materialized<T>;
     convexClient: ConvexClient;
-    /** Convex API functions for this collection */
     api: {
         stream: FunctionReference<'query'>;
-        insertDocument: FunctionReference<'mutation'>;
-        updateDocument: FunctionReference<'mutation'>;
-        deleteDocument: FunctionReference<'mutation'>;
+        insert: FunctionReference<'mutation'>;
+        update: FunctionReference<'mutation'>;
+        remove: FunctionReference<'mutation'>;
+        recovery: FunctionReference<'query'>;
+        material?: FunctionReference<'query'>;
+        [key: string]: any;
     };
-    /** Unique collection name */
-    collectionName: string;
+    collection: string;
+    /** Fields that contain prose (rich text) content stored as Y.XmlFragment */
+    prose: Array<ProseFields<T>>;
+    /** Undo capture timeout in ms. Changes within this window merge into one undo. Default: 500 */
+    undoCaptureTimeout?: number;
+    /** Persistence provider for Y.Doc and key-value storage */
+    persistence: Persistence;
+}
+/** Editor binding for BlockNote/TipTap collaboration */
+export interface EditorBinding {
+    /** The Y.XmlFragment bound to the editor */
+    readonly fragment: Y.XmlFragment;
+    /** Provider stub for BlockNote compatibility */
+    readonly provider: {
+        readonly awareness: null;
+    };
+    /** Current sync state - true if unsent changes exist */
+    readonly pending: boolean;
+    /** Subscribe to pending state changes. Returns unsubscribe function. */
+    onPendingChange(callback: (pending: boolean) => void): () => void;
+    /** Undo the last content edit */
+    undo(): void;
+    /** Redo the last undone edit */
+    redo(): void;
+    /** Check if undo is available */
+    canUndo(): boolean;
+    /** Check if redo is available */
+    canRedo(): boolean;
+}
+/** Utilities exposed on collection.utils */
+interface ConvexCollectionUtils<T extends object> {
+    /**
+     * Get an editor binding for a prose field.
+     * Waits for Y.Doc to be ready (IndexedDB loaded) before returning.
+     * @param documentId - The document ID
+     * @param field - The prose field name (must be in `prose` config)
+     * @returns Promise resolving to EditorBinding
+     */
+    prose(documentId: string, field: ProseFields<T>): Promise<EditorBinding>;
+}
+/** Extended collection with prose field utilities */
+export interface ConvexCollection<T extends object> extends Collection<T> {
+    /** Utilities for prose field operations */
+    utils: ConvexCollectionUtils<T>;
 }
 /**
- * ConvexCollection is now just a standard TanStack DB Collection!
- * No custom wrapper, no special methods - uses built-in transaction system.
- */
-export type ConvexCollection<T extends object> = Collection<T>;
-/**
- * Step 1: Create TanStack DB CollectionConfig with REAL mutation handlers.
- *
- * This implements the CORRECT pattern:
- * - Uses onInsert/onUpdate/onDelete handlers (not custom wrapper)
- * - Yjs Y.Doc with 'update' event for delta encoding
- * - Stores Y.Map instances (not plain objects) for field-level CRDT
- * - Uses ydoc.transact() to batch changes into single 'update' event
+ * Create TanStack DB collection options with Convex + Yjs replication.
  *
  * @example
  * ```typescript
- * import { createCollection } from '@tanstack/react-db'
- * import { convexCollectionOptions } from '@trestleinc/convex-replicate-core'
- *
- * const rawCollection = createCollection(
- *   convexCollectionOptions<Task>({
- *     convexClient,
- *     api: api.tasks,
- *     collectionName: 'tasks',
- *     getKey: (task) => task.id,
- *     initialData,
- *   })
- * )
+ * const options = convexCollectionOptions<Task>({
+ *   getKey: (t) => t.id,
+ *   convexClient,
+ *   api: { stream: api.tasks.stream, insert: api.tasks.insert, ... },
+ *   collection: 'tasks',
+ * });
+ * const collection = createCollection(options);
  * ```
  */
-export declare function convexCollectionOptions<T extends object>({ getKey, initialData, convexClient, api, collectionName, }: ConvexCollectionOptionsConfig<T>): CollectionConfig<T> & {
+export declare function convexCollectionOptions<T extends object>({ getKey, material, convexClient, api, collection, prose: proseFields, undoCaptureTimeout, persistence, }: ConvexCollectionOptionsConfig<T>): CollectionConfig<T> & {
     _convexClient: ConvexClient;
-    _collectionName: string;
+    _collection: string;
+    _proseFields: Array<ProseFields<T>>;
+    _persistence: Persistence;
+    utils: ConvexCollectionUtils<T>;
 };
-/**
- * Step 2: Wrap collection with offline support.
- *
- * This implements the CORRECT pattern:
- * - Wraps collection ONCE with startOfflineExecutor
- * - Returns raw collection (NO CUSTOM WRAPPER)
- * - Uses beforeRetry filter for stale transactions
- * - Connects to Convex connection state for retry triggers
- *
- * Config is automatically extracted from the rawCollection!
- *
- * @example
- * ```typescript
- * import { createCollection } from '@tanstack/react-db'
- * import { convexCollectionOptions, createConvexCollection } from '@trestleinc/convex-replicate-core'
- *
- * // Step 1: Create raw collection with ALL config
- * const rawCollection = createCollection(
- *   convexCollectionOptions<Task>({
- *     convexClient,
- *     api: api.tasks,
- *     collectionName: 'tasks',
- *     getKey: (task) => task.id,
- *     initialData,
- *   })
- * )
- *
- * // Step 2: Wrap with offline support - params automatically extracted!
- * const collection = createConvexCollection(rawCollection)
- *
- * // Use like a normal TanStack DB collection
- * const tx = collection.insert({ id: '1', text: 'Buy milk', isCompleted: false })
- * await tx.isPersisted.promise  // Built-in promise (not custom awaitReplication)
- * ```
- */
-export declare function createConvexCollection<T extends object>(rawCollection: Collection<T>): ConvexCollection<T>;
+export {};

package/dist/client/errors.d.ts

@@ -0,0 +1,59 @@
+declare const NetworkError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NetworkError";
+} & Readonly<A>;
+export declare class NetworkError extends NetworkError_base<{
+    readonly cause: unknown;
+    readonly retryable: true;
+    readonly operation: string;
+}> {
+}
+declare const IDBError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "IDBError";
+} & Readonly<A>;
+export declare class IDBError extends IDBError_base<{
+    readonly operation: 'get' | 'set' | 'delete' | 'clear';
+    readonly store?: string;
+    readonly key?: string;
+    readonly cause: unknown;
+}> {
+}
+declare const IDBWriteError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "IDBWriteError";
+} & Readonly<A>;
+export declare class IDBWriteError extends IDBWriteError_base<{
+    readonly key: string;
+    readonly value: unknown;
+    readonly cause: unknown;
+}> {
+}
+declare const ReconciliationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ReconciliationError";
+} & Readonly<A>;
+export declare class ReconciliationError extends ReconciliationError_base<{
+    readonly collection: string;
+    readonly reason: string;
+    readonly cause?: unknown;
+}> {
+}
+declare const ProseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ProseError";
+} & Readonly<A>;
+export declare class ProseError extends ProseError_base<{
+    readonly documentId: string;
+    readonly field: string;
+    readonly collection: string;
+}> {
+}
+declare const CollectionNotReadyError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CollectionNotReadyError";
+} & Readonly<A>;
+export declare class CollectionNotReadyError extends CollectionNotReadyError_base<{
+    readonly collection: string;
+    readonly reason: string;
+}> {
+}
+/** Error that should not be retried (auth failures, validation errors) */
+export declare class NonRetriableError extends Error {
+    constructor(message: string);
+}
+export {};

package/dist/client/index.d.ts

@@ -1,18 +1,22 @@
-/**
- * Client-side utilities for browser/React code.
- * Import this in your frontend components.
- *
- * @example
- * ```typescript
- * // src/useTasks.ts
- * import {
- *   convexCollectionOptions,
- *   createConvexCollection,
- *   type ConvexCollection,
- * } from '@trestleinc/replicate/client';
- * ```
- */
-export { ReplicateStorage } from './storage.js';
-export { convexCollectionOptions, createConvexCollection, type ConvexCollection, type ConvexCollectionOptionsConfig, } from './collection.js';
-export * as Y from 'yjs';
-export { NonRetriableError } from '@tanstack/offline-transactions';
+export { convexCollectionOptions, type ConvexCollection, type EditorBinding, } from '$/client/collection.js';
+import { NetworkError, IDBError, IDBWriteError, ReconciliationError, ProseError, CollectionNotReadyError, NonRetriableError } from '$/client/errors.js';
+export declare const errors: {
+    readonly Network: typeof NetworkError;
+    readonly IDB: typeof IDBError;
+    readonly IDBWrite: typeof IDBWriteError;
+    readonly Reconciliation: typeof ReconciliationError;
+    readonly Prose: typeof ProseError;
+    readonly CollectionNotReady: typeof CollectionNotReadyError;
+    readonly NonRetriable: typeof NonRetriableError;
+};
+import { extract } from '$/client/merge.js';
+export declare const prose: {
+    readonly extract: typeof extract;
+};
+export { persistence, type Persistence, type PersistenceProvider, type KeyValueStore, type SqlitePersistenceOptions, type SqliteAdapter, type SqlJsStatic, } from '$/client/persistence/index.js';
+import { SqlJsAdapter, OPSqliteAdapter } from '$/client/persistence/adapters/index.js';
+export declare const adapters: {
+    readonly sqljs: typeof SqlJsAdapter;
+    readonly opsqlite: typeof OPSqliteAdapter;
+};
+export type { SqlJsDatabase, SqlJsAdapterOptions, OPSQLiteDatabase, } from '$/client/persistence/adapters/index.js';

package/dist/client/logger.d.ts

@@ -1,3 +1,2 @@
 import { type Logger } from '@logtape/logtape';
-export declare function configureLogger(enableLogging?: boolean): Promise<void>;
 export declare function getLogger(category: string[]): Logger;

package/dist/client/merge.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Merge Helpers - Plain functions for Yjs CRDT operations
+ *
+ * Provides document creation, state encoding, and merge operations.
+ */
+import * as Y from 'yjs';
+import type { KeyValueStore } from '$/client/persistence/types.js';
+/**
+ * Create a Yjs document with a persistent clientId.
+ * The clientId ensures consistent identity across sessions for CRDT merging.
+ *
+ * @param collection - The collection name
+ * @param kv - Key-value store for persisting the clientId
+ */
+export declare function createYjsDocument(collection: string, kv: KeyValueStore): Promise<Y.Doc>;
+/**
+ * Apply a binary update to a Yjs document.
+ * Y.applyUpdateV2 is already atomic, no need for transaction wrapper.
+ */
+export declare function applyUpdate(doc: Y.Doc, update: Uint8Array, origin?: string): void;
+/**
+ * Get a Y.Map from a Yjs document by name.
+ */
+export declare function getYMap<T = unknown>(doc: Y.Doc, name: string): Y.Map<T>;
+/**
+ * Execute a function within a Yjs transaction.
+ */
+export declare function yjsTransact<A>(doc: Y.Doc, fn: () => A, origin?: string): A;
+/**
+ * Execute a function within a Yjs transaction and capture the delta.
+ * Returns both the function result and a delta containing only the changes made.
+ */
+export declare function transactWithDelta<A>(doc: Y.Doc, fn: () => A, origin?: string): {
+    result: A;
+    delta: Uint8Array;
+};
+/**
+ * Serialize a Y.Map to a plain object.
+ */
+export declare function serializeYMap(ymap: Y.Map<unknown>): Record<string, unknown>;
+/**
+ * Extract all items from a Y.Map as plain objects.
+ */
+export declare function extractItems<T>(ymap: Y.Map<unknown>): T[];
+/**
+ * Extract a single item from a Y.Map by key.
+ */
+export declare function extractItem<T>(ymap: Y.Map<unknown>, key: string): T | null;
+import type { XmlFragmentJSON } from '$/shared/types.js';
+/**
+ * Check if a value looks like ProseMirror/BlockNote JSON document.
+ * Used internally to auto-detect prose fields during insert/update.
+ */
+export declare function isDoc(value: unknown): value is XmlFragmentJSON;
+/**
+ * Convert a Y.XmlFragment to ProseMirror-compatible JSON.
+ */
+export declare function fragmentToJSON(fragment: Y.XmlFragment): XmlFragmentJSON;
+/**
+ * Initialize a Y.XmlFragment from ProseMirror-compatible JSON.
+ */
+export declare function fragmentFromJSON(fragment: Y.XmlFragment, json: XmlFragmentJSON): void;
+/**
+ * Extract plain text from ProseMirror/BlockNote JSON content.
+ * Handles various content structures defensively for search and display.
+ */
+export declare function extract(content: unknown): string;
+/**
+ * Serialize any value, handling Yjs types specially.
+ * Uses our custom serialization system that works across module instances.
+ */
+export declare function serializeYMapValue(value: unknown): unknown;
+/**
+ * Get a Y.XmlFragment from a document's field.
+ * Returns null if the document or field doesn't exist, or if the field is not an XmlFragment.
+ */
+export declare function getFragmentFromYMap(ymap: Y.Map<unknown>, documentId: string, field: string): Y.XmlFragment | null;

package/dist/client/persistence/adapters/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SQLite adapter wrappers for different platforms.
+ *
+ * These are wrapper classes - the consuming app imports and initializes
+ * the actual database packages, then passes them to these wrappers.
+ */
+export { SqlJsAdapter, type SqlJsDatabase, type SqlJsAdapterOptions } from './sqljs.js';
+export { OPSqliteAdapter, type OPSQLiteDatabase } from './opsqlite.js';

package/dist/client/persistence/adapters/opsqlite.d.ts

@@ -0,0 +1,46 @@
+/**
+ * op-sqlite adapter wrapper for React Native SQLite.
+ *
+ * The consuming app imports @op-engineering/op-sqlite and opens the database,
+ * then passes it to this wrapper.
+ *
+ * @example
+ * ```typescript
+ * import { open } from '@op-engineering/op-sqlite';
+ * import { OPSqliteAdapter } from '@trestleinc/replicate/client';
+ *
+ * const db = open({ name: 'myapp.db' });
+ * const adapter = new OPSqliteAdapter(db);
+ * ```
+ */
+import type { SqliteAdapter } from '../sqlite-level.js';
+/**
+ * Interface for op-sqlite Database.
+ * Consumer must install @op-engineering/op-sqlite and pass a Database instance.
+ */
+export interface OPSQLiteDatabase {
+    execute(sql: string, params?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+    close(): void;
+}
+/**
+ * Wraps an op-sqlite Database as a SqliteAdapter.
+ *
+ * @example
+ * ```typescript
+ * import { open } from '@op-engineering/op-sqlite';
+ * import { OPSqliteAdapter } from '@trestleinc/replicate/client';
+ *
+ * const db = open({ name: 'myapp.db' });
+ * const adapter = new OPSqliteAdapter(db);
+ * ```
+ */
+export declare class OPSqliteAdapter implements SqliteAdapter {
+    private db;
+    constructor(db: OPSQLiteDatabase);
+    execute(sql: string, params?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+    close(): void;
+}

package/dist/client/persistence/adapters/sqljs.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 declare class SqlJsAdapter implements SqliteAdapter {
+    private db;
+    private onPersist?;
+    constructor(db: SqlJsDatabase, options?: SqlJsAdapterOptions);
+    execute(sql: string, params?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+    close(): void;
+    /**
+     * Persist database using the onPersist callback if provided.
+     */
+    private persist;
+}

package/dist/client/persistence/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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';
+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 declare const persistence: {
+    /** IndexedDB-backed persistence (browser) */
+    readonly indexeddb: typeof indexeddbPersistence;
+    /** In-memory persistence (testing/ephemeral) */
+    readonly memory: typeof memoryPersistence;
+    /** SQLite persistence variants */
+    readonly sqlite: {
+        /** Browser SQLite with OPFS (sql.js) */
+        readonly browser: typeof createBrowserSqlitePersistence;
+        /** React Native SQLite (op-sqlite) */
+        readonly native: typeof createReactNativeSqlitePersistence;
+        /** Custom SQLite adapter */
+        readonly create: typeof sqlitePersistence;
+    };
+};

package/dist/client/persistence/indexeddb.d.ts

@@ -0,0 +1,17 @@
+import type { Persistence } from './types.js';
+/**
+ * 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 declare function indexeddbPersistence(dbName?: string): Persistence;

package/dist/client/persistence/memory.d.ts

@@ -0,0 +1,16 @@
+import type { Persistence } from './types.js';
+/**
+ * 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 declare function memoryPersistence(): Persistence;

package/dist/client/persistence/sqlite-browser.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 { type SqlJsDatabase } from './adapters/sqljs.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;
+}
+/**
+ * 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 declare function createBrowserSqlitePersistence(SQL: SqlJsStatic, dbName: string): Promise<Persistence>;