@trestleinc/replicate 1.1.0 → 1.1.2-preview.0

package/dist/server/builder.d.ts

@@ -1,94 +0,0 @@
-import type { GenericMutationCtx, GenericQueryCtx, GenericDataModel } from 'convex/server';
-/**
- * Configuration for replicate handlers (without component - used with factory pattern).
- */
-export interface ReplicateConfig<T extends object> {
-    collection: string;
-    /** Size threshold for auto-compaction (default: 5MB). Set to 0 to disable. */
-    compaction?: {
-        threshold?: number;
-    };
-    hooks?: {
-        evalRead?: (ctx: GenericQueryCtx<GenericDataModel>, collection: string) => void | Promise<void>;
-        evalWrite?: (ctx: GenericMutationCtx<GenericDataModel>, doc: T) => void | Promise<void>;
-        evalRemove?: (ctx: GenericMutationCtx<GenericDataModel>, docId: string) => void | Promise<void>;
-        onStream?: (ctx: GenericQueryCtx<GenericDataModel>, result: any) => void | Promise<void>;
-        onInsert?: (ctx: GenericMutationCtx<GenericDataModel>, doc: T) => void | Promise<void>;
-        onUpdate?: (ctx: GenericMutationCtx<GenericDataModel>, doc: T) => void | Promise<void>;
-        onRemove?: (ctx: GenericMutationCtx<GenericDataModel>, docId: string) => void | Promise<void>;
-        transform?: (docs: T[]) => T[] | Promise<T[]>;
-    };
-}
-/**
- * Create a replicate function bound to your component. Call this once in your
- * convex/replicate.ts file, then use the returned function for all collections.
- *
- * @example
- * ```typescript
- * // convex/replicate.ts (create once)
- * import { replicate } from '@trestleinc/replicate/server';
- * import { components } from './_generated/api';
- *
- * export const tasks = replicate(components.replicate)<Task>({ collection: 'tasks' });
- *
- * // Or bind once and reuse:
- * const r = replicate(components.replicate);
- * export const tasks = r<Task>({ collection: 'tasks' });
- * export const notebooks = r<Notebook>({ collection: 'notebooks' });
- * ```
- */
-export declare function replicate(component: any): <T extends object>(config: ReplicateConfig<T>) => {
-    stream: import("convex/server").RegisteredQuery<"public", {
-        limit?: number | undefined;
-        vector?: ArrayBuffer | undefined;
-        checkpoint: {
-            lastModified: number;
-        };
-    }, Promise<any>>;
-    material: import("convex/server").RegisteredQuery<"public", {}, Promise<{
-        documents: T[];
-        checkpoint?: {
-            lastModified: number;
-        } | undefined;
-        count: number;
-        crdtBytes?: ArrayBuffer;
-    }>>;
-    recovery: import("convex/server").RegisteredQuery<"public", {
-        clientStateVector: ArrayBuffer;
-    }, Promise<any>>;
-    insert: import("convex/server").RegisteredMutation<"public", {
-        documentId: string;
-        crdtBytes: ArrayBuffer;
-        materializedDoc: any;
-    }, Promise<{
-        success: boolean;
-        metadata: {
-            documentId: string;
-            timestamp: number;
-            collection: string;
-        };
-    }>>;
-    update: import("convex/server").RegisteredMutation<"public", {
-        documentId: string;
-        crdtBytes: ArrayBuffer;
-        materializedDoc: any;
-    }, Promise<{
-        success: boolean;
-        metadata: {
-            documentId: string;
-            timestamp: number;
-            collection: string;
-        };
-    }>>;
-    remove: import("convex/server").RegisteredMutation<"public", {
-        documentId: string;
-        crdtBytes: ArrayBuffer;
-    }, Promise<{
-        success: boolean;
-        metadata: {
-            documentId: string;
-            timestamp: number;
-            collection: string;
-        };
-    }>>;
-};

package/dist/server/schema.d.ts

@@ -1,27 +0,0 @@
-/** Fields automatically added to replicated tables */
-export type ReplicationFields = {
-    timestamp: number;
-};
-export declare const prose: () => import("convex/values").VObject<{
-    content?: any[] | undefined;
-    type: "doc";
-}, {
-    type: import("convex/values").VLiteral<"doc", "required">;
-    content: import("convex/values").VArray<any[] | undefined, import("convex/values").VAny<any, "required", string>, "optional">;
-}, "required", "type" | "content">;
-/**
- * Define a table with automatic timestamp field for replication.
- * All replicated tables must have an `id` field and define a `by_doc_id` index.
- *
- * @example
- * ```typescript
- * // convex/schema.ts
- * export default defineSchema({
- *   tasks: table(
- *     { id: v.string(), text: v.string(), isCompleted: v.boolean() },
- *     (t) => t.index('by_doc_id', ['id']).index('by_completed', ['isCompleted'])
- *   ),
- * });
- * ```
- */
-export declare function table(userFields: Record<string, any>, applyIndexes?: (table: any) => any): any;

package/dist/server/storage.d.ts

@@ -1,80 +0,0 @@
-import type { GenericMutationCtx, GenericQueryCtx, GenericDataModel } from 'convex/server';
-export declare class Replicate<T extends object> {
-    component: any;
-    collectionName: string;
-    private options?;
-    constructor(component: any, collectionName: string, options?: {
-        threshold?: number;
-    } | undefined);
-    createStreamQuery(opts?: {
-        evalRead?: (ctx: GenericQueryCtx<GenericDataModel>, collection: string) => void | Promise<void>;
-        onStream?: (ctx: GenericQueryCtx<GenericDataModel>, result: any) => void | Promise<void>;
-    }): import("convex/server").RegisteredQuery<"public", {
-        limit?: number | undefined;
-        vector?: ArrayBuffer | undefined;
-        checkpoint: {
-            lastModified: number;
-        };
-    }, Promise<any>>;
-    createSSRQuery(opts?: {
-        evalRead?: (ctx: GenericQueryCtx<GenericDataModel>, collection: string) => void | Promise<void>;
-        transform?: (docs: T[]) => T[] | Promise<T[]>;
-        includeCRDTState?: boolean;
-    }): import("convex/server").RegisteredQuery<"public", {}, Promise<{
-        documents: T[];
-        checkpoint?: {
-            lastModified: number;
-        };
-        count: number;
-        crdtBytes?: ArrayBuffer;
-    }>>;
-    createInsertMutation(opts?: {
-        evalWrite?: (ctx: GenericMutationCtx<GenericDataModel>, doc: T) => void | Promise<void>;
-        onInsert?: (ctx: GenericMutationCtx<GenericDataModel>, doc: T) => void | Promise<void>;
-    }): import("convex/server").RegisteredMutation<"public", {
-        documentId: string;
-        crdtBytes: ArrayBuffer;
-        materializedDoc: any;
-    }, Promise<{
-        success: boolean;
-        metadata: {
-            documentId: string;
-            timestamp: number;
-            collection: string;
-        };
-    }>>;
-    createUpdateMutation(opts?: {
-        evalWrite?: (ctx: GenericMutationCtx<GenericDataModel>, doc: T) => void | Promise<void>;
-        onUpdate?: (ctx: GenericMutationCtx<GenericDataModel>, doc: T) => void | Promise<void>;
-    }): import("convex/server").RegisteredMutation<"public", {
-        documentId: string;
-        crdtBytes: ArrayBuffer;
-        materializedDoc: any;
-    }, Promise<{
-        success: boolean;
-        metadata: {
-            documentId: string;
-            timestamp: number;
-            collection: string;
-        };
-    }>>;
-    createRemoveMutation(opts?: {
-        evalRemove?: (ctx: GenericMutationCtx<GenericDataModel>, docId: string) => void | Promise<void>;
-        onRemove?: (ctx: GenericMutationCtx<GenericDataModel>, docId: string) => void | Promise<void>;
-    }): import("convex/server").RegisteredMutation<"public", {
-        documentId: string;
-        crdtBytes: ArrayBuffer;
-    }, Promise<{
-        success: boolean;
-        metadata: {
-            documentId: string;
-            timestamp: number;
-            collection: string;
-        };
-    }>>;
-    createRecoveryQuery(opts?: {
-        evalRead?: (ctx: GenericQueryCtx<GenericDataModel>, collection: string) => void | Promise<void>;
-    }): import("convex/server").RegisteredQuery<"public", {
-        clientStateVector: ArrayBuffer;
-    }, Promise<any>>;
-}

package/dist/server.js

@@ -1,281 +0,0 @@
-import { v } from "convex/values";
-import { defineTable, mutationGeneric, queryGeneric } from "convex/server";
-class Replicate {
-    component;
-    collectionName;
-    options;
-    constructor(component, collectionName, options){
-        this.component = component;
-        this.collectionName = collectionName;
-        this.options = options;
-    }
-    createStreamQuery(opts) {
-        const component = this.component;
-        const collection = this.collectionName;
-        return queryGeneric({
-            args: {
-                checkpoint: v.object({
-                    lastModified: v.number()
-                }),
-                limit: v.optional(v.number()),
-                vector: v.optional(v.bytes())
-            },
-            returns: v.object({
-                changes: v.array(v.object({
-                    documentId: v.optional(v.string()),
-                    crdtBytes: v.bytes(),
-                    version: v.number(),
-                    timestamp: v.number(),
-                    operationType: v.string()
-                })),
-                checkpoint: v.object({
-                    lastModified: v.number()
-                }),
-                hasMore: v.boolean()
-            }),
-            handler: async (ctx, args)=>{
-                if (opts?.evalRead) await opts.evalRead(ctx, collection);
-                const result = await ctx.runQuery(component.public.stream, {
-                    collection,
-                    checkpoint: args.checkpoint,
-                    limit: args.limit,
-                    vector: args.vector
-                });
-                if (opts?.onStream) await opts.onStream(ctx, result);
-                return result;
-            }
-        });
-    }
-    createSSRQuery(opts) {
-        const collection = this.collectionName;
-        const component = this.component;
-        return queryGeneric({
-            args: {},
-            returns: v.object({
-                documents: v.any(),
-                checkpoint: v.optional(v.object({
-                    lastModified: v.number()
-                })),
-                count: v.number(),
-                crdtBytes: v.optional(v.bytes())
-            }),
-            handler: async (ctx)=>{
-                if (opts?.evalRead) await opts.evalRead(ctx, collection);
-                let docs = await ctx.db.query(collection).collect();
-                if (opts?.transform) docs = await opts.transform(docs);
-                const latestTimestamp = docs.length > 0 ? Math.max(...docs.map((doc)=>doc.timestamp || 0)) : 0;
-                const response = {
-                    documents: docs,
-                    checkpoint: latestTimestamp > 0 ? {
-                        lastModified: latestTimestamp
-                    } : void 0,
-                    count: docs.length
-                };
-                if (opts?.includeCRDTState) {
-                    const crdtState = await ctx.runQuery(component.public.getInitialState, {
-                        collection
-                    });
-                    if (crdtState) {
-                        response.crdtBytes = crdtState.crdtBytes;
-                        response.checkpoint = crdtState.checkpoint;
-                    }
-                }
-                return response;
-            }
-        });
-    }
-    createInsertMutation(opts) {
-        const component = this.component;
-        const collection = this.collectionName;
-        const threshold = this.options?.threshold;
-        return mutationGeneric({
-            args: {
-                documentId: v.string(),
-                crdtBytes: v.bytes(),
-                materializedDoc: v.any()
-            },
-            returns: v.object({
-                success: v.boolean(),
-                metadata: v.any()
-            }),
-            handler: async (ctx, args)=>{
-                const doc = args.materializedDoc;
-                if (opts?.evalWrite) await opts.evalWrite(ctx, doc);
-                const version = Date.now();
-                await ctx.runMutation(component.public.insertDocument, {
-                    collection,
-                    documentId: args.documentId,
-                    crdtBytes: args.crdtBytes,
-                    version,
-                    threshold
-                });
-                await ctx.db.insert(collection, {
-                    id: args.documentId,
-                    ...args.materializedDoc,
-                    timestamp: Date.now()
-                });
-                if (opts?.onInsert) await opts.onInsert(ctx, doc);
-                return {
-                    success: true,
-                    metadata: {
-                        documentId: args.documentId,
-                        timestamp: Date.now(),
-                        collection
-                    }
-                };
-            }
-        });
-    }
-    createUpdateMutation(opts) {
-        const component = this.component;
-        const collection = this.collectionName;
-        const threshold = this.options?.threshold;
-        return mutationGeneric({
-            args: {
-                documentId: v.string(),
-                crdtBytes: v.bytes(),
-                materializedDoc: v.any()
-            },
-            returns: v.object({
-                success: v.boolean(),
-                metadata: v.any()
-            }),
-            handler: async (ctx, args)=>{
-                const doc = args.materializedDoc;
-                if (opts?.evalWrite) await opts.evalWrite(ctx, doc);
-                const version = Date.now();
-                await ctx.runMutation(component.public.updateDocument, {
-                    collection,
-                    documentId: args.documentId,
-                    crdtBytes: args.crdtBytes,
-                    version,
-                    threshold
-                });
-                const existing = await ctx.db.query(collection).withIndex('by_doc_id', (q)=>q.eq('id', args.documentId)).first();
-                if (existing) await ctx.db.patch(collection, existing._id, {
-                    ...args.materializedDoc,
-                    timestamp: Date.now()
-                });
-                if (opts?.onUpdate) await opts.onUpdate(ctx, doc);
-                return {
-                    success: true,
-                    metadata: {
-                        documentId: args.documentId,
-                        timestamp: Date.now(),
-                        collection
-                    }
-                };
-            }
-        });
-    }
-    createRemoveMutation(opts) {
-        const component = this.component;
-        const collection = this.collectionName;
-        const threshold = this.options?.threshold;
-        return mutationGeneric({
-            args: {
-                documentId: v.string(),
-                crdtBytes: v.bytes()
-            },
-            returns: v.object({
-                success: v.boolean(),
-                metadata: v.any()
-            }),
-            handler: async (ctx, args)=>{
-                const documentId = args.documentId;
-                if (opts?.evalRemove) await opts.evalRemove(ctx, documentId);
-                const version = Date.now();
-                await ctx.runMutation(component.public.deleteDocument, {
-                    collection,
-                    documentId: documentId,
-                    crdtBytes: args.crdtBytes,
-                    version,
-                    threshold
-                });
-                const existing = await ctx.db.query(collection).withIndex('by_doc_id', (q)=>q.eq('id', documentId)).first();
-                if (existing) await ctx.db.delete(collection, existing._id);
-                if (opts?.onRemove) await opts.onRemove(ctx, documentId);
-                return {
-                    success: true,
-                    metadata: {
-                        documentId: documentId,
-                        timestamp: Date.now(),
-                        collection
-                    }
-                };
-            }
-        });
-    }
-    createRecoveryQuery(opts) {
-        const component = this.component;
-        const collection = this.collectionName;
-        return queryGeneric({
-            args: {
-                clientStateVector: v.bytes()
-            },
-            returns: v.object({
-                diff: v.optional(v.bytes()),
-                serverStateVector: v.bytes()
-            }),
-            handler: async (ctx, args)=>{
-                if (opts?.evalRead) await opts.evalRead(ctx, collection);
-                return await ctx.runQuery(component.public.recovery, {
-                    collection,
-                    clientStateVector: args.clientStateVector
-                });
-            }
-        });
-    }
-}
-function replicate(component) {
-    return function(config) {
-        return replicateInternal(component, config);
-    };
-}
-function replicateInternal(component, config) {
-    const storage = new Replicate(component, config.collection, {
-        threshold: config.compaction?.threshold
-    });
-    return {
-        stream: storage.createStreamQuery({
-            evalRead: config.hooks?.evalRead,
-            onStream: config.hooks?.onStream
-        }),
-        material: storage.createSSRQuery({
-            evalRead: config.hooks?.evalRead,
-            transform: config.hooks?.transform
-        }),
-        recovery: storage.createRecoveryQuery({
-            evalRead: config.hooks?.evalRead
-        }),
-        insert: storage.createInsertMutation({
-            evalWrite: config.hooks?.evalWrite,
-            onInsert: config.hooks?.onInsert
-        }),
-        update: storage.createUpdateMutation({
-            evalWrite: config.hooks?.evalWrite,
-            onUpdate: config.hooks?.onUpdate
-        }),
-        remove: storage.createRemoveMutation({
-            evalRemove: config.hooks?.evalRemove,
-            onRemove: config.hooks?.onRemove
-        })
-    };
-}
-const prose = ()=>v.object({
-        type: v.literal('doc'),
-        content: v.optional(v.array(v.any()))
-    });
-function table(userFields, applyIndexes) {
-    const tbl = defineTable({
-        ...userFields,
-        timestamp: v.number()
-    });
-    if (applyIndexes) return applyIndexes(tbl);
-    return tbl;
-}
-const schema = {
-    table: table,
-    prose: prose
-};
-export { replicate, schema };

package/dist/shared/types.d.ts

@@ -1,50 +0,0 @@
-/**
- * Shared types for @trestleinc/replicate
- *
- * These types are used across client, server, and component code.
- * They are safe to import in any environment (browser, Node.js, Convex).
- */
-/** Marker used during insert/update to signal a fragment field */
-export interface FragmentValue {
-    __xmlFragment: true;
-    content?: XmlFragmentJSON;
-}
-/** ProseMirror-compatible JSON for XmlFragment serialization */
-export interface XmlFragmentJSON {
-    type: "doc";
-    content?: XmlNodeJSON[];
-}
-/** ProseMirror node structure */
-export interface XmlNodeJSON {
-    type: string;
-    attrs?: Record<string, unknown>;
-    content?: XmlNodeJSON[];
-    text?: string;
-    marks?: {
-        type: string;
-        attrs?: Record<string, unknown>;
-    }[];
-}
-/** Operation type for streaming changes */
-export declare enum OperationType {
-    Delta = "delta",
-    Snapshot = "snapshot"
-}
-/**
- * Extract field names from T where the value type is XmlFragmentJSON.
- * Used for type-safe prose field configuration.
- *
- * @example
- * ```typescript
- * interface Notebook {
- *   id: string;
- *   title: string;
- *   content: XmlFragmentJSON;
- * }
- *
- * type Fields = ProseFields<Notebook>; // 'content'
- * ```
- */
-export type ProseFields<T> = {
-    [K in keyof T]: T[K] extends XmlFragmentJSON ? K : never;
-}[keyof T];

package/dist/shared/types.js

@@ -1,6 +0,0 @@
-var types_OperationType = /*#__PURE__*/ function(OperationType) {
-    OperationType["Delta"] = "delta";
-    OperationType["Snapshot"] = "snapshot";
-    return OperationType;
-}({});
-export { types_OperationType as OperationType };

package/dist/shared.js

@@ -1,6 +0,0 @@
-var types_OperationType = /*#__PURE__*/ function(OperationType) {
-    OperationType["Delta"] = "delta";
-    OperationType["Snapshot"] = "snapshot";
-    return OperationType;
-}({});
-export { types_OperationType as OperationType };

package/src/client/persistence/adapters/index.ts

@@ -1,8 +0,0 @@
-/**
- * SQLite adapter wrappers for different platforms.
- *
- * These are wrapper classes - the consuming app imports and initializes
- * the actual database packages, then passes them to these wrappers.
- */
-export { SqlJsAdapter, type SqlJsDatabase, type SqlJsAdapterOptions } from './sqljs.js';
-export { OPSqliteAdapter, type OPSQLiteDatabase } from './opsqlite.js';

package/src/client/persistence/adapters/opsqlite.ts

@@ -1,54 +0,0 @@
-/**
- * op-sqlite adapter wrapper for React Native SQLite.
- *
- * The consuming app imports @op-engineering/op-sqlite and opens the database,
- * then passes it to this wrapper.
- *
- * @example
- * ```typescript
- * import { open } from '@op-engineering/op-sqlite';
- * import { OPSqliteAdapter } from '@trestleinc/replicate/client';
- *
- * const db = open({ name: 'myapp.db' });
- * const adapter = new OPSqliteAdapter(db);
- * ```
- */
-import type { SqliteAdapter } from '../sqlite-level.js';
-
-/**
- * Interface for op-sqlite Database.
- * Consumer must install @op-engineering/op-sqlite and pass a Database instance.
- */
-export interface OPSQLiteDatabase {
-  execute(sql: string, params?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
-  close(): void;
-}
-
-/**
- * Wraps an op-sqlite Database as a SqliteAdapter.
- *
- * @example
- * ```typescript
- * import { open } from '@op-engineering/op-sqlite';
- * import { OPSqliteAdapter } from '@trestleinc/replicate/client';
- *
- * const db = open({ name: 'myapp.db' });
- * const adapter = new OPSqliteAdapter(db);
- * ```
- */
-export class OPSqliteAdapter implements SqliteAdapter {
-  private db: OPSQLiteDatabase;
-
-  constructor(db: OPSQLiteDatabase) {
-    this.db = db;
-  }
-
-  async execute(sql: string, params?: unknown[]): Promise<{ rows: Record<string, unknown>[] }> {
-    const result = await this.db.execute(sql, params);
-    return { rows: result.rows || [] };
-  }
-
-  close(): void {
-    this.db.close();
-  }
-}