@trestleinc/replicate 0.1.0 → 1.1.0

package/src/client/storage.ts

@@ -1,206 +0,0 @@
-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 class ReplicateStorage<_TDocument extends { id: string } = { id: string }> {
-  /**
-   * 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(
-    private component: UseApi<typeof api>,
-    private 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
-   */
-  async insertDocument(
-    ctx: RunMutationCtx,
-    documentId: string,
-    crdtBytes: ArrayBuffer,
-    version: number
-  ): Promise<{ success: boolean }> {
-    return ctx.runMutation(this.component.public.insertDocument, {
-      collectionName: this.collectionName,
-      documentId,
-      crdtBytes,
-      version,
-    });
-  }
-
-  /**
-   * 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
-   */
-  async updateDocument(
-    ctx: RunMutationCtx,
-    documentId: string,
-    crdtBytes: ArrayBuffer,
-    version: number
-  ): Promise<{ success: boolean }> {
-    return ctx.runMutation(this.component.public.updateDocument, {
-      collectionName: this.collectionName,
-      documentId,
-      crdtBytes,
-      version,
-    });
-  }
-
-  /**
-   * 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
-   */
-  async deleteDocument(
-    ctx: RunMutationCtx,
-    documentId: string,
-    crdtBytes: ArrayBuffer,
-    version: number
-  ): Promise<{ success: boolean }> {
-    return ctx.runMutation(this.component.public.deleteDocument, {
-      collectionName: this.collectionName,
-      documentId,
-      crdtBytes,
-      version,
-    });
-  }
-
-  /**
-   * 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
-   */
-  async stream(
-    ctx: RunQueryCtx,
-    checkpoint: { lastModified: number },
-    limit?: number
-  ): Promise<{
-    changes: Array<{
-      documentId: string;
-      crdtBytes: ArrayBuffer;
-      version: number;
-      timestamp: number;
-    }>;
-    checkpoint: { lastModified: number };
-    hasMore: boolean;
-  }> {
-    return ctx.runQuery(this.component.public.stream, {
-      collectionName: this.collectionName,
-      checkpoint,
-      limit,
-    }) as any;
-  }
-}
-
-/**
- * Re-export the component API for direct access if needed.
- */
-export { api };
-
-/* Type utilities */
-
-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/src/component/_generated/api.d.ts

@@ -1,95 +0,0 @@
-/* eslint-disable */
-/**
- * Generated `api` utility.
- *
- * THIS CODE IS AUTOMATICALLY GENERATED.
- *
- * To regenerate, run `npx convex dev`.
- * @module
- */
-
-import type * as public_ from "../public.js";
-
-import type {
-  ApiFromModules,
-  FilterApi,
-  FunctionReference,
-} from "convex/server";
-
-/**
- * A utility for referencing Convex functions in your app's API.
- *
- * Usage:
- * ```js
- * const myFunctionReference = api.myModule.myFunction;
- * ```
- */
-declare const fullApi: ApiFromModules<{
-  public: typeof public_;
-}>;
-export type Mounts = {
-  public: {
-    deleteDocument: FunctionReference<
-      "mutation",
-      "public",
-      { collectionName: string; documentId: string },
-      { success: boolean }
-    >;
-    insertDocument: FunctionReference<
-      "mutation",
-      "public",
-      {
-        collectionName: string;
-        crdtBytes: ArrayBuffer;
-        documentId: string;
-        version: number;
-      },
-      { success: boolean }
-    >;
-    stream: FunctionReference<
-      "query",
-      "public",
-      {
-        checkpoint: { lastModified: number };
-        collectionName: string;
-        limit?: number;
-      },
-      {
-        changes: Array<{
-          crdtBytes: ArrayBuffer;
-          documentId: string;
-          timestamp: number;
-          version: number;
-        }>;
-        checkpoint: { lastModified: number };
-        hasMore: boolean;
-      }
-    >;
-    updateDocument: FunctionReference<
-      "mutation",
-      "public",
-      {
-        collectionName: string;
-        crdtBytes: ArrayBuffer;
-        documentId: string;
-        version: number;
-      },
-      { success: boolean }
-    >;
-  };
-};
-// For now fullApiWithMounts is only fullApi which provides
-// jump-to-definition in component client code.
-// Use Mounts for the same type without the inference.
-declare const fullApiWithMounts: typeof fullApi;
-
-export declare const api: FilterApi<
-  typeof fullApiWithMounts,
-  FunctionReference<any, "public">
->;
-export declare const internal: FilterApi<
-  typeof fullApiWithMounts,
-  FunctionReference<any, "internal">
->;
-
-export declare const components: {};

package/src/component/_generated/api.js

@@ -1,23 +0,0 @@
-/* eslint-disable */
-/**
- * Generated `api` utility.
- *
- * THIS CODE IS AUTOMATICALLY GENERATED.
- *
- * To regenerate, run `npx convex dev`.
- * @module
- */
-
-import { anyApi, componentsGeneric } from "convex/server";
-
-/**
- * A utility for referencing Convex functions in your app's API.
- *
- * Usage:
- * ```js
- * const myFunctionReference = api.myModule.myFunction;
- * ```
- */
-export const api = anyApi;
-export const internal = anyApi;
-export const components = componentsGeneric();

package/src/component/_generated/server.js

@@ -1,90 +0,0 @@
-/* eslint-disable */
-/**
- * Generated utilities for implementing server-side Convex query and mutation functions.
- *
- * THIS CODE IS AUTOMATICALLY GENERATED.
- *
- * To regenerate, run `npx convex dev`.
- * @module
- */
-
-import {
-  actionGeneric,
-  httpActionGeneric,
-  queryGeneric,
-  mutationGeneric,
-  internalActionGeneric,
-  internalMutationGeneric,
-  internalQueryGeneric,
-  componentsGeneric,
-} from "convex/server";
-
-/**
- * Define a query in this Convex app's public API.
- *
- * This function will be allowed to read your Convex database and will be accessible from the client.
- *
- * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
- * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
- */
-export const query = queryGeneric;
-
-/**
- * Define a query that is only accessible from other Convex functions (but not from the client).
- *
- * This function will be allowed to read from your Convex database. It will not be accessible from the client.
- *
- * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
- * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
- */
-export const internalQuery = internalQueryGeneric;
-
-/**
- * Define a mutation in this Convex app's public API.
- *
- * This function will be allowed to modify your Convex database and will be accessible from the client.
- *
- * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
- * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
- */
-export const mutation = mutationGeneric;
-
-/**
- * Define a mutation that is only accessible from other Convex functions (but not from the client).
- *
- * This function will be allowed to modify your Convex database. It will not be accessible from the client.
- *
- * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
- * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
- */
-export const internalMutation = internalMutationGeneric;
-
-/**
- * Define an action in this Convex app's public API.
- *
- * An action is a function which can execute any JavaScript code, including non-deterministic
- * code and code with side-effects, like calling third-party services.
- * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
- * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
- *
- * @param func - The action. It receives an {@link ActionCtx} as its first argument.
- * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
- */
-export const action = actionGeneric;
-
-/**
- * Define an action that is only accessible from other Convex functions (but not from the client).
- *
- * @param func - The function. It receives an {@link ActionCtx} as its first argument.
- * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
- */
-export const internalAction = internalActionGeneric;
-
-/**
- * Define a Convex HTTP action.
- *
- * @param func - The function. It receives an {@link ActionCtx} as its first argument, and a `Request` object
- * as its second.
- * @returns The wrapped endpoint function. Route a URL path to this function in `convex/http.js`.
- */
-export const httpAction = httpActionGeneric;

package/src/server/replication.ts

@@ -1,244 +0,0 @@
-import type { GenericDataModel } from 'convex/server';
-
-function cleanDocument(doc: unknown): unknown {
-  return Object.fromEntries(
-    Object.entries(doc as Record<string, unknown>).filter(
-      ([_, value]) => value !== undefined && value !== null
-    )
-  );
-}
-
-/**
- * Insert a document into both the CRDT component and the main application table.
- *
- * DUAL-STORAGE ARCHITECTURE:
- * This helper implements a dual-storage pattern where documents are stored in two places:
- *
- * 1. Component Storage (CRDT Layer):
- *    - Stores CRDT bytes (from Yjs) for offline-first conflict resolution
- *    - Handles concurrent updates with automatic merging
- *    - Provides the source of truth for offline changes
- *
- * 2. Main Application Table:
- *    - Stores materialized documents for efficient querying
- *    - Used by server-side Convex functions that need to query/join data
- *    - Optimized for reactive subscriptions and complex queries
- *
- * WHY BOTH?
- * - Component: Handles conflict resolution and offline replication (CRDT bytes)
- * - Main table: Enables efficient server-side queries (materialized docs)
- * - Similar to event sourcing: component = event log, main table = read model
- *
- * @param ctx - Convex mutation context
- * @param components - Generated components from Convex
- * @param tableName - Name of the main application table
- * @param args - Document data with id, crdtBytes, materializedDoc, and version
- * @returns Success indicator
- */
-export async function insertDocumentHelper<_DataModel extends GenericDataModel>(
-  ctx: unknown,
-  components: unknown,
-  tableName: string,
-  args: { id: string; crdtBytes: ArrayBuffer; materializedDoc: unknown; version: number }
-): Promise<{
-  success: boolean;
-  metadata: {
-    documentId: string;
-    timestamp: number;
-    version: number;
-    collectionName: string;
-  };
-}> {
-  // Use consistent timestamp for both writes to enable sync matching
-  const timestamp = Date.now();
-
-  // Write CRDT bytes to component
-  await (ctx as any).runMutation((components as any).replicate.public.insertDocument, {
-    collectionName: tableName,
-    documentId: args.id,
-    crdtBytes: args.crdtBytes,
-    version: args.version,
-  });
-
-  // Write materialized doc to main table
-  const db = (ctx as any).db;
-  const cleanDoc = cleanDocument(args.materializedDoc) as Record<string, unknown>;
-
-  await db.insert(tableName, {
-    id: args.id,
-    ...cleanDoc,
-    version: args.version,
-    timestamp,
-  });
-
-  // Return metadata for replication matching
-  return {
-    success: true,
-    metadata: {
-      documentId: args.id,
-      timestamp,
-      version: args.version,
-      collectionName: tableName,
-    },
-  };
-}
-
-/**
- * Update a document in both the CRDT component and the main application table.
- *
- * @param ctx - Convex mutation context
- * @param components - Generated components from Convex
- * @param tableName - Name of the main application table
- * @param args - Document data with id, crdtBytes, materializedDoc, and version
- * @returns Success indicator
- */
-export async function updateDocumentHelper<_DataModel extends GenericDataModel>(
-  ctx: unknown,
-  components: unknown,
-  tableName: string,
-  args: { id: string; crdtBytes: ArrayBuffer; materializedDoc: unknown; version: number }
-): Promise<{
-  success: boolean;
-  metadata: {
-    documentId: string;
-    timestamp: number;
-    version: number;
-    collectionName: string;
-  };
-}> {
-  // Use consistent timestamp for both writes to enable sync matching
-  const timestamp = Date.now();
-
-  // Write CRDT bytes to component
-  await (ctx as any).runMutation((components as any).replicate.public.updateDocument, {
-    collectionName: tableName,
-    documentId: args.id,
-    crdtBytes: args.crdtBytes,
-    version: args.version,
-  });
-
-  // Update materialized doc in main table
-  const db = (ctx as any).db;
-  const existing = await db
-    .query(tableName)
-    .withIndex('by_user_id', (q: unknown) => (q as any).eq('id', args.id))
-    .first();
-
-  if (!existing) {
-    throw new Error(`Document ${args.id} not found in table ${tableName}`);
-  }
-
-  const cleanDoc = cleanDocument(args.materializedDoc) as Record<string, unknown>;
-
-  await db.patch(existing._id, {
-    ...cleanDoc,
-    version: args.version,
-    timestamp,
-  });
-
-  // Return metadata for replication matching
-  return {
-    success: true,
-    metadata: {
-      documentId: args.id,
-      timestamp,
-      version: args.version,
-      collectionName: tableName,
-    },
-  };
-}
-
-/**
- * HARD delete a document from main table, APPEND deletion delta to component.
- *
- * NEW BEHAVIOR (v0.3.0):
- * - Appends deletion delta to component event log (preserves history)
- * - Physically removes document from main table (hard delete)
- * - CRDT history preserved for future recovery features
- *
- * @param ctx - Convex mutation context
- * @param components - Generated components from Convex
- * @param tableName - Name of the main application table
- * @param args - Document data with id, crdtBytes (deletion delta), and version
- * @returns Success indicator with metadata
- */
-export async function deleteDocumentHelper<_DataModel extends GenericDataModel>(
-  ctx: unknown,
-  components: unknown,
-  tableName: string,
-  args: { id: string; crdtBytes: ArrayBuffer; version: number }
-): Promise<{
-  success: boolean;
-  metadata: {
-    documentId: string;
-    timestamp: number;
-    version: number;
-    collectionName: string;
-  };
-}> {
-  const timestamp = Date.now();
-
-  // 1. Append deletion delta to component (event log)
-  await (ctx as any).runMutation((components as any).replicate.public.deleteDocument, {
-    collectionName: tableName,
-    documentId: args.id,
-    crdtBytes: args.crdtBytes,
-    version: args.version,
-  });
-
-  // 2. HARD DELETE from main table (physical removal)
-  const db = (ctx as any).db;
-  const existing = await db
-    .query(tableName)
-    .withIndex('by_user_id', (q: unknown) => (q as any).eq('id', args.id))
-    .first();
-
-  if (existing) {
-    await db.delete(existing._id);
-  }
-
-  return {
-    success: true,
-    metadata: {
-      documentId: args.id,
-      timestamp,
-      version: args.version,
-      collectionName: tableName,
-    },
-  };
-}
-
-/**
- * Stream document changes from the CRDT component storage.
- *
- * This reads CRDT bytes from the component (not the main table) to enable
- * true Y.applyUpdate() conflict resolution on the client.
- * Can be used for both polling (awaitReplication) and subscriptions (live updates).
- *
- * @param ctx - Convex query context
- * @param components - Generated components from Convex
- * @param tableName - Name of the collection
- * @param args - Checkpoint and limit for pagination
- * @returns Array of changes with CRDT bytes
- */
-export async function streamHelper<_DataModel extends GenericDataModel>(
-  ctx: unknown,
-  components: unknown,
-  tableName: string,
-  args: { checkpoint: { lastModified: number }; limit?: number }
-): Promise<{
-  changes: Array<{
-    documentId: string;
-    crdtBytes: ArrayBuffer;
-    version: number;
-    timestamp: number;
-  }>;
-  checkpoint: { lastModified: number };
-  hasMore: boolean;
-}> {
-  return (ctx as any).runQuery((components as any).replicate.public.stream, {
-    collectionName: tableName,
-    checkpoint: args.checkpoint,
-    limit: args.limit,
-  });
-}