@trestleinc/replicate 0.1.0 → 1.1.0

package/LICENSE.package

@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-1.  Definitions.
-
-    "License" shall mean the terms and conditions for use, reproduction,
-    and distribution as defined by Sections 1 through 9 of this document.
-
-    "Licensor" shall mean the copyright owner or entity authorized by
-    the copyright owner that is granting the License.
-
-    "Legal Entity" shall mean the union of the acting entity and all
-    other entities that control, are controlled by, or are under common
-    control with that entity. For the purposes of this definition,
-    "control" means (i) the power, direct or indirect, to cause the
-    direction or management of such entity, whether by contract or
-    otherwise, or (ii) ownership of fifty percent (50%) or more of the
-    outstanding shares, or (iii) beneficial ownership of such entity.
-
-    "You" (or "Your") shall mean an individual or Legal Entity
-    exercising permissions granted by this License.
-
-    "Source" form shall mean the preferred form for making modifications,
-    including but not limited to software source code, documentation
-    source, and configuration files.
-
-    "Object" form shall mean any form resulting from mechanical
-    transformation or translation of a Source form, including but
-    not limited to compiled object code, generated documentation,
-    and conversions to other media types.
-
-    "Work" shall mean the work of authorship, whether in Source or
-    Object form, made available under the License, as indicated by a
-    copyright notice that is included in or attached to the work
-    (an example is provided in the Appendix below).
-
-    "Derivative Works" shall mean any work, whether in Source or Object
-    form, that is based on (or derived from) the Work and for which the
-    editorial revisions, annotations, elaborations, or other modifications
-    represent, as a whole, an original work of authorship. For the purposes
-    of this License, Derivative Works shall not include works that remain
-    separable from, or merely link (or bind by name) to the interfaces of,
-    the Work and Derivative Works thereof.
-
-    "Contribution" shall mean any work of authorship, including
-    the original version of the Work and any modifications or additions
-    to that Work or Derivative Works thereof, that is intentionally
-    submitted to Licensor for inclusion in the Work by the copyright owner
-    or by an individual or Legal Entity authorized to submit on behalf of
-    the copyright owner. For the purposes of this definition, "submitted"
-    means any form of electronic, verbal, or written communication sent
-    to the Licensor or its representatives, including but not limited to
-    communication on electronic mailing lists, source code control systems,
-    and issue tracking systems that are managed by, or on behalf of, the
-    Licensor for the purpose of discussing and improving the Work, but
-    excluding communication that is conspicuously marked or otherwise
-    designated in writing by the copyright owner as "Not a Contribution."
-
-    "Contributor" shall mean Licensor and any individual or Legal Entity
-    on behalf of whom a Contribution has been received by Licensor and
-    subsequently incorporated within the Work.
-
-2.  Grant of Copyright License. Subject to the terms and conditions of
-    this License, each Contributor hereby grants to You a perpetual,
-    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-    copyright license to reproduce, prepare Derivative Works of,
-    publicly display, publicly perform, sublicense, and distribute the
-    Work and such Derivative Works in Source or Object form.
-
-3.  Grant of Patent License. Subject to the terms and conditions of
-    this License, each Contributor hereby grants to You a perpetual,
-    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-    (except as stated in this section) patent license to make, have made,
-    use, offer to sell, sell, import, and otherwise transfer the Work,
-    where such license applies only to those patent claims licensable
-    by such Contributor that are necessarily infringed by their
-    Contribution(s) alone or by combination of their Contribution(s)
-    with the Work to which such Contribution(s) was submitted. If You
-    institute patent litigation against any entity (including a
-    cross-claim or counterclaim in a lawsuit) alleging that the Work
-    or a Contribution incorporated within the Work constitutes direct
-    or contributory patent infringement, then any patent licenses
-    granted to You under this License for that Work shall terminate
-    as of the date such litigation is filed.
-
-4.  Redistribution. You may reproduce and distribute copies of the
-    Work or Derivative Works thereof in any medium, with or without
-    modifications, and in Source or Object form, provided that You
-    meet the following conditions:
-
-    (a) You must give any other recipients of the Work or
-    Derivative Works a copy of this License; and
-
-    (b) You must cause any modified files to carry prominent notices
-    stating that You changed the files; and
-
-    (c) You must retain, in the Source form of any Derivative Works
-    that You distribute, all copyright, patent, trademark, and
-    attribution notices from the Source form of the Work,
-    excluding those notices that do not pertain to any part of
-    the Derivative Works; and
-
-    (d) If the Work includes a "NOTICE" text file as part of its
-    distribution, then any Derivative Works that You distribute must
-    include a readable copy of the attribution notices contained
-    within such NOTICE file, excluding those notices that do not
-    pertain to any part of the Derivative Works, in at least one
-    of the following places: within a NOTICE text file distributed
-    as part of the Derivative Works; within the Source form or
-    documentation, if provided along with the Derivative Works; or,
-    within a display generated by the Derivative Works, if and
-    wherever such third-party notices normally appear. The contents
-    of the NOTICE file are for informational purposes only and
-    do not modify the License. You may add Your own attribution
-    notices within Derivative Works that You distribute, alongside
-    or as an addendum to the NOTICE text from the Work, provided
-    that such additional attribution notices cannot be construed
-    as modifying the License.
-
-    You may add Your own copyright statement to Your modifications and
-    may provide additional or different license terms and conditions
-    for use, reproduction, or distribution of Your modifications, or
-    for any such Derivative Works as a whole, provided Your use,
-    reproduction, and distribution of the Work otherwise complies with
-    the conditions stated in this License.
-
-5.  Submission of Contributions. Unless You explicitly state otherwise,
-    any Contribution intentionally submitted for inclusion in the Work
-    by You to the Licensor shall be under the terms and conditions of
-    this License, without any additional terms or conditions.
-    Notwithstanding the above, nothing herein shall supersede or modify
-    the terms of any separate license agreement you may have executed
-    with Licensor regarding such Contributions.
-
-6.  Trademarks. This License does not grant permission to use the trade
-    names, trademarks, service marks, or product names of the Licensor,
-    except as required for reasonable and customary use in describing the
-    origin of the Work and reproducing the content of the NOTICE file.
-
-7.  Disclaimer of Warranty. Unless required by applicable law or
-    agreed to in writing, Licensor provides the Work (and each
-    Contributor provides its Contributions) on an "AS IS" BASIS,
-    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-    implied, including, without limitation, any warranties or conditions
-    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-    PARTICULAR PURPOSE. You are solely responsible for determining the
-    appropriateness of using or redistributing the Work and assume any
-    risks associated with Your exercise of permissions under this License.
-
-8.  Limitation of Liability. In no event and under no legal theory,
-    whether in tort (including negligence), contract, or otherwise,
-    unless required by applicable law (such as deliberate and grossly
-    negligent acts) or agreed to in writing, shall any Contributor be
-    liable to You for damages, including any direct, indirect, special,
-    incidental, or consequential damages of any character arising as a
-    result of this License or out of the use or inability to use the
-    Work (including but not limited to damages for loss of goodwill,
-    work stoppage, computer failure or malfunction, or any and all
-    other commercial damages or losses), even if such Contributor
-    has been advised of the possibility of such damages.
-
-9.  Accepting Warranty or Additional Liability. While redistributing
-    the Work or Derivative Works thereof, You may choose to offer,
-    and charge a fee for, acceptance of support, warranty, indemnity,
-    or other liability obligations and/or rights consistent with this
-    License. However, in accepting such obligations, You may act only
-    on Your own behalf and on Your sole responsibility, not on behalf
-    of any other Contributor, and only if You agree to indemnify,
-    defend, and hold each Contributor harmless for any liability
-    incurred by, or claims asserted against, such Contributor by reason
-    of your accepting any such warranty or additional liability.
-
-END OF TERMS AND CONDITIONS
-
-APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-Copyright 2025 Trestle Inc
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.

package/dist/client/storage.d.ts

@@ -1,143 +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 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/server/replication.d.ts

@@ -1,122 +0,0 @@
-import type { GenericDataModel } from 'convex/server';
-/**
- * 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 declare 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;
-    };
-}>;
-/**
- * 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 declare 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;
-    };
-}>;
-/**
- * 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 declare 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;
-    };
-}>;
-/**
- * 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 declare 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;
-}>;

package/dist/server/ssr.d.ts

@@ -1,79 +0,0 @@
-/**
- * Server-Side Rendering (SSR) Utilities
- *
- * This module provides utilities for loading collection data during
- * server-side rendering. Use `loadCollection` with an explicit config
- * object for clarity and type safety.
- *
- * @module ssr
- * @example
- * ```typescript
- * import { loadCollection } from '@convex-replicate/core/ssr';
- * import { api } from '../convex/_generated/api';
- *
- * const tasks = await loadCollection<Task>(httpClient, {
- *   api: api.tasks,
- *   collection: 'tasks',
- *   limit: 100,
- * });
- * ```
- */
-import type { ConvexHttpClient } from 'convex/browser';
-import type { FunctionReference } from 'convex/server';
-/**
- * API module shape expected by loadCollection.
- *
- * This should match the generated API module for your collection
- * (e.g., api.tasks, api.users, etc.)
- */
-export type CollectionAPI = {
-    stream: FunctionReference<'query', 'public' | 'internal'>;
-};
-/**
- * Configuration for loading collection data during SSR.
- */
-export interface LoadCollectionConfig {
-    /** The API module for the collection (e.g., api.tasks) */
-    api: CollectionAPI;
-    /** The collection name (should match the API module name) */
-    collection: string;
-    /** Maximum number of items to load (default: 100) */
-    limit?: number;
-}
-/**
- * Load collection data for server-side rendering.
- *
- * **IMPORTANT**: This function is currently limited because `stream` only returns
- * CRDT bytes, not materialized documents. For most SSR use cases, it's recommended to
- * create a separate query that reads from your main table instead.
- *
- * @deprecated Consider creating a dedicated SSR query instead. See example below.
- *
- * @param httpClient - Convex HTTP client for server-side queries
- * @param config - Configuration object with api, collection, and options
- * @returns Promise resolving to array of items from the collection
- *
- * @example
- * **Recommended SSR Pattern:**
- * ```typescript
- * // convex/tasks.ts
- * export const list = query({
- *   handler: async (ctx) => {
- *     return await ctx.db
- *       .query('tasks')
- *       .filter((q) => q.neq(q.field('deleted'), true))
- *       .collect();
- *   },
- * });
- *
- * // In your route loader
- * import { ConvexHttpClient } from 'convex/browser';
- * import { api } from '../convex/_generated/api';
- *
- * const httpClient = new ConvexHttpClient(import.meta.env.VITE_CONVEX_URL);
- * const tasks = await httpClient.query(api.tasks.list);
- * ```
- */
-export declare function loadCollection<TItem extends {
-    id: string;
-}>(httpClient: ConvexHttpClient, config: LoadCollectionConfig): Promise<ReadonlyArray<TItem>>;

package/dist/ssr.js

@@ -1,19 +0,0 @@
-async function loadCollection(httpClient, config) {
-    const result = await httpClient.query(config.api.stream, {
-        collectionName: config.collection,
-        checkpoint: {
-            lastModified: 0
-        },
-        limit: config.limit ?? 100
-    });
-    const items = [];
-    for (const change of result.changes){
-        const item = {
-            id: change.documentId,
-            ...change.document
-        };
-        items.push(item);
-    }
-    return items;
-}
-export { loadCollection };