@trestleinc/replicate 0.1.0

package/dist/client/collection.d.ts

@@ -0,0 +1,94 @@
+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
+ */
+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 */
+    convexClient: ConvexClient;
+    /** Convex API functions for this collection */
+    api: {
+        stream: FunctionReference<'query'>;
+        insertDocument: FunctionReference<'mutation'>;
+        updateDocument: FunctionReference<'mutation'>;
+        deleteDocument: FunctionReference<'mutation'>;
+    };
+    /** Unique collection name */
+    collectionName: string;
+}
+/**
+ * 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
+ *
+ * @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,
+ *   })
+ * )
+ * ```
+ */
+export declare function convexCollectionOptions<T extends object>({ getKey, initialData, convexClient, api, collectionName, }: ConvexCollectionOptionsConfig<T>): CollectionConfig<T> & {
+    _convexClient: ConvexClient;
+    _collectionName: string;
+};
+/**
+ * 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>;

package/dist/client/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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';

package/dist/client/logger.d.ts

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

package/dist/client/storage.d.ts

@@ -0,0 +1,143 @@
+import type { Expand, FunctionReference, GenericDataModel, GenericMutationCtx, GenericQueryCtx } from 'convex/server';
+import type { GenericId } from 'convex/values';
+import { api } from '../component/_generated/api';
+/**
+ * A client API for interacting with the Convex Replicate storage component.
+ *
+ * This class provides a type-safe, scoped interface for storing and retrieving
+ * CRDT document data from the replicate component. Each instance is scoped to
+ * a specific collection name, eliminating the need to pass collectionName to
+ * every method call.
+ *
+ * @example
+ * ```typescript
+ * import { components } from "./_generated/api";
+ * import { ReplicateStorage } from "@trestleinc/convex-replicate-component";
+ *
+ * // Create a storage instance for the "tasks" collection
+ * const tasksStorage = new ReplicateStorage(components.replicate, "tasks");
+ *
+ * export const submitTask = mutation({
+ *   handler: async (ctx, args) => {
+ *     return await tasksStorage.submitDocument(
+ *       ctx,
+ *       args.id,
+ *       args.document,
+ *       args.version
+ *     );
+ *   }
+ * });
+ *
+ * export const getTasks = query({
+ *   handler: async (ctx, args) => {
+ *     return await tasksStorage.stream(ctx, args.checkpoint, args.limit);
+ *   }
+ * });
+ * ```
+ *
+ * @template TDocument - The document type being stored (must have an id field)
+ */
+export declare class ReplicateStorage<_TDocument extends {
+    id: string;
+} = {
+    id: string;
+}> {
+    private component;
+    private collectionName;
+    /**
+     * Create a new ReplicateStorage instance scoped to a specific collection.
+     *
+     * @param component - The replicate component from your generated API
+     * @param collectionName - The name of the collection to interact with
+     *
+     * @example
+     * ```typescript
+     * const tasksStorage = new ReplicateStorage(
+     *   components.replicate,
+     *   "tasks"
+     * );
+     * ```
+     */
+    constructor(component: UseApi<typeof api>, collectionName: string);
+    /**
+     * Insert a new document into the replicate component storage.
+     *
+     * This stores the CRDT bytes in the component's internal storage table.
+     *
+     * @param ctx - Convex mutation context
+     * @param documentId - Unique identifier for the document
+     * @param crdtBytes - The CRDT binary data (from Automerge.save())
+     * @param version - Version number for conflict resolution
+     * @returns Success indicator
+     */
+    insertDocument(ctx: RunMutationCtx, documentId: string, crdtBytes: ArrayBuffer, version: number): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Update an existing document in the replicate component storage.
+     *
+     * @param ctx - Convex mutation context
+     * @param documentId - Unique identifier for the document
+     * @param crdtBytes - The CRDT binary data (from Automerge.save())
+     * @param version - Version number for conflict resolution
+     * @returns Success indicator
+     */
+    updateDocument(ctx: RunMutationCtx, documentId: string, crdtBytes: ArrayBuffer, version: number): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Delete a document from the replicate component storage.
+     * Appends deletion delta to event log.
+     *
+     * @param ctx - Convex mutation context
+     * @param documentId - Unique identifier for the document
+     * @param crdtBytes - Yjs deletion delta
+     * @param version - CRDT version number
+     * @returns Success indicator
+     */
+    deleteDocument(ctx: RunMutationCtx, documentId: string, crdtBytes: ArrayBuffer, version: number): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Stream CRDT changes for incremental replication.
+     *
+     * Retrieves CRDT bytes for documents that have been modified since the
+     * provided checkpoint, enabling incremental replication.
+     * Can be used for both polling (awaitReplication) and subscriptions (live updates).
+     *
+     * @param ctx - Convex query context
+     * @param checkpoint - Last known modification timestamp
+     * @param limit - Maximum number of changes to retrieve (default: 100)
+     * @returns Array of changes with updated checkpoint
+     */
+    stream(ctx: RunQueryCtx, checkpoint: {
+        lastModified: number;
+    }, limit?: number): Promise<{
+        changes: Array<{
+            documentId: string;
+            crdtBytes: ArrayBuffer;
+            version: number;
+            timestamp: number;
+        }>;
+        checkpoint: {
+            lastModified: number;
+        };
+        hasMore: boolean;
+    }>;
+}
+/**
+ * Re-export the component API for direct access if needed.
+ */
+export { api };
+type RunQueryCtx = {
+    runQuery: GenericQueryCtx<GenericDataModel>['runQuery'];
+};
+type RunMutationCtx = {
+    runMutation: GenericMutationCtx<GenericDataModel>['runMutation'];
+};
+export type OpaqueIds<T> = T extends GenericId<infer _T> ? string : T extends (infer U)[] ? OpaqueIds<U>[] : T extends object ? {
+    [K in keyof T]: OpaqueIds<T[K]>;
+} : T;
+export type UseApi<API> = Expand<{
+    [mod in keyof API]: API[mod] extends FunctionReference<infer FType, 'public', infer FArgs, infer FReturnType, infer FComponentPath> ? FunctionReference<FType, 'internal', OpaqueIds<FArgs>, OpaqueIds<FReturnType>, FComponentPath> : UseApi<API[mod]>;
+}>;

package/dist/component/_generated/api.js

@@ -0,0 +1,5 @@
+import { anyApi, componentsGeneric } from "convex/server";
+const api = anyApi;
+const internal = anyApi;
+const components = componentsGeneric();
+export { api, components, internal };

package/dist/component/_generated/server.js

@@ -0,0 +1,9 @@
+import { actionGeneric, httpActionGeneric, internalActionGeneric, internalMutationGeneric, internalQueryGeneric, mutationGeneric, queryGeneric } from "convex/server";
+const query = queryGeneric;
+const internalQuery = internalQueryGeneric;
+const mutation = mutationGeneric;
+const internalMutation = internalMutationGeneric;
+const action = actionGeneric;
+const internalAction = internalActionGeneric;
+const httpAction = httpActionGeneric;
+export { action, httpAction, internalAction, internalMutation, internalQuery, mutation, query };

package/dist/component/convex.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("convex/server").ComponentDefinition<any>;
+export default _default;

package/dist/component/convex.config.js

@@ -0,0 +1,3 @@
+import { defineComponent } from "convex/server";
+const convex_config = defineComponent('replicate');
+export { convex_config as default };

package/dist/component/public.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Insert a new document with CRDT bytes (Yjs format).
+ * Appends delta to event log (event sourcing pattern).
+ *
+ * @param collectionName - Collection identifier
+ * @param documentId - Unique document identifier
+ * @param crdtBytes - ArrayBuffer containing Yjs CRDT bytes (delta)
+ * @param version - CRDT version number
+ */
+export declare const insertDocument: import("convex/server").RegisteredMutation<"public", {
+    collectionName: string;
+    documentId: string;
+    crdtBytes: ArrayBuffer;
+    version: number;
+}, Promise<{
+    success: boolean;
+}>>;
+/**
+ * Update an existing document with new CRDT bytes (Yjs format).
+ * Appends delta to event log (event sourcing pattern).
+ *
+ * @param collectionName - Collection identifier
+ * @param documentId - Unique document identifier
+ * @param crdtBytes - ArrayBuffer containing Yjs CRDT bytes (delta)
+ * @param version - CRDT version number
+ */
+export declare const updateDocument: import("convex/server").RegisteredMutation<"public", {
+    collectionName: string;
+    documentId: string;
+    crdtBytes: ArrayBuffer;
+    version: number;
+}, Promise<{
+    success: boolean;
+}>>;
+/**
+ * Delete a document from CRDT storage.
+ * Appends deletion delta to event log (preserves history).
+ *
+ * @param collectionName - Collection identifier
+ * @param documentId - Unique document identifier
+ * @param crdtBytes - ArrayBuffer containing Yjs deletion delta
+ * @param version - CRDT version number
+ */
+export declare const deleteDocument: import("convex/server").RegisteredMutation<"public", {
+    collectionName: string;
+    documentId: string;
+    crdtBytes: ArrayBuffer;
+    version: number;
+}, Promise<{
+    success: boolean;
+}>>;
+/**
+ * Get complete event history for a document.
+ * Returns all CRDT deltas in chronological order.
+ *
+ * Used for:
+ * - Future recovery features (client-side)
+ * - Audit trails
+ * - Debugging
+ *
+ * @param collectionName - Collection identifier
+ * @param documentId - Unique document identifier
+ */
+export declare const getDocumentHistory: import("convex/server").RegisteredQuery<"public", {
+    collectionName: string;
+    documentId: string;
+}, Promise<{
+    crdtBytes: ArrayBuffer;
+    version: number;
+    timestamp: number;
+    operationType: string;
+}[]>>;
+/**
+ * Stream CRDT changes for incremental replication.
+ * Returns Yjs CRDT bytes for documents modified since the checkpoint.
+ * Can be used for both polling (awaitReplication) and subscriptions (live updates).
+ *
+ * @param collectionName - Collection identifier
+ * @param checkpoint - Last replication checkpoint
+ * @param limit - Maximum number of changes to return (default: 100)
+ */
+export declare const stream: import("convex/server").RegisteredQuery<"public", {
+    limit?: number | undefined;
+    collectionName: string;
+    checkpoint: {
+        lastModified: number;
+    };
+}, Promise<{
+    changes: {
+        documentId: string;
+        crdtBytes: ArrayBuffer;
+        version: number;
+        timestamp: number;
+    }[];
+    checkpoint: {
+        lastModified: number;
+    };
+    hasMore: boolean;
+}>>;

package/dist/component/public.js

@@ -0,0 +1,135 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+const insertDocument = mutation({
+    args: {
+        collectionName: v.string(),
+        documentId: v.string(),
+        crdtBytes: v.bytes(),
+        version: v.number()
+    },
+    returns: v.object({
+        success: v.boolean()
+    }),
+    handler: async (ctx, args)=>{
+        await ctx.db.insert('documents', {
+            collectionName: args.collectionName,
+            documentId: args.documentId,
+            crdtBytes: args.crdtBytes,
+            version: args.version,
+            timestamp: Date.now(),
+            operationType: 'insert'
+        });
+        return {
+            success: true
+        };
+    }
+});
+const updateDocument = mutation({
+    args: {
+        collectionName: v.string(),
+        documentId: v.string(),
+        crdtBytes: v.bytes(),
+        version: v.number()
+    },
+    returns: v.object({
+        success: v.boolean()
+    }),
+    handler: async (ctx, args)=>{
+        await ctx.db.insert('documents', {
+            collectionName: args.collectionName,
+            documentId: args.documentId,
+            crdtBytes: args.crdtBytes,
+            version: args.version,
+            timestamp: Date.now(),
+            operationType: 'update'
+        });
+        return {
+            success: true
+        };
+    }
+});
+const deleteDocument = mutation({
+    args: {
+        collectionName: v.string(),
+        documentId: v.string(),
+        crdtBytes: v.bytes(),
+        version: v.number()
+    },
+    returns: v.object({
+        success: v.boolean()
+    }),
+    handler: async (ctx, args)=>{
+        await ctx.db.insert('documents', {
+            collectionName: args.collectionName,
+            documentId: args.documentId,
+            crdtBytes: args.crdtBytes,
+            version: args.version,
+            timestamp: Date.now(),
+            operationType: 'delete'
+        });
+        return {
+            success: true
+        };
+    }
+});
+const getDocumentHistory = query({
+    args: {
+        collectionName: v.string(),
+        documentId: v.string()
+    },
+    returns: v.array(v.object({
+        crdtBytes: v.bytes(),
+        version: v.number(),
+        timestamp: v.number(),
+        operationType: v.string()
+    })),
+    handler: async (ctx, args)=>{
+        const deltas = await ctx.db.query('documents').withIndex('by_collection_document_version', (q)=>q.eq('collectionName', args.collectionName).eq('documentId', args.documentId)).order('asc').collect();
+        return deltas.map((d)=>({
+                crdtBytes: d.crdtBytes,
+                version: d.version,
+                timestamp: d.timestamp,
+                operationType: d.operationType
+            }));
+    }
+});
+const stream = query({
+    args: {
+        collectionName: v.string(),
+        checkpoint: v.object({
+            lastModified: v.number()
+        }),
+        limit: v.optional(v.number())
+    },
+    returns: v.object({
+        changes: v.array(v.object({
+            documentId: v.string(),
+            crdtBytes: v.bytes(),
+            version: v.number(),
+            timestamp: v.number()
+        })),
+        checkpoint: v.object({
+            lastModified: v.number()
+        }),
+        hasMore: v.boolean()
+    }),
+    handler: async (ctx, args)=>{
+        const limit = args.limit ?? 100;
+        const documents = await ctx.db.query('documents').withIndex('by_timestamp', (q)=>q.eq('collectionName', args.collectionName).gt('timestamp', args.checkpoint.lastModified)).order('asc').take(limit);
+        const changes = documents.map((doc)=>({
+                documentId: doc.documentId,
+                crdtBytes: doc.crdtBytes,
+                version: doc.version,
+                timestamp: doc.timestamp
+            }));
+        const newCheckpoint = {
+            lastModified: documents.length > 0 ? documents[documents.length - 1]?.timestamp ?? args.checkpoint.lastModified : args.checkpoint.lastModified
+        };
+        return {
+            changes,
+            checkpoint: newCheckpoint,
+            hasMore: documents.length === limit
+        };
+    }
+});
+export { deleteDocument, getDocumentHistory, insertDocument, stream, updateDocument };

package/dist/component/schema.d.ts

@@ -0,0 +1,22 @@
+declare const _default: import("convex/server").SchemaDefinition<{
+    documents: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        collectionName: string;
+        documentId: string;
+        crdtBytes: ArrayBuffer;
+        version: number;
+        timestamp: number;
+        operationType: string;
+    }, {
+        collectionName: import("convex/values").VString<string, "required">;
+        documentId: import("convex/values").VString<string, "required">;
+        crdtBytes: import("convex/values").VBytes<ArrayBuffer, "required">;
+        version: import("convex/values").VFloat64<number, "required">;
+        timestamp: import("convex/values").VFloat64<number, "required">;
+        operationType: import("convex/values").VString<string, "required">;
+    }, "required", "collectionName" | "documentId" | "crdtBytes" | "version" | "timestamp" | "operationType">, {
+        by_collection: ["collectionName", "_creationTime"];
+        by_collection_document_version: ["collectionName", "documentId", "version", "_creationTime"];
+        by_timestamp: ["collectionName", "timestamp", "_creationTime"];
+    }, {}, {}>;
+}, true>;
+export default _default;

package/dist/component/schema.js

@@ -0,0 +1,22 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+const schema = defineSchema({
+    documents: defineTable({
+        collectionName: v.string(),
+        documentId: v.string(),
+        crdtBytes: v.bytes(),
+        version: v.number(),
+        timestamp: v.number(),
+        operationType: v.string()
+    }).index('by_collection', [
+        'collectionName'
+    ]).index('by_collection_document_version', [
+        'collectionName',
+        'documentId',
+        'version'
+    ]).index('by_timestamp', [
+        'collectionName',
+        'timestamp'
+    ])
+});
+export { schema as default };