@trestleinc/replicate 0.1.0 → 1.1.0

package/src/client/errors.ts

@@ -0,0 +1,45 @@
+import { Data } from 'effect';
+
+export class NetworkError extends Data.TaggedError('NetworkError')<{
+  readonly cause: unknown;
+  readonly retryable: true;
+  readonly operation: string;
+}> {}
+
+export class IDBError extends Data.TaggedError('IDBError')<{
+  readonly operation: 'get' | 'set' | 'delete' | 'clear';
+  readonly store?: string;
+  readonly key?: string;
+  readonly cause: unknown;
+}> {}
+
+export class IDBWriteError extends Data.TaggedError('IDBWriteError')<{
+  readonly key: string;
+  readonly value: unknown;
+  readonly cause: unknown;
+}> {}
+
+export class ReconciliationError extends Data.TaggedError('ReconciliationError')<{
+  readonly collection: string;
+  readonly reason: string;
+  readonly cause?: unknown;
+}> {}
+
+export class ProseError extends Data.TaggedError('ProseError')<{
+  readonly documentId: string;
+  readonly field: string;
+  readonly collection: string;
+}> {}
+
+export class CollectionNotReadyError extends Data.TaggedError('CollectionNotReadyError')<{
+  readonly collection: string;
+  readonly reason: string;
+}> {}
+
+/** Error that should not be retried (auth failures, validation errors) */
+export class NonRetriableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NonRetriableError';
+  }
+}

package/src/client/index.ts

@@ -1,31 +1,57 @@
-/**
- * Client-side utilities for browser/React code.
- * Import this in your frontend components.
- *
- * @example
- * ```typescript
- * // src/useTasks.ts
- * import {
- *   convexCollectionOptions,
- *   createConvexCollection,
- *   type ConvexCollection,
- * } from '@trestleinc/replicate/client';
- * ```
- */
-
-// Component client (ReplicateStorage class)
-export { ReplicateStorage } from './storage.js';
-
-// TanStack DB collection integration
 export {
   convexCollectionOptions,
-  createConvexCollection,
   type ConvexCollection,
-  type ConvexCollectionOptionsConfig,
-} from './collection.js';
+  type EditorBinding,
+} from '$/client/collection.js';
 
-// Re-export Yjs for convenience
-export * as Y from 'yjs';
+import {
+  NetworkError,
+  IDBError,
+  IDBWriteError,
+  ReconciliationError,
+  ProseError,
+  CollectionNotReadyError,
+  NonRetriableError,
+} from '$/client/errors.js';
 
-// Re-export TanStack DB offline utilities
-export { NonRetriableError } from '@tanstack/offline-transactions';
+export const errors = {
+  Network: NetworkError,
+  IDB: IDBError,
+  IDBWrite: IDBWriteError,
+  Reconciliation: ReconciliationError,
+  Prose: ProseError,
+  CollectionNotReady: CollectionNotReadyError,
+  NonRetriable: NonRetriableError,
+} as const;
+
+import { extract } from '$/client/merge.js';
+
+export const prose = {
+  extract,
+} as const;
+
+export {
+  persistence,
+  type Persistence,
+  type PersistenceProvider,
+  type KeyValueStore,
+  type SqlitePersistenceOptions,
+  type SqliteAdapter,
+  type SqlJsStatic,
+} from '$/client/persistence/index.js';
+
+import {
+  SqlJsAdapter,
+  OPSqliteAdapter,
+} from '$/client/persistence/adapters/index.js';
+
+export const adapters = {
+  sqljs: SqlJsAdapter,
+  opsqlite: OPSqliteAdapter,
+} as const;
+
+export type {
+  SqlJsDatabase,
+  SqlJsAdapterOptions,
+  OPSQLiteDatabase,
+} from '$/client/persistence/adapters/index.js';

package/src/client/logger.ts

@@ -1,31 +1,5 @@
-import {
-  type Logger,
-  configure,
-  getConsoleSink,
-  getLogger as getLogTapeLogger,
-} from '@logtape/logtape';
-
-let isConfigured = false;
-
-export async function configureLogger(enableLogging = false): Promise<void> {
-  if (isConfigured) return;
-
-  await configure({
-    sinks: {
-      console: getConsoleSink(),
-    },
-    loggers: [
-      {
-        category: ['convex-replicate'],
-        lowestLevel: enableLogging ? 'debug' : 'warning',
-        sinks: ['console'],
-      },
-    ],
-  });
-
-  isConfigured = true;
-}
+import { type Logger, getLogger as getLogTapeLogger } from '@logtape/logtape';
 
 export function getLogger(category: string[]): Logger {
-  return getLogTapeLogger(['convex-replicate', ...category]);
+  return getLogTapeLogger(['replicate', ...category]);
 }

package/src/client/merge.ts

@@ -0,0 +1,374 @@
+/**
+ * Merge Helpers - Plain functions for Yjs CRDT operations
+ *
+ * Provides document creation, state encoding, and merge operations.
+ */
+
+import * as Y from 'yjs';
+import { getLogger } from '$/client/logger.js';
+import type { KeyValueStore } from '$/client/persistence/types.js';
+
+const logger = getLogger(['replicate', 'merge']);
+
+/**
+ * Create a Yjs document with a persistent clientId.
+ * The clientId ensures consistent identity across sessions for CRDT merging.
+ *
+ * @param collection - The collection name
+ * @param kv - Key-value store for persisting the clientId
+ */
+export async function createYjsDocument(collection: string, kv: KeyValueStore): Promise<Y.Doc> {
+  const clientIdKey = `yjsClientId:${collection}`;
+  let clientId = await kv.get<number>(clientIdKey);
+
+  if (!clientId) {
+    clientId = Math.floor(Math.random() * 2147483647);
+    await kv.set(clientIdKey, clientId);
+    logger.info('Generated new Yjs clientID', { collection, clientId });
+  }
+
+  const ydoc = new Y.Doc({
+    guid: collection,
+    clientID: clientId,
+  } as any);
+
+  logger.info('Created Yjs document', { collection, clientId });
+  return ydoc;
+}
+
+/**
+ * Apply a binary update to a Yjs document.
+ * Y.applyUpdateV2 is already atomic, no need for transaction wrapper.
+ */
+export function applyUpdate(doc: Y.Doc, update: Uint8Array, origin?: string): void {
+  Y.applyUpdateV2(doc, update, origin);
+}
+
+/**
+ * Get a Y.Map from a Yjs document by name.
+ */
+export function getYMap<T = unknown>(doc: Y.Doc, name: string): Y.Map<T> {
+  return doc.getMap(name);
+}
+
+/**
+ * Execute a function within a Yjs transaction.
+ */
+export function yjsTransact<A>(doc: Y.Doc, fn: () => A, origin?: string): A {
+  return doc.transact(fn, origin);
+}
+
+/**
+ * Execute a function within a Yjs transaction and capture the delta.
+ * Returns both the function result and a delta containing only the changes made.
+ */
+export function transactWithDelta<A>(
+  doc: Y.Doc,
+  fn: () => A,
+  origin?: string
+): { result: A; delta: Uint8Array } {
+  const beforeVector = Y.encodeStateVector(doc);
+  const result = doc.transact(fn, origin);
+  const delta = Y.encodeStateAsUpdateV2(doc, beforeVector);
+  return { result, delta };
+}
+
+// ============================================================================
+// Yjs Serialization System
+// ============================================================================
+// Yjs uses `instanceof AbstractType` internally in toJSON() which breaks when
+// multiple Yjs module instances exist (common with bundlers). We detect Yjs
+// types by their internal structure (`doc`, `_map`, `_start` properties) which
+// is stable across instances, then manually iterate using forEach/toArray.
+// ============================================================================
+
+/**
+ * Check if a value is a Yjs AbstractType by checking internal properties.
+ * All Yjs types (Y.Map, Y.Array, Y.Text, Y.XmlFragment, etc.) extend AbstractType
+ * and have these properties regardless of which module instance created them.
+ */
+function isYjsAbstractType(value: unknown): boolean {
+  if (value === null || typeof value !== 'object') return false;
+  const v = value as Record<string, unknown>;
+  // AbstractType has: doc (Doc|null), _map (Map), _eH (event handler)
+  return '_map' in v && '_eH' in v && 'doc' in v;
+}
+
+/**
+ * Check if a value is a Y.Map.
+ * Y.Map has keys() method which Y.XmlFragment does not.
+ */
+function isYMap(value: unknown): boolean {
+  if (!isYjsAbstractType(value)) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.keys === 'function' && typeof v.get === 'function';
+}
+
+/**
+ * Check if a value is a Y.Array (has toArray but not get - distinguishes from Y.Map).
+ */
+function isYArray(value: unknown): boolean {
+  if (!isYjsAbstractType(value)) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.toArray === 'function' && typeof v.get !== 'function';
+}
+
+/**
+ * Check if a value is a Y.XmlFragment or Y.XmlElement.
+ * XmlFragment has toArray() and get(index), but NOT keys() like Y.Map.
+ */
+function isYXmlFragment(value: unknown): value is Y.XmlFragment {
+  if (!isYjsAbstractType(value)) return false;
+  const v = value as Record<string, unknown>;
+  // XmlFragment has toArray() but NOT keys() - keys() is unique to Y.Map
+  return typeof v.toArray === 'function' && typeof v.keys !== 'function';
+}
+
+/**
+ * Recursively serialize a Yjs value to plain JavaScript.
+ * Handles Y.Map, Y.Array, Y.XmlFragment without using instanceof.
+ */
+function serialize(value: unknown): unknown {
+  // Primitives pass through
+  if (value === null || value === undefined) return value;
+  if (typeof value !== 'object') return value;
+
+  // Check for XmlFragment first (converts to ProseMirror JSON)
+  if (isYXmlFragment(value)) {
+    return fragmentToJSON(value);
+  }
+
+  // Y.Map - iterate with forEach and recursively serialize values
+  if (isYMap(value)) {
+    const result: Record<string, unknown> = {};
+    const ymap = value as Y.Map<unknown>;
+    ymap.forEach((v, k) => {
+      result[k] = serialize(v);
+    });
+    return result;
+  }
+
+  // Y.Array - convert to array and recursively serialize elements
+  if (isYArray(value)) {
+    return (value as Y.Array<unknown>).toArray().map(serialize);
+  }
+
+  // Regular object/array (not a Yjs type) - return as-is
+  return value;
+}
+
+/**
+ * Serialize a Y.Map to a plain object.
+ */
+export function serializeYMap(ymap: Y.Map<unknown>): Record<string, unknown> {
+  return serialize(ymap) as Record<string, unknown>;
+}
+
+/**
+ * Extract all items from a Y.Map as plain objects.
+ */
+export function extractItems<T>(ymap: Y.Map<unknown>): T[] {
+  const items: T[] = [];
+  ymap.forEach((value) => {
+    if (isYMap(value)) {
+      items.push(serialize(value) as T);
+    }
+  });
+  return items;
+}
+
+/**
+ * Extract a single item from a Y.Map by key.
+ */
+export function extractItem<T>(ymap: Y.Map<unknown>, key: string): T | null {
+  const value = ymap.get(key);
+  if (isYMap(value)) {
+    return serialize(value) as T;
+  }
+  return null;
+}
+
+import type { XmlFragmentJSON, XmlNodeJSON } from '$/shared/types.js';
+
+/**
+ * Check if a value looks like ProseMirror/BlockNote JSON document.
+ * Used internally to auto-detect prose fields during insert/update.
+ */
+export function isDoc(value: unknown): value is XmlFragmentJSON {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'type' in value &&
+    (value as { type: unknown }).type === 'doc'
+  );
+}
+
+/**
+ * Convert a Y.XmlFragment to ProseMirror-compatible JSON.
+ */
+export function fragmentToJSON(fragment: Y.XmlFragment): XmlFragmentJSON {
+  const content: XmlNodeJSON[] = [];
+
+  for (const child of fragment.toArray()) {
+    if (child instanceof Y.XmlElement) {
+      content.push(xmlElementToJSON(child));
+    } else if (child instanceof Y.XmlText) {
+      const textContent = xmlTextToJSON(child);
+      if (textContent.length > 0) {
+        content.push({
+          type: 'paragraph',
+          content: textContent,
+        });
+      }
+    }
+  }
+
+  return {
+    type: 'doc',
+    content: content.length > 0 ? content : [{ type: 'paragraph' }],
+  };
+}
+
+function xmlElementToJSON(element: Y.XmlElement): XmlNodeJSON {
+  const result: XmlNodeJSON = {
+    type: element.nodeName,
+  };
+
+  const attrs = element.getAttributes();
+  if (Object.keys(attrs).length > 0) {
+    result.attrs = attrs;
+  }
+
+  const content: XmlNodeJSON[] = [];
+  for (const child of element.toArray()) {
+    if (child instanceof Y.XmlElement) {
+      content.push(xmlElementToJSON(child));
+    } else if (child instanceof Y.XmlText) {
+      content.push(...xmlTextToJSON(child));
+    }
+  }
+
+  if (content.length > 0) {
+    result.content = content;
+  }
+
+  return result;
+}
+
+function xmlTextToJSON(text: Y.XmlText): XmlNodeJSON[] {
+  const result: XmlNodeJSON[] = [];
+  const delta = text.toDelta();
+
+  for (const op of delta) {
+    if (typeof op.insert === 'string') {
+      const node: XmlNodeJSON = {
+        type: 'text',
+        text: op.insert,
+      };
+
+      if (op.attributes && Object.keys(op.attributes).length > 0) {
+        node.marks = Object.entries(op.attributes).map(([type, attrs]) => ({
+          type,
+          attrs: typeof attrs === 'object' ? (attrs as Record<string, unknown>) : undefined,
+        }));
+      }
+
+      result.push(node);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Initialize a Y.XmlFragment from ProseMirror-compatible JSON.
+ */
+export function fragmentFromJSON(fragment: Y.XmlFragment, json: XmlFragmentJSON): void {
+  if (!json.content) return;
+
+  for (const node of json.content) {
+    appendNodeToFragment(fragment, node);
+  }
+}
+
+/**
+ * Extract plain text from ProseMirror/BlockNote JSON content.
+ * Handles various content structures defensively for search and display.
+ */
+export function extract(content: unknown): string {
+  if (!content || typeof content !== 'object') return '';
+
+  const doc = content as { content?: unknown; type?: string };
+
+  // Handle XmlFragmentJSON format - content must be an array
+  if (!doc.content || !Array.isArray(doc.content)) return '';
+
+  return doc.content
+    .map((block: { content?: unknown }) => {
+      if (!block.content || !Array.isArray(block.content)) return '';
+      return block.content.map((node: { text?: string }) => node.text || '').join('');
+    })
+    .join(' ');
+}
+
+function appendNodeToFragment(parent: Y.XmlFragment | Y.XmlElement, node: XmlNodeJSON): void {
+  if (node.type === 'text') {
+    const text = new Y.XmlText();
+    if (node.text) {
+      const attrs: Record<string, unknown> = {};
+      if (node.marks) {
+        for (const mark of node.marks) {
+          attrs[mark.type] = mark.attrs ?? true;
+        }
+      }
+      text.insert(0, node.text, Object.keys(attrs).length > 0 ? attrs : undefined);
+    }
+    parent.insert(parent.length, [text]);
+  } else {
+    const element = new Y.XmlElement(node.type);
+
+    if (node.attrs) {
+      for (const [key, value] of Object.entries(node.attrs)) {
+        element.setAttribute(key, value as string);
+      }
+    }
+
+    if (node.content) {
+      for (const child of node.content) {
+        appendNodeToFragment(element, child);
+      }
+    }
+
+    parent.insert(parent.length, [element]);
+  }
+}
+
+/**
+ * Serialize any value, handling Yjs types specially.
+ * Uses our custom serialization system that works across module instances.
+ */
+export function serializeYMapValue(value: unknown): unknown {
+  return serialize(value);
+}
+
+/**
+ * Get a Y.XmlFragment from a document's field.
+ * Returns null if the document or field doesn't exist, or if the field is not an XmlFragment.
+ */
+export function getFragmentFromYMap(
+  ymap: Y.Map<unknown>,
+  documentId: string,
+  field: string
+): Y.XmlFragment | null {
+  const doc = ymap.get(documentId);
+  if (!isYMap(doc)) {
+    return null;
+  }
+
+  const fieldValue = (doc as Y.Map<unknown>).get(field);
+  if (isYXmlFragment(fieldValue)) {
+    return fieldValue;
+  }
+
+  return null;
+}

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

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

@@ -0,0 +1,54 @@
+/**
+ * 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();
+  }
+}