@trestleinc/replicate 1.1.2 → 1.2.0-preview.0

package/dist/server/index.js

@@ -1,368 +0,0 @@
-import { v } from "convex/values";
-import { defineTable, mutationGeneric, queryGeneric } from "convex/server";
-
-//#region src/shared/types.ts
-const SIZE_MULTIPLIERS = {
-	kb: 1024,
-	mb: 1024 ** 2,
-	gb: 1024 ** 3
-};
-const DURATION_MULTIPLIERS = {
-	m: 6e4,
-	h: 36e5,
-	d: 864e5
-};
-function parseSize(s) {
-	const match = /^(\d+)(kb|mb|gb)$/i.exec(s);
-	if (!match) throw new Error(`Invalid size: ${s}`);
-	const [, num, unit] = match;
-	return parseInt(num) * SIZE_MULTIPLIERS[unit.toLowerCase()];
-}
-function parseDuration(s) {
-	const match = /^(\d+)(m|h|d)$/i.exec(s);
-	if (!match) throw new Error(`Invalid duration: ${s}`);
-	const [, num, unit] = match;
-	return parseInt(num) * DURATION_MULTIPLIERS[unit.toLowerCase()];
-}
-
-//#endregion
-//#region src/server/storage.ts
-const BYTES_PER_MB = 1024 * 1024;
-const MS_PER_HOUR = 3600 * 1e3;
-const DEFAULT_SIZE_THRESHOLD_5MB = 5 * BYTES_PER_MB;
-const DEFAULT_PEER_TIMEOUT_24H = 24 * MS_PER_HOUR;
-var Replicate = class {
-	sizeThreshold;
-	peerTimeout;
-	constructor(component, collectionName, compaction) {
-		this.component = component;
-		this.collectionName = collectionName;
-		this.sizeThreshold = compaction?.sizeThreshold ? parseSize(compaction.sizeThreshold) : DEFAULT_SIZE_THRESHOLD_5MB;
-		this.peerTimeout = compaction?.peerTimeout ? parseDuration(compaction.peerTimeout) : DEFAULT_PEER_TIMEOUT_24H;
-	}
-	createStreamQuery(opts) {
-		const component = this.component;
-		const collection = this.collectionName;
-		return queryGeneric({
-			args: {
-				cursor: v.number(),
-				limit: v.optional(v.number()),
-				sizeThreshold: v.optional(v.number())
-			},
-			returns: v.object({
-				changes: v.array(v.object({
-					documentId: v.string(),
-					crdtBytes: v.bytes(),
-					seq: v.number(),
-					operationType: v.string()
-				})),
-				cursor: v.number(),
-				hasMore: v.boolean(),
-				compact: v.optional(v.string())
-			}),
-			handler: async (ctx, args) => {
-				if (opts?.evalRead) await opts.evalRead(ctx, collection);
-				const result = await ctx.runQuery(component.public.stream, {
-					collection,
-					cursor: args.cursor,
-					limit: args.limit,
-					sizeThreshold: args.sizeThreshold
-				});
-				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(),
-				cursor: v.optional(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 response = {
-					documents: docs,
-					count: docs.length
-				};
-				if (opts?.includeCRDTState) {
-					const crdtState = await ctx.runQuery(component.public.getInitialState, { collection });
-					if (crdtState) {
-						response.crdtBytes = crdtState.crdtBytes;
-						response.cursor = crdtState.cursor;
-					}
-				}
-				return response;
-			}
-		});
-	}
-	createInsertMutation(opts) {
-		const component = this.component;
-		const collection = this.collectionName;
-		return mutationGeneric({
-			args: {
-				documentId: v.string(),
-				crdtBytes: v.bytes(),
-				materializedDoc: v.any()
-			},
-			returns: v.object({
-				success: v.boolean(),
-				seq: v.number()
-			}),
-			handler: async (ctx, args) => {
-				const doc = args.materializedDoc;
-				if (opts?.evalWrite) await opts.evalWrite(ctx, doc);
-				const result = await ctx.runMutation(component.public.insertDocument, {
-					collection,
-					documentId: args.documentId,
-					crdtBytes: args.crdtBytes
-				});
-				await ctx.db.insert(collection, {
-					id: args.documentId,
-					...args.materializedDoc,
-					timestamp: Date.now()
-				});
-				if (opts?.onInsert) await opts.onInsert(ctx, doc);
-				return {
-					success: true,
-					seq: result.seq
-				};
-			}
-		});
-	}
-	createUpdateMutation(opts) {
-		const component = this.component;
-		const collection = this.collectionName;
-		return mutationGeneric({
-			args: {
-				documentId: v.string(),
-				crdtBytes: v.bytes(),
-				materializedDoc: v.any()
-			},
-			returns: v.object({
-				success: v.boolean(),
-				seq: v.number()
-			}),
-			handler: async (ctx, args) => {
-				const doc = args.materializedDoc;
-				if (opts?.evalWrite) await opts.evalWrite(ctx, doc);
-				const result = await ctx.runMutation(component.public.updateDocument, {
-					collection,
-					documentId: args.documentId,
-					crdtBytes: args.crdtBytes
-				});
-				const existing = await ctx.db.query(collection).withIndex("by_doc_id", (q) => q.eq("id", args.documentId)).first();
-				if (existing) await ctx.db.patch(existing._id, {
-					...args.materializedDoc,
-					timestamp: Date.now()
-				});
-				if (opts?.onUpdate) await opts.onUpdate(ctx, doc);
-				return {
-					success: true,
-					seq: result.seq
-				};
-			}
-		});
-	}
-	createRemoveMutation(opts) {
-		const component = this.component;
-		const collection = this.collectionName;
-		return mutationGeneric({
-			args: {
-				documentId: v.string(),
-				crdtBytes: v.bytes()
-			},
-			returns: v.object({
-				success: v.boolean(),
-				seq: v.number()
-			}),
-			handler: async (ctx, args) => {
-				const documentId = args.documentId;
-				if (opts?.evalRemove) await opts.evalRemove(ctx, documentId);
-				const result = await ctx.runMutation(component.public.deleteDocument, {
-					collection,
-					documentId,
-					crdtBytes: args.crdtBytes
-				});
-				const existing = await ctx.db.query(collection).withIndex("by_doc_id", (q) => q.eq("id", documentId)).first();
-				if (existing) await ctx.db.delete(existing._id);
-				if (opts?.onRemove) await opts.onRemove(ctx, documentId);
-				return {
-					success: true,
-					seq: result.seq
-				};
-			}
-		});
-	}
-	createMarkMutation(opts) {
-		const component = this.component;
-		const collection = this.collectionName;
-		return mutationGeneric({
-			args: {
-				peerId: v.string(),
-				syncedSeq: v.number()
-			},
-			returns: v.null(),
-			handler: async (ctx, args) => {
-				if (opts?.evalWrite) await opts.evalWrite(ctx, args.peerId);
-				await ctx.runMutation(component.public.mark, {
-					collection,
-					peerId: args.peerId,
-					syncedSeq: args.syncedSeq
-				});
-				return null;
-			}
-		});
-	}
-	createCompactMutation(opts) {
-		const component = this.component;
-		const collection = this.collectionName;
-		return mutationGeneric({
-			args: {
-				documentId: v.string(),
-				snapshotBytes: v.bytes(),
-				stateVector: v.bytes(),
-				peerTimeout: v.optional(v.number())
-			},
-			returns: v.object({
-				success: v.boolean(),
-				removed: v.number(),
-				retained: v.number()
-			}),
-			handler: async (ctx, args) => {
-				if (opts?.evalWrite) await opts.evalWrite(ctx, args.documentId);
-				return await ctx.runMutation(component.public.compact, {
-					collection,
-					documentId: args.documentId,
-					snapshotBytes: args.snapshotBytes,
-					stateVector: args.stateVector,
-					peerTimeout: args.peerTimeout
-				});
-			}
-		});
-	}
-	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(),
-				cursor: v.number()
-			}),
-			handler: async (ctx, args) => {
-				if (opts?.evalRead) await opts.evalRead(ctx, collection);
-				return await ctx.runQuery(component.public.recovery, {
-					collection,
-					clientStateVector: args.clientStateVector
-				});
-			}
-		});
-	}
-};
-
-//#endregion
-//#region src/server/builder.ts
-/**
-* 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' });
-* ```
-*/
-function replicate(component) {
-	return function boundReplicate(config) {
-		return replicateInternal(component, config);
-	};
-}
-/**
-* Internal implementation for replicate.
-*/
-function replicateInternal(component, config) {
-	const storage = new Replicate(component, config.collection, config.compaction);
-	return {
-		__collection: config.collection,
-		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
-		}),
-		mark: storage.createMarkMutation({ evalWrite: config.hooks?.evalMark }),
-		compact: storage.createCompactMutation({ evalWrite: config.hooks?.evalCompact })
-	};
-}
-
-//#endregion
-//#region src/server/schema.ts
-const prose = () => v.object({
-	type: v.literal("doc"),
-	content: v.optional(v.array(v.any()))
-});
-/**
-* 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'])
-*   ),
-* });
-* ```
-*/
-function table(userFields, applyIndexes) {
-	const tbl = defineTable({
-		...userFields,
-		timestamp: v.number()
-	});
-	if (applyIndexes) return applyIndexes(tbl);
-	return tbl;
-}
-
-//#endregion
-//#region src/server/index.ts
-const schema = {
-	table,
-	prose
-};
-
-//#endregion
-export { replicate, schema };

package/dist/shared/index.d.ts

@@ -1,29 +0,0 @@
-//#region src/shared/types.d.ts
-
-/** ProseMirror-compatible JSON for XmlFragment serialization */
-interface XmlFragmentJSON {
-  type: "doc";
-  content?: XmlNodeJSON[];
-}
-declare const PROSE_BRAND: unique symbol;
-/**
- * Branded prose type for Zod schemas.
- * Extends XmlFragmentJSON with a unique brand for type-level detection.
- * Use the `prose()` helper from `@trestleinc/replicate/client` to create this type.
- */
-interface ProseValue extends XmlFragmentJSON {
-  readonly [PROSE_BRAND]: typeof PROSE_BRAND;
-}
-/** ProseMirror node structure */
-interface XmlNodeJSON {
-  type: string;
-  attrs?: Record<string, unknown>;
-  content?: XmlNodeJSON[];
-  text?: string;
-  marks?: {
-    type: string;
-    attrs?: Record<string, unknown>;
-  }[];
-}
-//#endregion
-export { type ProseValue, type XmlFragmentJSON, type XmlNodeJSON };

package/dist/shared/index.js

@@ -1 +0,0 @@
-export {  };

package/src/client/prose-schema.ts

@@ -1,55 +0,0 @@
-import { z } from "zod";
-import type { ProseValue } from "$/shared/types";
-
-const PROSE_MARKER = Symbol.for("replicate:prose");
-
-function createProseSchema(): z.ZodType<ProseValue> {
-  const schema = z.custom<ProseValue>(
-    (val) => {
-      if (val == null) return true;
-      if (typeof val !== "object") return false;
-      return (val as { type?: string }).type === "doc";
-    },
-    { message: "Expected prose document with type \"doc\"" },
-  );
-
-  Object.defineProperty(schema, PROSE_MARKER, { value: true, writable: false });
-
-  return schema;
-}
-
-function emptyProse(): ProseValue {
-  return { type: "doc", content: [] } as unknown as ProseValue;
-}
-
-export function prose(): z.ZodType<ProseValue> {
-  return createProseSchema();
-}
-
-prose.empty = emptyProse;
-
-export function isProseSchema(schema: unknown): boolean {
-  return (
-    schema != null
-    && typeof schema === "object"
-    && PROSE_MARKER in schema
-    && (schema as Record<symbol, unknown>)[PROSE_MARKER] === true
-  );
-}
-
-export function extractProseFields(schema: z.ZodObject<z.ZodRawShape>): string[] {
-  const fields: string[] = [];
-
-  for (const [key, fieldSchema] of Object.entries(schema.shape)) {
-    let unwrapped = fieldSchema;
-    while (unwrapped instanceof z.ZodOptional || unwrapped instanceof z.ZodNullable) {
-      unwrapped = unwrapped.unwrap();
-    }
-
-    if (isProseSchema(unwrapped)) {
-      fields.push(key);
-    }
-  }
-
-  return fields;
-}

package/src/client/services/cursor.ts

@@ -1,109 +0,0 @@
-import { Effect, Context, Layer } from "effect";
-import { IDBError, IDBWriteError } from "$/client/errors";
-import type { KeyValueStore } from "$/client/persistence/types";
-
-export type Cursor = number;
-
-export class CursorService extends Context.Tag("CursorService")<
-  CursorService,
-  {
-    readonly loadCursor: (collection: string) => Effect.Effect<Cursor, IDBError>;
-    readonly saveCursor: (collection: string, cursor: Cursor) => Effect.Effect<void, IDBWriteError>;
-    readonly clearCursor: (collection: string) => Effect.Effect<void, IDBError>;
-    readonly loadPeerId: (collection: string) => Effect.Effect<string, IDBError | IDBWriteError>;
-  }
->() {}
-
-function generatePeerId(): string {
-  return crypto.randomUUID();
-}
-
-export function createCursorLayer(kv: KeyValueStore) {
-  return Layer.succeed(
-    CursorService,
-    CursorService.of({
-      loadCursor: collection =>
-        Effect.gen(function* (_) {
-          const key = `cursor:${collection}`;
-          const stored = yield* _(
-            Effect.tryPromise({
-              try: () => kv.get<Cursor>(key),
-              catch: cause => new IDBError({ operation: "get", key, cause }),
-            }),
-          );
-
-          if (stored !== undefined) {
-            yield* _(
-              Effect.logDebug("Loaded cursor from storage", {
-                collection,
-                cursor: stored,
-              }),
-            );
-            return stored;
-          }
-
-          yield* _(
-            Effect.logDebug("No stored cursor, using default", {
-              collection,
-            }),
-          );
-          return 0;
-        }),
-
-      saveCursor: (collection, cursor) =>
-        Effect.gen(function* (_) {
-          const key = `cursor:${collection}`;
-          yield* _(
-            Effect.tryPromise({
-              try: () => kv.set(key, cursor),
-              catch: cause => new IDBWriteError({ key, value: cursor, cause }),
-            }),
-          );
-          yield* _(
-            Effect.logDebug("Cursor saved", {
-              collection,
-              cursor,
-            }),
-          );
-        }),
-
-      clearCursor: collection =>
-        Effect.gen(function* (_) {
-          const key = `cursor:${collection}`;
-          yield* _(
-            Effect.tryPromise({
-              try: () => kv.del(key),
-              catch: cause => new IDBError({ operation: "delete", key, cause }),
-            }),
-          );
-          yield* _(Effect.logDebug("Cursor cleared", { collection }));
-        }),
-
-      loadPeerId: collection =>
-        Effect.gen(function* (_) {
-          const key = `peerId:${collection}`;
-          const stored = yield* _(
-            Effect.tryPromise({
-              try: () => kv.get<string>(key),
-              catch: cause => new IDBError({ operation: "get", key, cause }),
-            }),
-          );
-
-          if (stored) {
-            yield* _(Effect.logDebug("Loaded peerId from storage", { collection, peerId: stored }));
-            return stored;
-          }
-
-          const newPeerId = generatePeerId();
-          yield* _(
-            Effect.tryPromise({
-              try: () => kv.set(key, newPeerId),
-              catch: cause => new IDBWriteError({ key, value: newPeerId, cause }),
-            }),
-          );
-          yield* _(Effect.logDebug("Generated new peerId", { collection, peerId: newPeerId }));
-          return newPeerId;
-        }),
-    }),
-  );
-}