@trestleinc/replicate 1.1.1 → 1.1.2-preview.0

package/src/client/errors.ts

@@ -1,37 +1,37 @@
-import { Data } from 'effect';
+import { Data } from "effect";
 
-export class NetworkError extends Data.TaggedError('NetworkError')<{
+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';
+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')<{
+export class IDBWriteError extends Data.TaggedError("IDBWriteError")<{
   readonly key: string;
   readonly value: unknown;
   readonly cause: unknown;
 }> {}
 
-export class ReconciliationError extends Data.TaggedError('ReconciliationError')<{
+export class ReconciliationError extends Data.TaggedError("ReconciliationError")<{
   readonly collection: string;
   readonly reason: string;
   readonly cause?: unknown;
 }> {}
 
-export class ProseError extends Data.TaggedError('ProseError')<{
+export class ProseError extends Data.TaggedError("ProseError")<{
   readonly documentId: string;
   readonly field: string;
   readonly collection: string;
 }> {}
 
-export class CollectionNotReadyError extends Data.TaggedError('CollectionNotReadyError')<{
+export class CollectionNotReadyError extends Data.TaggedError("CollectionNotReadyError")<{
   readonly collection: string;
   readonly reason: string;
 }> {}
@@ -40,6 +40,6 @@ export class CollectionNotReadyError extends Data.TaggedError('CollectionNotRead
 export class NonRetriableError extends Error {
   constructor(message: string) {
     super(message);
-    this.name = 'NonRetriableError';
+    this.name = "NonRetriableError";
   }
 }

package/src/client/index.ts

@@ -1,8 +1,9 @@
 export {
-  convexCollectionOptions,
-  type ConvexCollection,
+  collection,
   type EditorBinding,
-} from '$/client/collection.js';
+  type ConvexCollection,
+  type Materialized,
+} from "$/client/collection";
 
 import {
   NetworkError,
@@ -12,7 +13,7 @@ import {
   ProseError,
   CollectionNotReadyError,
   NonRetriableError,
-} from '$/client/errors.js';
+} from "$/client/errors";
 
 export const errors = {
   Network: NetworkError,
@@ -24,34 +25,14 @@ export const errors = {
   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 type { ProseValue } from "$/shared/types";
+import { extract } from "$/client/merge";
+import { prose as proseSchema } from "$/client/prose-schema";
 
-import {
-  SqlJsAdapter,
-  OPSqliteAdapter,
-} from '$/client/persistence/adapters/index.js';
+function empty(): ProseValue {
+  return { type: "doc", content: [] } as unknown as ProseValue;
+}
 
-export const adapters = {
-  sqljs: SqlJsAdapter,
-  opsqlite: OPSqliteAdapter,
-} as const;
+export const prose = Object.assign(proseSchema, { extract, empty });
 
-export type {
-  SqlJsDatabase,
-  SqlJsAdapterOptions,
-  OPSQLiteDatabase,
-} from '$/client/persistence/adapters/index.js';
+export { persistence, type StorageAdapter, type Persistence } from "$/client/persistence/index";

package/src/client/logger.ts

@@ -1,5 +1,5 @@
-import { type Logger, getLogger as getLogTapeLogger } from '@logtape/logtape';
+import { type Logger, getLogger as getLogTapeLogger } from "@logtape/logtape";
 
 export function getLogger(category: string[]): Logger {
-  return getLogTapeLogger(['replicate', ...category]);
+  return getLogTapeLogger(["replicate", ...category]);
 }

package/src/client/merge.ts

@@ -4,11 +4,11 @@
  * 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';
+import * as Y from "yjs";
+import { getLogger } from "$/client/logger";
+import type { KeyValueStore } from "$/client/persistence/types";
 
-const logger = getLogger(['replicate', 'merge']);
+const logger = getLogger(["replicate", "merge"]);
 
 /**
  * Create a Yjs document with a persistent clientId.
@@ -24,7 +24,7 @@ export async function createYjsDocument(collection: string, kv: KeyValueStore):
   if (!clientId) {
     clientId = Math.floor(Math.random() * 2147483647);
     await kv.set(clientIdKey, clientId);
-    logger.info('Generated new Yjs clientID', { collection, clientId });
+    logger.info("Generated new Yjs clientID", { collection, clientId });
   }
 
   const ydoc = new Y.Doc({
@@ -32,7 +32,7 @@ export async function createYjsDocument(collection: string, kv: KeyValueStore):
     clientID: clientId,
   } as any);
 
-  logger.info('Created Yjs document', { collection, clientId });
+  logger.info("Created Yjs document", { collection, clientId });
   return ydoc;
 }
 
@@ -65,7 +65,7 @@ export function yjsTransact<A>(doc: Y.Doc, fn: () => A, origin?: string): A {
 export function transactWithDelta<A>(
   doc: Y.Doc,
   fn: () => A,
-  origin?: string
+  origin?: string,
 ): { result: A; delta: Uint8Array } {
   const beforeVector = Y.encodeStateVector(doc);
   const result = doc.transact(fn, origin);
@@ -88,10 +88,10 @@ export function transactWithDelta<A>(
  * and have these properties regardless of which module instance created them.
  */
 function isYjsAbstractType(value: unknown): boolean {
-  if (value === null || typeof value !== 'object') return false;
+  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;
+  return "_map" in v && "_eH" in v && "doc" in v;
 }
 
 /**
@@ -101,7 +101,7 @@ function isYjsAbstractType(value: unknown): boolean {
 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';
+  return typeof v.keys === "function" && typeof v.get === "function";
 }
 
 /**
@@ -110,7 +110,7 @@ function isYMap(value: unknown): boolean {
 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';
+  return typeof v.toArray === "function" && typeof v.get !== "function";
 }
 
 /**
@@ -121,7 +121,7 @@ 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';
+  return typeof v.toArray === "function" && typeof v.keys !== "function";
 }
 
 /**
@@ -131,7 +131,7 @@ function isYXmlFragment(value: unknown): value is Y.XmlFragment {
 function serialize(value: unknown): unknown {
   // Primitives pass through
   if (value === null || value === undefined) return value;
-  if (typeof value !== 'object') return value;
+  if (typeof value !== "object") return value;
 
   // Check for XmlFragment first (converts to ProseMirror JSON)
   if (isYXmlFragment(value)) {
@@ -188,7 +188,7 @@ export function extractItem<T>(ymap: Y.Map<unknown>, key: string): T | null {
   return null;
 }
 
-import type { XmlFragmentJSON, XmlNodeJSON } from '$/shared/types.js';
+import type { XmlFragmentJSON, XmlNodeJSON } from "$/shared/types";
 
 /**
  * Check if a value looks like ProseMirror/BlockNote JSON document.
@@ -196,10 +196,10 @@ import type { XmlFragmentJSON, XmlNodeJSON } from '$/shared/types.js';
  */
 export function isDoc(value: unknown): value is XmlFragmentJSON {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    'type' in value &&
-    (value as { type: unknown }).type === 'doc'
+    typeof value === "object"
+    && value !== null
+    && "type" in value
+    && (value as { type: unknown }).type === "doc"
   );
 }
 
@@ -212,11 +212,12 @@ export function fragmentToJSON(fragment: Y.XmlFragment): XmlFragmentJSON {
   for (const child of fragment.toArray()) {
     if (child instanceof Y.XmlElement) {
       content.push(xmlElementToJSON(child));
-    } else if (child instanceof Y.XmlText) {
+    }
+    else if (child instanceof Y.XmlText) {
       const textContent = xmlTextToJSON(child);
       if (textContent.length > 0) {
         content.push({
-          type: 'paragraph',
+          type: "paragraph",
           content: textContent,
         });
       }
@@ -224,8 +225,8 @@ export function fragmentToJSON(fragment: Y.XmlFragment): XmlFragmentJSON {
   }
 
   return {
-    type: 'doc',
-    content: content.length > 0 ? content : [{ type: 'paragraph' }],
+    type: "doc",
+    content: content.length > 0 ? content : [{ type: "paragraph" }],
   };
 }
 
@@ -243,7 +244,8 @@ function xmlElementToJSON(element: Y.XmlElement): XmlNodeJSON {
   for (const child of element.toArray()) {
     if (child instanceof Y.XmlElement) {
       content.push(xmlElementToJSON(child));
-    } else if (child instanceof Y.XmlText) {
+    }
+    else if (child instanceof Y.XmlText) {
       content.push(...xmlTextToJSON(child));
     }
   }
@@ -260,16 +262,16 @@ function xmlTextToJSON(text: Y.XmlText): XmlNodeJSON[] {
   const delta = text.toDelta();
 
   for (const op of delta) {
-    if (typeof op.insert === 'string') {
+    if (typeof op.insert === "string") {
       const node: XmlNodeJSON = {
-        type: 'text',
+        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,
+          attrs: typeof attrs === "object" ? (attrs as Record<string, unknown>) : undefined,
         }));
       }
 
@@ -296,23 +298,23 @@ export function fragmentFromJSON(fragment: Y.XmlFragment, json: XmlFragmentJSON)
  * Handles various content structures defensively for search and display.
  */
 export function extract(content: unknown): string {
-  if (!content || typeof content !== 'object') return '';
+  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 '';
+  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('');
+      if (!block.content || !Array.isArray(block.content)) return "";
+      return block.content.map((node: { text?: string }) => node.text || "").join("");
     })
-    .join(' ');
+    .join(" ");
 }
 
 function appendNodeToFragment(parent: Y.XmlFragment | Y.XmlElement, node: XmlNodeJSON): void {
-  if (node.type === 'text') {
+  if (node.type === "text") {
     const text = new Y.XmlText();
     if (node.text) {
       const attrs: Record<string, unknown> = {};
@@ -324,7 +326,8 @@ function appendNodeToFragment(parent: Y.XmlFragment | Y.XmlElement, node: XmlNod
       text.insert(0, node.text, Object.keys(attrs).length > 0 ? attrs : undefined);
     }
     parent.insert(parent.length, [text]);
-  } else {
+  }
+  else {
     const element = new Y.XmlElement(node.type);
 
     if (node.attrs) {
@@ -358,7 +361,7 @@ export function serializeYMapValue(value: unknown): unknown {
 export function getFragmentFromYMap(
   ymap: Y.Map<unknown>,
   documentId: string,
-  field: string
+  field: string,
 ): Y.XmlFragment | null {
   const doc = ymap.get(documentId);
   if (!isYMap(doc)) {

package/src/client/persistence/custom.ts

@@ -0,0 +1,84 @@
+import * as Y from "yjs";
+import type { StorageAdapter, Persistence, PersistenceProvider, KeyValueStore } from "./types.js";
+
+const SNAPSHOT_PREFIX = "snapshot:";
+const UPDATE_PREFIX = "update:";
+const META_PREFIX = "meta:";
+
+class AdapterKeyValueStore implements KeyValueStore {
+  constructor(private adapter: StorageAdapter) {}
+
+  async get<T>(key: string): Promise<T | undefined> {
+    const data = await this.adapter.get(`${META_PREFIX}${key}`);
+    if (!data) return undefined;
+    return JSON.parse(new TextDecoder().decode(data)) as T;
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    await this.adapter.set(`${META_PREFIX}${key}`, new TextEncoder().encode(JSON.stringify(value)));
+  }
+
+  async del(key: string): Promise<void> {
+    await this.adapter.delete(`${META_PREFIX}${key}`);
+  }
+}
+
+class AdapterPersistenceProvider implements PersistenceProvider {
+  private updateHandler: (update: Uint8Array, origin: unknown) => void;
+  private updateCounter = 0;
+  readonly whenSynced: Promise<void>;
+
+  constructor(
+    private adapter: StorageAdapter,
+    private collection: string,
+    private ydoc: Y.Doc,
+  ) {
+    this.whenSynced = this.loadState();
+
+    this.updateHandler = (update: Uint8Array, origin: unknown) => {
+      if (origin !== "custom") {
+        void this.saveUpdate(update);
+      }
+    };
+    this.ydoc.on("update", this.updateHandler);
+  }
+
+  private async loadState(): Promise<void> {
+    const snapshotData = await this.adapter.get(`${SNAPSHOT_PREFIX}${this.collection}`);
+    if (snapshotData) {
+      Y.applyUpdate(this.ydoc, snapshotData, "custom");
+    }
+
+    const updateKeys = await this.adapter.keys(`${UPDATE_PREFIX}${this.collection}:`);
+    const sortedKeys = updateKeys.sort();
+
+    for (const key of sortedKeys) {
+      const updateData = await this.adapter.get(key);
+      if (updateData) {
+        Y.applyUpdate(this.ydoc, updateData, "custom");
+        const seq = parseInt(key.split(":").pop() || "0", 10);
+        if (seq > this.updateCounter) {
+          this.updateCounter = seq;
+        }
+      }
+    }
+  }
+
+  private async saveUpdate(update: Uint8Array): Promise<void> {
+    this.updateCounter++;
+    const paddedCounter = String(this.updateCounter).padStart(10, "0");
+    await this.adapter.set(`${UPDATE_PREFIX}${this.collection}:${paddedCounter}`, update);
+  }
+
+  destroy(): void {
+    this.ydoc.off("update", this.updateHandler);
+  }
+}
+
+export function createCustomPersistence(adapter: StorageAdapter): Persistence {
+  return {
+    createDocPersistence: (collection: string, ydoc: Y.Doc) =>
+      new AdapterPersistenceProvider(adapter, collection, ydoc),
+    kv: new AdapterKeyValueStore(adapter),
+  };
+}

package/src/client/persistence/index.ts

@@ -1,54 +1,17 @@
-/**
- * Persistence layer exports.
- *
- * Provides swappable storage backends for Y.Doc and key-value data.
- */
-export type { Persistence, PersistenceProvider, KeyValueStore } from './types.js';
-export type { SqlitePersistenceOptions } from './sqlite.js';
-export type { SqlJsStatic } from './sqlite-browser.js';
-export type { SqliteAdapter } from './sqlite-level.js';
+export type { StorageAdapter, Persistence } from "./types.js";
 
-// Internal imports for the persistence object
-import { indexeddbPersistence } from './indexeddb.js';
-import { memoryPersistence } from './memory.js';
-import { sqlitePersistence } from './sqlite.js';
-import { createBrowserSqlitePersistence } from './sqlite-browser.js';
-import { createReactNativeSqlitePersistence } from './sqlite-rn.js';
+import { memoryPersistence } from "./memory.js";
+import { createBrowserSqlitePersistence } from "./sqlite/browser.js";
+import { createNativeSqlitePersistence } from "./sqlite/native.js";
+import { createIndexedDBPersistence } from "./indexeddb.js";
+import { createCustomPersistence } from "./custom.js";
 
-/**
- * Persistence API - nested object pattern for ergonomic access.
- *
- * @example
- * ```typescript
- * import { persistence } from '@trestleinc/replicate/client';
- *
- * // Browser SQLite (recommended for web)
- * const p = await persistence.sqlite.browser(SQL, 'myapp');
- *
- * // React Native SQLite
- * const p = await persistence.sqlite.native(db, 'myapp');
- *
- * // IndexedDB fallback
- * const p = persistence.indexeddb('myapp');
- *
- * // In-memory (testing)
- * const p = persistence.memory();
- * ```
- */
 export const persistence = {
-  /** IndexedDB-backed persistence (browser) */
-  indexeddb: indexeddbPersistence,
-
-  /** In-memory persistence (testing/ephemeral) */
   memory: memoryPersistence,
-
-  /** SQLite persistence variants */
   sqlite: {
-    /** Browser SQLite with OPFS (sql.js) */
     browser: createBrowserSqlitePersistence,
-    /** React Native SQLite (op-sqlite) */
-    native: createReactNativeSqlitePersistence,
-    /** Custom SQLite adapter */
-    create: sqlitePersistence,
+    native: createNativeSqlitePersistence,
   },
+  indexeddb: createIndexedDBPersistence,
+  custom: createCustomPersistence,
 } as const;