@trestleinc/replicate 1.1.2 → 1.2.0-preview.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trestleinc/replicate",
-  "version": "1.1.2",
+  "version": "1.2.0-preview.0",
   "description": "Offline-first data replication with Yjs CRDTs and Convex",
   "repository": "github:trestleinc/replicate",
   "homepage": "https://github.com/trestleinc/replicate#readme",
@@ -82,6 +82,7 @@
     "@tanstack/db": "^0.5.15",
     "convex": "^1.31.0",
     "lib0": "^0.2.0",
+    "y-protocols": "^1.0.7",
     "yjs": "^13.6.0"
   },
   "peerDependenciesMeta": {
@@ -111,6 +112,7 @@
     "tsdown": "0.18.2",
     "typescript": "5.9.3",
     "typescript-eslint": "8.50.1",
+    "y-protocols": "1.0.7",
     "yjs": "13.6.28",
     "zod": "4.2.1"
   },