@trestleinc/replicate 1.1.2 → 1.2.0-preview.1

package/README.md

@@ -127,16 +127,14 @@ export default defineSchema({
 
 ### Step 3: Create Replication Functions
 
-Use `replicate()` to bind your component and create collection functions:
+Use `collection.create()` to create server-side collection functions:
 
 ```typescript
 // convex/tasks.ts
-import { replicate } from '@trestleinc/replicate/server';
+import { collection } from '@trestleinc/replicate/server';
 import { components } from './_generated/api';
 import type { Task } from '../src/useTasks';
 
-const r = replicate(components.replicate);
-
 export const {
   stream,
   material,
@@ -144,18 +142,15 @@ export const {
   insert,
   update,
   remove,
-  mark,     // Peer sync progress tracking
-  compact,  // Manual compaction trigger
-} = r<Task>({
-  collection: 'tasks',
-  compaction: {
-    sizeThreshold: "5mb",  // Type-safe size: "100kb", "5mb", "1gb"
-    peerTimeout: "24h",    // Type-safe duration: "30m", "24h", "7d"
-  },
-});
+  mark,
+  compact,
+  sessions,
+  cursors,
+  leave,
+} = collection.create<Task>(components.replicate, 'tasks');
 ```
 
-**What `replicate()` generates:**
+**What `collection.create()` generates:**
 
 - `stream` - Real-time CRDT stream query (cursor-based subscriptions with `seq` numbers)
 - `material` - SSR-friendly query (for server-side rendering)
@@ -165,6 +160,9 @@ 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
 
 ### Step 4: Define Your Collection
 
@@ -296,7 +294,7 @@ For frameworks that support SSR (TanStack Start, Next.js, Remix, SvelteKit), pre
 
 **Step 1: Prefetch material on the server**
 
-Use `ConvexHttpClient` to fetch data during SSR. The `material` query is generated by `replicate()`:
+Use `ConvexHttpClient` to fetch data during SSR. The `material` query is generated by `collection.create()`:
 
 ```typescript
 // TanStack Start: src/routes/__root.tsx
@@ -471,12 +469,10 @@ You can customize the behavior of generated functions using optional hooks:
 
 ```typescript
 // convex/tasks.ts
-import { replicate } from '@trestleinc/replicate/server';
+import { collection } from '@trestleinc/replicate/server';
 import { components } from './_generated/api';
 import type { Task } from '../src/useTasks';
 
-const r = replicate(components.replicate);
-
 export const {
   stream,
   material,
@@ -486,9 +482,10 @@ export const {
   remove,
   mark,
   compact,
-} = r<Task>({
-  collection: 'tasks',
-
+  sessions,
+  cursors,
+  leave,
+} = collection.create<Task>(components.replicate, 'tasks', {
   // Optional hooks for authorization and lifecycle events
   hooks: {
     // Permission checks (eval* hooks validate BEFORE execution, throw to deny)
@@ -500,7 +497,7 @@ export const {
       const userId = await ctx.auth.getUserIdentity();
       if (!userId) throw new Error('Unauthorized');
     },
-    evalRemove: async (ctx, documentId) => {
+    evalRemove: async (ctx, document) => {
       const userId = await ctx.auth.getUserIdentity();
       if (!userId) throw new Error('Unauthorized');
     },
@@ -509,7 +506,7 @@ export const {
       const userId = await ctx.auth.getUserIdentity();
       if (!userId) throw new Error('Unauthorized');
     },
-    evalCompact: async (ctx, documentId) => {
+    evalCompact: async (ctx, document) => {
       // Restrict compaction to admin users
       const userId = await ctx.auth.getUserIdentity();
       if (!userId) throw new Error('Unauthorized');
@@ -519,7 +516,7 @@ export const {
     onStream: async (ctx, result) => { /* after stream query */ },
     onInsert: async (ctx, doc) => { /* after insert */ },
     onUpdate: async (ctx, doc) => { /* after update */ },
-    onRemove: async (ctx, documentId) => { /* after remove */ },
+    onRemove: async (ctx, document) => { /* after remove */ },
 
     // Transform hook (modify documents before returning)
     transform: async (docs) => docs.filter(d => d.isPublic),
@@ -711,7 +708,7 @@ interface CollectionConfig<T> {
   schema: ZodObject;              // Required: Zod schema for type inference
   getKey: (item: T) => string | number;  // Extract unique key from item
   convexClient: ConvexClient;     // Convex client instance
-  api: {                          // API from replicate()
+  api: {                          // API from collection.create()
     stream: FunctionReference;    // Real-time subscription
     insert: FunctionReference;    // Insert mutation
     update: FunctionReference;    // Update mutation
@@ -816,34 +813,33 @@ errors.NonRetriable      // Errors that should not be retried (auth, validation)
 
 ### Server-Side (`@trestleinc/replicate/server`)
 
-#### `replicate(component)`
+#### `collection.create<T>(component, name, options?)`
 
-Factory function that creates a bound replicate function for your collections.
+Creates server-side collection functions that mirror the client-side collection.
 
 **Parameters:**
 - `component` - Your Convex component reference (`components.replicate`)
-
-**Returns:** A function `<T>(config: ReplicateConfig<T>)` that generates collection operations.
+- `name` - Collection name (e.g., `'tasks'`)
+- `options` - Optional configuration for compaction and hooks
 
 **Example:**
 ```typescript
-import { replicate } from '@trestleinc/replicate/server';
+import { collection } from '@trestleinc/replicate/server';
 import { components } from './_generated/api';
 
-const r = replicate(components.replicate);
-export const tasks = r<Task>({ collection: 'tasks' });
+export const {
+  stream, material, insert, update, remove, recovery, mark, compact, sessions, cursors, leave,
+} = collection.create<Task>(components.replicate, 'tasks');
 ```
 
-#### `ReplicateConfig<T>`
+#### `CollectionOptions<T>`
 
-Configuration for the bound replicate function.
+Optional configuration for `collection.create()`.
 
 **Config:**
 ```typescript
-interface ReplicateConfig<T> {
-  collection: string;          // Collection name (e.g., 'tasks')
-
-  // Optional: Compaction settings with type-safe values
+interface CollectionOptions<T> {
+  // Optional: Compaction settings
   compaction?: {
     sizeThreshold?: Size;      // Size threshold: "100kb", "5mb", "1gb" (default: "5mb")
     peerTimeout?: Duration;    // Peer timeout: "30m", "24h", "7d" (default: "24h")
@@ -854,15 +850,15 @@ interface ReplicateConfig<T> {
     // Permission checks (throw to reject)
     evalRead?: (ctx, collection) => Promise<void>;
     evalWrite?: (ctx, doc) => Promise<void>;
-    evalRemove?: (ctx, documentId) => Promise<void>;
+    evalRemove?: (ctx, document) => Promise<void>;
     evalMark?: (ctx, peerId) => Promise<void>;
-    evalCompact?: (ctx, documentId) => Promise<void>;
+    evalCompact?: (ctx, document) => Promise<void>;
 
     // Lifecycle callbacks (run after operation)
     onStream?: (ctx, result) => Promise<void>;
     onInsert?: (ctx, doc) => Promise<void>;
     onUpdate?: (ctx, doc) => Promise<void>;
-    onRemove?: (ctx, documentId) => Promise<void>;
+    onRemove?: (ctx, document) => Promise<void>;
 
     // Transform hook (modify documents before returning)
     transform?: (docs) => Promise<T[]>;
@@ -883,6 +879,9 @@ interface ReplicateConfig<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
 
 #### `schema.table(userFields, applyIndexes?)`
 

package/dist/client/index.d.ts

@@ -2,6 +2,7 @@ import * as Y from "yjs";
 import { FunctionReference } from "convex/server";
 import { BaseCollectionConfig, Collection, NonSingleResult } from "@tanstack/db";
 import { Context, Effect, Layer } from "effect";
+import { Awareness } from "y-protocols/awareness";
 import { ConvexClient } from "convex/browser";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 import * as effect_Types0 from "effect/Types";
@@ -97,7 +98,7 @@ declare const ProseError_base: new <A extends Record<string, any> = {}>(args: ef
   readonly _tag: "ProseError";
 } & Readonly<A>;
 declare class ProseError extends ProseError_base<{
-  readonly documentId: string;
+  readonly document: string;
   readonly field: string;
   readonly collection: string;
 }> {}
@@ -113,8 +114,8 @@ declare class NonRetriableError extends Error {
   constructor(message: string);
 }
 //#endregion
-//#region src/client/services/cursor.d.ts
-type Cursor = number;
+//#region src/client/services/seq.d.ts
+type Seq = number;
 //#endregion
 //#region src/shared/types.d.ts
 /** ProseMirror-compatible JSON for XmlFragment serialization */
@@ -152,9 +153,12 @@ type ProseFields<T> = { [K in keyof T]: T[K] extends ProseValue ? K : never }[ke
 /** Server-rendered material data for SSR hydration */
 interface Materialized<T> {
   documents: readonly T[];
-  cursor?: Cursor;
+  cursor?: Seq;
   count?: number;
-  crdtBytes?: ArrayBuffer;
+  crdt?: Record<string, {
+    bytes: ArrayBuffer;
+    seq: number;
+  }>;
 }
 /** API object from replicate() */
 interface ConvexCollectionApi {
@@ -166,6 +170,9 @@ interface ConvexCollectionApi {
   mark: FunctionReference<"mutation">;
   compact: FunctionReference<"mutation">;
   material?: FunctionReference<"query">;
+  sessions?: FunctionReference<"query">;
+  cursors?: FunctionReference<"query">;
+  leave?: 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;
@@ -173,39 +180,42 @@ interface ConvexCollectionConfig<T extends object = object, TSchema extends Stan
   api: ConvexCollectionApi;
   persistence: Persistence;
   material?: Materialized<T>;
-  undoCaptureTimeout?: number;
 }
-/** Editor binding for BlockNote/TipTap collaboration */
+/**
+ * Binding returned by collection.utils.prose() for collaborative editing.
+ *
+ * Compatible with TipTap's Collaboration/CollaborationCursor and BlockNote's
+ * collaboration config. The editor handles undo/redo internally via y-prosemirror.
+ */
 interface EditorBinding {
-  /** The Y.XmlFragment bound to the editor */
+  /** Yjs XmlFragment for content sync */
   readonly fragment: Y.XmlFragment;
-  /** Provider stub for BlockNote compatibility */
+  /**
+   * Provider with Yjs Awareness for cursor/presence sync.
+   * Pass to CollaborationCursor.configure({ provider: binding.provider })
+   * or BlockNote's collaboration.provider
+   */
   readonly provider: {
-    readonly awareness: null;
+    readonly awareness: Awareness;
+    readonly document: Y.Doc;
   };
-  /** Current sync state - true if unsent changes exist */
+  /** Whether there are unsaved local changes */
   readonly pending: boolean;
-  /** Subscribe to pending state changes. Returns unsubscribe function. */
+  /** Subscribe to pending state changes */
   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;
+  /** Cleanup - call when unmounting editor */
+  destroy(): void;
 }
 /** 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 document - 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>;
+  prose(document: string, field: ProseFields<T>): Promise<EditorBinding>;
 }
 type LazyCollectionConfig<TSchema extends z.ZodObject<z.ZodRawShape>> = Omit<ConvexCollectionConfig<z.infer<TSchema>, TSchema, string>, "persistence" | "material">;
 interface LazyCollection<T extends object> {
@@ -228,7 +238,7 @@ declare const collection: {
  */
 declare function extract(content: unknown): string;
 //#endregion
-//#region src/client/prose-schema.d.ts
+//#region src/client/prose.d.ts
 declare function emptyProse(): ProseValue;
 declare function prose$1(): z.ZodType<ProseValue>;
 declare namespace prose$1 {
@@ -305,10 +315,8 @@ declare const errors: {
   readonly CollectionNotReady: typeof CollectionNotReadyError;
   readonly NonRetriable: typeof NonRetriableError;
 };
-declare function empty(): ProseValue;
 declare const prose: typeof prose$1 & {
   extract: typeof extract;
-  empty: typeof empty;
 };
 //#endregion
-export { type ConvexCollection, type EditorBinding, type Materialized, type Persistence, type StorageAdapter, collection, errors, persistence, prose };
+export { type ConvexCollection, type EditorBinding, type Materialized, type Persistence, type Seq, type StorageAdapter, collection, errors, persistence, prose };