@trestleinc/replicate 0.1.0

package/src/client/storage.ts

@@ -0,0 +1,206 @@
+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

@@ -0,0 +1,95 @@
+/* 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

@@ -0,0 +1,23 @@
+/* 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/dataModel.d.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/component/_generated/server.d.ts

@@ -0,0 +1,149 @@
+/* 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 {
+  ActionBuilder,
+  AnyComponents,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+  FunctionReference,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+type GenericCtx =
+  | GenericActionCtx<DataModel>
+  | GenericMutationCtx<DataModel>
+  | GenericQueryCtx<DataModel>;
+
+/**
+ * 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 declare const query: QueryBuilder<DataModel, "public">;
+
+/**
+ * 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 declare const internalQuery: QueryBuilder<DataModel, "internal">;
+
+/**
+ * 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 declare const mutation: MutationBuilder<DataModel, "public">;
+
+/**
+ * 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 declare const internalMutation: MutationBuilder<DataModel, "internal">;
+
+/**
+ * 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 declare const action: ActionBuilder<DataModel, "public">;
+
+/**
+ * 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 declare const internalAction: ActionBuilder<DataModel, "internal">;
+
+/**
+ * Define an HTTP action.
+ *
+ * This function will be used to respond to HTTP requests received by a Convex
+ * deployment if the requests matches the path and method where this action
+ * is routed. Be sure to route your action in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export declare const httpAction: HttpActionBuilder;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * This differs from the {@link MutationCtx} because all of the services are
+ * read-only.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/_generated/server.js

@@ -0,0 +1,90 @@
+/* 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/component/convex.config.ts

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