@trestleinc/replicate 1.1.1 → 1.1.2-preview.0

package/dist/client/index.d.ts

@@ -1,22 +1,314 @@
-export { convexCollectionOptions, type ConvexCollection, type EditorBinding, } from '$/client/collection.js';
-import { NetworkError, IDBError, IDBWriteError, ReconciliationError, ProseError, CollectionNotReadyError, NonRetriableError } from '$/client/errors.js';
-export declare const errors: {
-    readonly Network: typeof NetworkError;
-    readonly IDB: typeof IDBError;
-    readonly IDBWrite: typeof IDBWriteError;
-    readonly Reconciliation: typeof ReconciliationError;
-    readonly Prose: typeof ProseError;
-    readonly CollectionNotReady: typeof CollectionNotReadyError;
-    readonly NonRetriable: typeof NonRetriableError;
+import * as Y from "yjs";
+import { FunctionReference } from "convex/server";
+import { BaseCollectionConfig, Collection, NonSingleResult } from "@tanstack/db";
+import { Context, Effect, Layer } from "effect";
+import { ConvexClient } from "convex/browser";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import * as effect_Types0 from "effect/Types";
+import * as effect_Cause0 from "effect/Cause";
+import { z } from "zod";
+
+//#region src/client/persistence/types.d.ts
+
+/**
+ * Low-level storage adapter for custom backends (Chrome extension, localStorage, cloud).
+ * For SQLite, use `persistence.sqlite()` directly.
+ *
+ * @example
+ * ```typescript
+ * class ChromeStorageAdapter implements StorageAdapter {
+ *   async get(key: string) {
+ *     const result = await chrome.storage.local.get(key);
+ *     return result[key] ? new Uint8Array(result[key]) : undefined;
+ *   }
+ *   async set(key: string, value: Uint8Array) {
+ *     await chrome.storage.local.set({ [key]: Array.from(value) });
+ *   }
+ *   async delete(key: string) {
+ *     await chrome.storage.local.remove(key);
+ *   }
+ *   async keys(prefix: string) {
+ *     const all = await chrome.storage.local.get(null);
+ *     return Object.keys(all).filter(k => k.startsWith(prefix));
+ *   }
+ * }
+ * ```
+ */
+interface StorageAdapter {
+  get(key: string): Promise<Uint8Array | undefined>;
+  set(key: string, value: Uint8Array): Promise<void>;
+  delete(key: string): Promise<void>;
+  keys(prefix: string): Promise<string[]>;
+  close?(): void;
+}
+interface PersistenceProvider {
+  readonly whenSynced: Promise<void>;
+  destroy(): void;
+}
+/**
+ * High-level persistence interface for collections.
+ * Create via `persistence.sqlite()`, `persistence.memory()`, or `persistence.custom()`.
+ */
+interface Persistence {
+  createDocPersistence(collection: string, ydoc: Y.Doc): PersistenceProvider;
+  readonly kv: KeyValueStore;
+}
+interface KeyValueStore {
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T): Promise<void>;
+  del(key: string): Promise<void>;
+}
+//#endregion
+//#region src/client/errors.d.ts
+declare const NetworkError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "NetworkError";
+} & Readonly<A>;
+declare class NetworkError extends NetworkError_base<{
+  readonly cause: unknown;
+  readonly retryable: true;
+  readonly operation: string;
+}> {}
+declare const IDBError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "IDBError";
+} & Readonly<A>;
+declare class IDBError extends IDBError_base<{
+  readonly operation: "get" | "set" | "delete" | "clear";
+  readonly store?: string;
+  readonly key?: string;
+  readonly cause: unknown;
+}> {}
+declare const IDBWriteError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "IDBWriteError";
+} & Readonly<A>;
+declare class IDBWriteError extends IDBWriteError_base<{
+  readonly key: string;
+  readonly value: unknown;
+  readonly cause: unknown;
+}> {}
+declare const ReconciliationError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "ReconciliationError";
+} & Readonly<A>;
+declare class ReconciliationError extends ReconciliationError_base<{
+  readonly collection: string;
+  readonly reason: string;
+  readonly cause?: unknown;
+}> {}
+declare const ProseError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "ProseError";
+} & Readonly<A>;
+declare class ProseError extends ProseError_base<{
+  readonly documentId: string;
+  readonly field: string;
+  readonly collection: string;
+}> {}
+declare const CollectionNotReadyError_base: new <A extends Record<string, any> = {}>(args: effect_Types0.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }) => effect_Cause0.YieldableError & {
+  readonly _tag: "CollectionNotReadyError";
+} & Readonly<A>;
+declare class CollectionNotReadyError extends CollectionNotReadyError_base<{
+  readonly collection: string;
+  readonly reason: string;
+}> {}
+/** Error that should not be retried (auth failures, validation errors) */
+declare class NonRetriableError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region src/client/services/cursor.d.ts
+type Cursor = number;
+//#endregion
+//#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>;
+  }[];
+}
+/**
+ * Extract prose field names from T (fields typed as ProseValue).
+ * Used internally for type-safe prose field operations.
+ */
+type ProseFields<T> = { [K in keyof T]: T[K] extends ProseValue ? K : never }[keyof T];
+//#endregion
+//#region src/client/collection.d.ts
+/** Server-rendered material data for SSR hydration */
+interface Materialized<T> {
+  documents: readonly T[];
+  cursor?: Cursor;
+  count?: number;
+  crdtBytes?: ArrayBuffer;
+}
+/** API object from replicate() */
+interface ConvexCollectionApi {
+  stream: FunctionReference<"query">;
+  insert: FunctionReference<"mutation">;
+  update: FunctionReference<"mutation">;
+  remove: FunctionReference<"mutation">;
+  recovery: FunctionReference<"query">;
+  mark: FunctionReference<"mutation">;
+  compact: FunctionReference<"mutation">;
+  material?: FunctionReference<"query">;
+}
+interface ConvexCollectionConfig<T extends object = object, TSchema extends StandardSchemaV1 = never, TKey extends string | number = string | number> extends BaseCollectionConfig<T, TKey, TSchema> {
+  schema: TSchema;
+  convexClient: ConvexClient;
+  api: ConvexCollectionApi;
+  persistence: Persistence;
+  material?: Materialized<T>;
+  undoCaptureTimeout?: number;
+}
+/** Editor binding for BlockNote/TipTap collaboration */
+interface EditorBinding {
+  /** The Y.XmlFragment bound to the editor */
+  readonly fragment: Y.XmlFragment;
+  /** Provider stub for BlockNote compatibility */
+  readonly provider: {
+    readonly awareness: null;
+  };
+  /** Current sync state - true if unsent changes exist */
+  readonly pending: boolean;
+  /** Subscribe to pending state changes. Returns unsubscribe function. */
+  onPendingChange(callback: (pending: boolean) => void): () => void;
+  /** Undo the last content edit */
+  undo(): void;
+  /** Redo the last undone edit */
+  redo(): void;
+  /** Check if undo is available */
+  canUndo(): boolean;
+  /** Check if redo is available */
+  canRedo(): boolean;
+}
+/** Utilities exposed on collection.utils */
+interface ConvexCollectionUtils<T extends object> {
+  /**
+   * Get an editor binding for a prose field.
+   * Waits for Y.Doc to be ready (IndexedDB loaded) before returning.
+   * @param documentId - The document ID
+   * @param field - The prose field name (must be in `prose` config)
+   * @returns Promise resolving to EditorBinding
+   */
+  prose(documentId: string, field: ProseFields<T>): Promise<EditorBinding>;
+}
+type LazyCollectionConfig<TSchema extends z.ZodObject<z.ZodRawShape>> = Omit<ConvexCollectionConfig<z.infer<TSchema>, TSchema, string>, "persistence" | "material">;
+interface LazyCollection<T extends object> {
+  init(material?: Materialized<T>): Promise<void>;
+  get(): Collection<T, string, ConvexCollectionUtils<T>, any, T> & NonSingleResult;
+}
+type ConvexCollection<T extends object> = Collection<T, any, ConvexCollectionUtils<T>, any, T> & NonSingleResult;
+interface CreateCollectionOptions<TSchema extends z.ZodObject<z.ZodRawShape>> {
+  persistence: () => Promise<Persistence>;
+  config: () => Omit<LazyCollectionConfig<TSchema>, "material">;
+}
+declare const collection: {
+  create<TSchema extends z.ZodObject<z.ZodRawShape>>(options: CreateCollectionOptions<TSchema>): LazyCollection<z.infer<TSchema>>;
 };
-import { extract } from '$/client/merge.js';
-export declare const prose: {
-    readonly extract: typeof extract;
+//#endregion
+//#region src/client/merge.d.ts
+/**
+ * Extract plain text from ProseMirror/BlockNote JSON content.
+ * Handles various content structures defensively for search and display.
+ */
+declare function extract(content: unknown): string;
+//#endregion
+//#region src/client/prose-schema.d.ts
+declare function emptyProse(): ProseValue;
+declare function prose$1(): z.ZodType<ProseValue>;
+declare namespace prose$1 {
+  var empty: typeof emptyProse;
+}
+//#endregion
+//#region src/client/persistence/memory.d.ts
+/**
+ * Create an in-memory persistence factory.
+ *
+ * Useful for testing where you don't want IndexedDB side effects.
+ *
+ * @example
+ * ```typescript
+ * // In tests
+ * convexCollectionOptions<Task>({
+ *   // ... other options
+ *   persistence: memoryPersistence(),
+ * });
+ * ```
+ */
+declare function memoryPersistence(): Persistence;
+//#endregion
+//#region src/client/persistence/sqlite/browser.d.ts
+interface SqlJsDatabase {
+  run(sql: string, params?: unknown): unknown;
+  prepare(sql: string): {
+    bind(params?: unknown): void;
+    step(): boolean;
+    getAsObject(): Record<string, unknown>;
+    free(): void;
+  };
+  export(): Uint8Array;
+  close(): void;
+}
+interface SqlJsStatic {
+  Database: new (data?: ArrayLike<number> | Buffer | null) => SqlJsDatabase;
+}
+declare function createBrowserSqlitePersistence(SQL: SqlJsStatic, dbName: string): Promise<Persistence>;
+//#endregion
+//#region src/client/persistence/sqlite/native.d.ts
+interface OPSQLiteDatabase {
+  execute(sql: string, params?: unknown[]): Promise<{
+    rows: Record<string, unknown>[];
+  }>;
+  close(): void;
+}
+declare function createNativeSqlitePersistence(db: OPSQLiteDatabase, _dbName: string): Promise<Persistence>;
+//#endregion
+//#region src/client/persistence/indexeddb.d.ts
+declare function createIndexedDBPersistence(dbName: string): Promise<Persistence>;
+//#endregion
+//#region src/client/persistence/custom.d.ts
+declare function createCustomPersistence(adapter: StorageAdapter): Persistence;
+//#endregion
+//#region src/client/persistence/index.d.ts
+declare const persistence: {
+  readonly memory: typeof memoryPersistence;
+  readonly sqlite: {
+    readonly browser: typeof createBrowserSqlitePersistence;
+    readonly native: typeof createNativeSqlitePersistence;
+  };
+  readonly indexeddb: typeof createIndexedDBPersistence;
+  readonly custom: typeof createCustomPersistence;
 };
-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 declare const adapters: {
-    readonly sqljs: typeof SqlJsAdapter;
-    readonly opsqlite: typeof OPSqliteAdapter;
+//#endregion
+//#region src/client/index.d.ts
+declare const errors: {
+  readonly Network: typeof NetworkError;
+  readonly IDB: typeof IDBError;
+  readonly IDBWrite: typeof IDBWriteError;
+  readonly Reconciliation: typeof ReconciliationError;
+  readonly Prose: typeof ProseError;
+  readonly CollectionNotReady: typeof CollectionNotReadyError;
+  readonly NonRetriable: typeof NonRetriableError;
 };
-export type { SqlJsDatabase, SqlJsAdapterOptions, OPSQLiteDatabase, } from '$/client/persistence/adapters/index.js';
+declare function empty(): ProseValue;
+declare const prose: typeof prose$1 & {
+  extract: typeof extract;
+  empty: typeof empty;
+};
+//#endregion
+export { type ConvexCollection, type EditorBinding, type Materialized, type Persistence, type StorageAdapter, collection, errors, persistence, prose };