@trestleinc/replicate 1.2.0-preview.1 → 1.2.0-preview.3

package/README.md

@@ -145,8 +145,7 @@ export const {
   mark,
   compact,
   sessions,
-  cursors,
-  leave,
+  presence,
 } = collection.create<Task>(components.replicate, 'tasks');
 ```
 
@@ -160,9 +159,8 @@ export const {
 - `remove` - Dual-storage delete mutation (auto-compacts when threshold exceeded)
 - `mark` - Report sync progress to server (peer tracking for safe compaction)
 - `compact` - Manual compaction trigger (peer-aware, respects active peer sync state)
-- `sessions` - Get connected sessions (presence query)
-- `cursors` - Get cursor positions for collaborative editing
-- `leave` - Explicit disconnect mutation
+- `sessions` - Get connected sessions with cursor positions (presence query)
+- `presence` - Join/leave presence for collaborative editing (with cursor, user, profile)
 
 ### Step 4: Define Your Collection
 
@@ -173,7 +171,7 @@ Create a collection definition using `collection.create()`. This is SSR-safe bec
 import { collection, persistence } from '@trestleinc/replicate/client';
 import { ConvexClient } from 'convex/browser';
 import { api } from '../../convex/_generated/api';
-import initSqlJs from 'sql.js';
+import { PGlite } from '@electric-sql/pglite';
 import { z } from 'zod';
 
 // Define your Zod schema (required)
@@ -189,8 +187,8 @@ export type Task = z.infer<typeof taskSchema>;
 export const tasks = collection.create({
   // Async factory - only called in browser during init()
   persistence: async () => {
-    const SQL = await initSqlJs({ locateFile: (f) => `/${f}` });
-    return persistence.sqlite.browser(SQL, 'tasks');
+    const db = new PGlite('idb://tasks');
+    return persistence.pglite(db, 'tasks');
   },
   // Sync factory - only called in browser during init()
   config: () => ({
@@ -483,8 +481,7 @@ export const {
   mark,
   compact,
   sessions,
-  cursors,
-  leave,
+  presence,
 } = collection.create<Task>(components.replicate, 'tasks', {
   // Optional hooks for authorization and lifecycle events
   hooks: {
@@ -526,10 +523,10 @@ export const {
 
 ### Rich Text / Prose Fields
 
-For collaborative rich text editing, use the `schema.prose()` validator and `prose.extract()` function:
+For collaborative rich text editing, use `schema.prose()` on both server and client:
 
 ```typescript
-// convex/schema.ts
+// convex/schema.ts (server)
 import { schema } from '@trestleinc/replicate/server';
 
 export default defineSchema({
@@ -541,14 +538,85 @@ export default defineSchema({
 });
 
 // Client: Extract plain text for search
-import { prose } from '@trestleinc/replicate/client';
+import { schema } from '@trestleinc/replicate/client';
 
-const plainText = prose.extract(notebook.content);
+const plainText = schema.prose.extract(notebook.content);
 
 // Client: Get editor binding for ProseMirror/TipTap
 const binding = await collection.utils.prose(notebookId, 'content');
 ```
 
+**Important:** `collection.utils.prose()` is async and internally waits for the actor system to initialize before observing the Yjs fragment. This ensures the sync infrastructure is ready before collaborative editing begins.
+
+```typescript
+// React: Use useEffect with cleanup
+useEffect(() => {
+  let binding: EditorBinding | null = null;
+  
+  collection.utils.prose(docId, 'content').then((b) => {
+    binding = b;
+    // Initialize your editor with binding.fragment and binding.provider
+  });
+  
+  return () => binding?.destroy();
+}, [docId]);
+
+// Svelte: Use onMount
+onMount(async () => {
+  binding = await collection.utils.prose(docId, 'content');
+  // Initialize TipTap with binding.fragment
+  
+  return () => binding?.destroy();
+});
+```
+
+**Prose Options:**
+
+```typescript
+interface ProseOptions {
+  user?: UserIdentity;  // Collaborative presence identity
+  debounceMs?: number;  // Sync debounce delay (default: 200ms)
+}
+
+interface UserIdentity {
+  name?: string;   // Display name for cursor labels
+  color?: string;  // Cursor/selection color (hex, e.g., "#6366f1")
+  avatar?: string; // Avatar URL for presence indicators
+}
+```
+
+**Configuration Examples:**
+
+```typescript
+// Minimal: Just get the binding with defaults
+const binding = await collection.utils.prose(docId, 'content');
+
+// With user presence for collaborative cursors
+const binding = await collection.utils.prose(docId, 'content', {
+  user: {
+    name: 'Alice',
+    color: '#6366f1',
+    avatar: 'https://example.com/alice.jpg',
+  },
+});
+
+// Custom debounce: 500ms for less frequent syncs
+const binding = await collection.utils.prose(docId, 'content', {
+  debounceMs: 500,
+});
+
+// Real-time: No debounce (sync on every keystroke)
+const binding = await collection.utils.prose(docId, 'content', {
+  debounceMs: 0,
+});
+
+// Full configuration
+const binding = await collection.utils.prose(docId, 'content', {
+  user: { name: 'Alice', color: '#6366f1' },
+  debounceMs: 200,
+});
+```
+
 ### Persistence Providers
 
 Choose the right storage backend for your platform. Persistence is configured in the `persistence` factory of `collection.create()`:
@@ -556,17 +624,38 @@ Choose the right storage backend for your platform. Persistence is configured in
 ```typescript
 import { collection, persistence } from '@trestleinc/replicate/client';
 
-// Browser SQLite: Uses sql.js WASM with OPFS persistence
+// Browser: PGlite (PostgreSQL in browser via IndexedDB)
 export const tasks = collection.create({
   persistence: async () => {
-    const initSqlJs = (await import('sql.js')).default;
-    const SQL = await initSqlJs({ locateFile: (f) => `/${f}` });
-    return persistence.sqlite.browser(SQL, 'my-app-db');
+    const { PGlite } = await import('@electric-sql/pglite');
+    const db = new PGlite('idb://my-app-db');
+    return persistence.pglite(db, 'tasks');
   },
   config: () => ({ /* ... */ }),
 });
 
-// React Native SQLite: Uses op-sqlite (native SQLite)
+// Browser: PGlite singleton (shared across multiple collections)
+// Use persistence.pglite.once() when you want one database for all collections
+import { persistence } from '@trestleinc/replicate/client';
+import { PGlite } from '@electric-sql/pglite';
+
+// Create shared PGlite factory (module level)
+const pglite = async () => {
+  const db = new PGlite('idb://my-app-db');
+  return persistence.pglite.once(db, 'my-app');
+};
+
+export const tasks = collection.create({
+  persistence: pglite,  // Shared instance
+  config: () => ({ /* ... */ }),
+});
+
+export const comments = collection.create({
+  persistence: pglite,  // Same shared instance
+  config: () => ({ /* ... */ }),
+});
+
+// React Native: Native SQLite (op-sqlite)
 export const tasks = collection.create({
   persistence: async () => {
     const { open } = await import('@op-engineering/op-sqlite');
@@ -589,7 +678,9 @@ export const tasks = collection.create({
 });
 ```
 
-**SQLite Browser** - Uses sql.js (SQLite compiled to WASM) with OPFS persistence. You initialize sql.js yourself and pass the SQL object.
+**PGlite** - PostgreSQL compiled to WASM, stored in IndexedDB. Full SQL support with reactive queries. Recommended for web apps.
+
+**PGlite Singleton** - Use `persistence.pglite.once()` when multiple collections should share one database. Reference counted for proper cleanup.
 
 **SQLite Native** - Uses op-sqlite for React Native. You create the database and pass it.
 
@@ -666,18 +757,18 @@ Creates a lazy-initialized collection with deferred persistence and config resol
 ```typescript
 import { collection, persistence } from '@trestleinc/replicate/client';
 import { ConvexClient } from 'convex/browser';
-import initSqlJs from 'sql.js';
+import { PGlite } from '@electric-sql/pglite';
 
 export const tasks = collection.create({
   persistence: async () => {
-    const SQL = await initSqlJs({ locateFile: (f) => `/${f}` });
-    return persistence.sqlite.browser(SQL, 'tasks');
+    const db = new PGlite('idb://tasks');
+    return persistence.pglite(db, 'tasks');
   },
   config: () => ({
     schema: taskSchema,
+    getKey: (task) => task.id,
     convexClient: new ConvexClient(import.meta.env.VITE_CONVEX_URL),
     api: api.tasks,
-    getKey: (task) => task.id,
   }),
 });
 
@@ -726,8 +817,8 @@ interface CollectionConfig<T> {
 ```typescript
 export const tasks = collection.create({
   persistence: async () => {
-    const SQL = await initSqlJs({ locateFile: (f) => `/${f}` });
-    return persistence.sqlite.browser(SQL, 'tasks');
+    const db = new PGlite('idb://tasks');
+    return persistence.pglite(db, 'tasks');
   },
   config: () => ({
     schema: taskSchema,
@@ -738,7 +829,7 @@ export const tasks = collection.create({
 });
 ```
 
-#### `prose.extract(proseJson)`
+#### `schema.prose.extract(proseJson)`
 
 Extract plain text from ProseMirror JSON.
 
@@ -749,9 +840,9 @@ Extract plain text from ProseMirror JSON.
 
 **Example:**
 ```typescript
-import { prose } from '@trestleinc/replicate/client';
+import { schema } from '@trestleinc/replicate/client';
 
-const plainText = prose.extract(task.content);
+const plainText = schema.prose.extract(task.content);
 ```
 
 #### Persistence Providers
@@ -760,13 +851,16 @@ const plainText = prose.extract(task.content);
 import { persistence, type StorageAdapter } from '@trestleinc/replicate/client';
 
 // Persistence providers (use in collection.create persistence factory)
-persistence.sqlite.browser(SQL, name)  // Browser: sql.js WASM + OPFS
+persistence.pglite(db, name)           // Browser: PGlite (PostgreSQL in IndexedDB)
+persistence.pglite.once(db, name)      // Browser: PGlite singleton (shared across collections)
 persistence.sqlite.native(db, name)    // React Native: op-sqlite
 persistence.memory()                   // Testing: in-memory (no persistence)
 persistence.custom(adapter)            // Custom: your StorageAdapter implementation
 ```
 
-**`persistence.sqlite.browser(SQL, name)`** - Browser SQLite using sql.js WASM. You initialize sql.js and pass the SQL object.
+**`persistence.pglite(db, name)`** - Browser persistence using PGlite (PostgreSQL compiled to WASM, stored in IndexedDB).
+
+**`persistence.pglite.once(db, name)`** - Singleton PGlite instance for sharing across multiple collections. Reference counted for cleanup.
 
 **`persistence.sqlite.native(db, name)`** - React Native SQLite using op-sqlite. You create the database and pass it.
 
@@ -828,7 +922,7 @@ import { collection } from '@trestleinc/replicate/server';
 import { components } from './_generated/api';
 
 export const {
-  stream, material, insert, update, remove, recovery, mark, compact, sessions, cursors, leave,
+  stream, material, insert, update, remove, recovery, mark, compact, sessions, presence,
 } = collection.create<Task>(components.replicate, 'tasks');
 ```
 
@@ -879,9 +973,8 @@ interface CollectionOptions<T> {
 - `remove` - Dual-storage delete mutation (auto-compacts when threshold exceeded)
 - `mark` - Peer sync tracking mutation (reports `syncedSeq` to server)
 - `compact` - Manual compaction mutation (peer-aware, safe for active clients)
-- `sessions` - Get connected sessions (presence query)
-- `cursors` - Get cursor positions for collaborative editing
-- `leave` - Explicit disconnect mutation
+- `sessions` - Get connected sessions with cursor positions (presence query)
+- `presence` - Join/leave presence mutation (with cursor, user, profile)
 
 #### `schema.table(userFields, applyIndexes?)`
 
@@ -925,7 +1018,7 @@ content: schema.prose()  // Validates ProseMirror JSON structure
 import type { ProseValue } from '@trestleinc/replicate/shared';
 
 // ProseValue - branded type for prose fields in Zod schemas
-// Use the prose() helper from client to create fields of this type
+// Use schema.prose() from client to create Zod fields of this type
 ```
 
 ## React Native
@@ -966,11 +1059,11 @@ A full-featured offline-first issue tracker built with Replicate, demonstrating
 - [`examples/expo/`](./examples/expo/) - Expo (React Native, mobile)
 
 **Web features demonstrated:**
-- Offline-first with SQLite persistence (sql.js + OPFS)
+- Offline-first with PGlite persistence (PostgreSQL in IndexedDB)
 - Rich text editing with TipTap + Yjs collaboration
 - PWA with custom service worker
 - Real-time sync across devices
-- Search with client-side text extraction (`prose.extract()`)
+- Search with client-side text extraction (`schema.prose.extract()`)
 
 **Mobile features demonstrated (Expo):**
 - Native SQLite persistence (op-sqlite)

package/dist/client/index.d.ts

@@ -9,8 +9,39 @@ import * as effect_Types0 from "effect/Types";
 import * as effect_Cause0 from "effect/Cause";
 import { z } from "zod";
 
+//#region src/shared/types.d.ts
+/** ProseMirror-compatible JSON for XmlFragment serialization */
+interface XmlFragmentJSON {
+  type: "doc";
+  content?: XmlNodeJSON[];
+}
+declare const PROSE_BRAND: unique symbol;
+/**
+ * Branded prose type for Zod schemas.
+ * Extends XmlFragmentJSON with a unique brand for type-level detection.
+ * Use the `prose()` helper from `@trestleinc/replicate/client` to create this type.
+ */
+interface ProseValue extends XmlFragmentJSON {
+  readonly [PROSE_BRAND]: typeof PROSE_BRAND;
+}
+/** ProseMirror node structure */
+interface XmlNodeJSON {
+  type: string;
+  attrs?: Record<string, unknown>;
+  content?: XmlNodeJSON[];
+  text?: string;
+  marks?: {
+    type: string;
+    attrs?: Record<string, unknown>;
+  }[];
+}
+/**
+ * Extract prose field names from T (fields typed as ProseValue).
+ * Used internally for type-safe prose field operations.
+ */
+type ProseFields<T> = { [K in keyof T]: T[K] extends ProseValue ? K : never }[keyof T];
+//#endregion
 //#region src/client/persistence/types.d.ts
-
 /**
  * Low-level storage adapter for custom backends (Chrome extension, localStorage, cloud).
  * For SQLite, use `persistence.sqlite()` directly.
@@ -117,37 +148,12 @@ declare class NonRetriableError extends Error {
 //#region src/client/services/seq.d.ts
 type Seq = number;
 //#endregion
-//#region src/shared/types.d.ts
-/** ProseMirror-compatible JSON for XmlFragment serialization */
-interface XmlFragmentJSON {
-  type: "doc";
-  content?: XmlNodeJSON[];
+//#region src/client/services/awareness.d.ts
+interface UserIdentity {
+  name?: string;
+  color?: string;
+  avatar?: string;
 }
-declare const PROSE_BRAND: unique symbol;
-/**
- * Branded prose type for Zod schemas.
- * Extends XmlFragmentJSON with a unique brand for type-level detection.
- * Use the `prose()` helper from `@trestleinc/replicate/client` to create this type.
- */
-interface ProseValue extends XmlFragmentJSON {
-  readonly [PROSE_BRAND]: typeof PROSE_BRAND;
-}
-/** ProseMirror node structure */
-interface XmlNodeJSON {
-  type: string;
-  attrs?: Record<string, unknown>;
-  content?: XmlNodeJSON[];
-  text?: string;
-  marks?: {
-    type: string;
-    attrs?: Record<string, unknown>;
-  }[];
-}
-/**
- * Extract prose field names from T (fields typed as ProseValue).
- * Used internally for type-safe prose field operations.
- */
-type ProseFields<T> = { [K in keyof T]: T[K] extends ProseValue ? K : never }[keyof T];
 //#endregion
 //#region src/client/collection.d.ts
 /** Server-rendered material data for SSR hydration */
@@ -171,8 +177,7 @@ interface ConvexCollectionApi {
   compact: FunctionReference<"mutation">;
   material?: FunctionReference<"query">;
   sessions?: FunctionReference<"query">;
-  cursors?: FunctionReference<"query">;
-  leave?: FunctionReference<"mutation">;
+  presence?: FunctionReference<"mutation">;
 }
 interface ConvexCollectionConfig<T extends object = object, TSchema extends StandardSchemaV1 = never, TKey extends string | number = string | number> extends BaseCollectionConfig<T, TKey, TSchema> {
   schema: TSchema;
@@ -206,16 +211,18 @@ interface EditorBinding {
   /** Cleanup - call when unmounting editor */
   destroy(): void;
 }
-/** Utilities exposed on collection.utils */
-interface ConvexCollectionUtils<T extends object> {
+interface ProseOptions {
+  /** User identity for collaborative presence */
+  user?: UserIdentity;
   /**
-   * Get an editor binding for a prose field.
-   * Waits for Y.Doc to be ready (IndexedDB loaded) before returning.
-   * @param document - The document ID
-   * @param field - The prose field name (must be in `prose` config)
-   * @returns Promise resolving to EditorBinding
+   * Debounce delay in milliseconds before syncing changes to server.
+   * Local changes are batched during this window for efficiency.
+   * @default 200
    */
-  prose(document: string, field: ProseFields<T>): Promise<EditorBinding>;
+  debounceMs?: number;
+}
+interface ConvexCollectionUtils<T extends object> {
+  prose(document: string, field: ProseFields<T>, options?: ProseOptions): Promise<EditorBinding>;
 }
 type LazyCollectionConfig<TSchema extends z.ZodObject<z.ZodRawShape>> = Omit<ConvexCollectionConfig<z.infer<TSchema>, TSchema, string>, "persistence" | "material">;
 interface LazyCollection<T extends object> {
@@ -240,8 +247,8 @@ declare function extract(content: unknown): string;
 //#endregion
 //#region src/client/prose.d.ts
 declare function emptyProse(): ProseValue;
-declare function prose$1(): z.ZodType<ProseValue>;
-declare namespace prose$1 {
+declare function prose(): z.ZodType<ProseValue>;
+declare namespace prose {
   var empty: typeof emptyProse;
 }
 //#endregion
@@ -262,23 +269,6 @@ declare namespace prose$1 {
  */
 declare function memoryPersistence(): Persistence;
 //#endregion
-//#region src/client/persistence/sqlite/browser.d.ts
-interface SqlJsDatabase {
-  run(sql: string, params?: unknown): unknown;
-  prepare(sql: string): {
-    bind(params?: unknown): void;
-    step(): boolean;
-    getAsObject(): Record<string, unknown>;
-    free(): void;
-  };
-  export(): Uint8Array;
-  close(): void;
-}
-interface SqlJsStatic {
-  Database: new (data?: ArrayLike<number> | Buffer | null) => SqlJsDatabase;
-}
-declare function createBrowserSqlitePersistence(SQL: SqlJsStatic, dbName: string): Promise<Persistence>;
-//#endregion
 //#region src/client/persistence/sqlite/native.d.ts
 interface OPSQLiteDatabase {
   execute(sql: string, params?: unknown[]): Promise<{
@@ -288,20 +278,52 @@ interface OPSQLiteDatabase {
 }
 declare function createNativeSqlitePersistence(db: OPSQLiteDatabase, _dbName: string): Promise<Persistence>;
 //#endregion
-//#region src/client/persistence/indexeddb.d.ts
-declare function createIndexedDBPersistence(dbName: string): Promise<Persistence>;
-//#endregion
 //#region src/client/persistence/custom.d.ts
 declare function createCustomPersistence(adapter: StorageAdapter): Persistence;
 //#endregion
+//#region src/client/persistence/pglite.d.ts
+interface PGliteInterface {
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+    rows: T[];
+  }>;
+  exec(sql: string): Promise<unknown>;
+  close(): Promise<void>;
+}
+declare function createPGlitePersistence(pg: PGliteInterface): Promise<Persistence>;
+/**
+ * Creates a singleton PGlite persistence factory.
+ * Use this to ensure the PGlite WASM module is only loaded once,
+ * even when shared across multiple collections.
+ *
+ * @example
+ * ```typescript
+ * // src/lib/pglite.ts
+ * import { persistence } from "@trestleinc/replicate/client";
+ *
+ * export const pglite = persistence.pglite.once(async () => {
+ *   const { PGlite } = await import("@electric-sql/pglite");
+ *   const { live } = await import("@electric-sql/pglite/live");
+ *   return PGlite.create({ dataDir: "idb://app", extensions: { live } });
+ * });
+ *
+ * // src/collections/useIntervals.ts
+ * import { pglite } from "$lib/pglite";
+ *
+ * export const intervals = collection.create({
+ *   persistence: pglite,
+ *   config: () => ({ ... }),
+ * });
+ * ```
+ */
+declare function oncePGlitePersistence(factory: () => Promise<PGliteInterface>): () => Promise<Persistence>;
+//#endregion
 //#region src/client/persistence/index.d.ts
 declare const persistence: {
-  readonly memory: typeof memoryPersistence;
-  readonly sqlite: {
-    readonly browser: typeof createBrowserSqlitePersistence;
-    readonly native: typeof createNativeSqlitePersistence;
+  readonly pglite: typeof createPGlitePersistence & {
+    once: typeof oncePGlitePersistence;
   };
-  readonly indexeddb: typeof createIndexedDBPersistence;
+  readonly sqlite: typeof createNativeSqlitePersistence;
+  readonly memory: typeof memoryPersistence;
   readonly custom: typeof createCustomPersistence;
 };
 //#endregion
@@ -315,8 +337,11 @@ declare const errors: {
   readonly CollectionNotReady: typeof CollectionNotReadyError;
   readonly NonRetriable: typeof NonRetriableError;
 };
-declare const prose: typeof prose$1 & {
-  extract: typeof extract;
+declare const schema: {
+  readonly prose: typeof prose & {
+    extract: typeof extract;
+    empty: () => ProseValue;
+  };
 };
 //#endregion
-export { type ConvexCollection, type EditorBinding, type Materialized, type Persistence, type Seq, type StorageAdapter, collection, errors, persistence, prose };
+export { type ConvexCollection, type EditorBinding, type Materialized, type Persistence, type ProseOptions, type Seq, type StorageAdapter, type UserIdentity, collection, errors, persistence, schema };