@strata-sync/client 0.1.0

package/src/client.ts

@@ -0,0 +1,1051 @@
+import type {
+  ConnectionState,
+  SyncClientState,
+  SyncStore,
+  Transaction,
+  TransactionAction,
+} from "@strata-sync/core";
+import {
+  generateUUID,
+  getOrCreateClientId,
+  ModelRegistry,
+} from "@strata-sync/core";
+import { YjsDocumentManager, YjsPresenceManager } from "@strata-sync/yjs";
+import { IdentityMapRegistry } from "./identity-map";
+import { OutboxManager } from "./outbox-manager";
+import { executeQuery } from "./query";
+import { SyncOrchestrator } from "./sync-orchestrator";
+import type {
+  ModelFactory,
+  ModelFactoryFactory,
+  ModelStore,
+  QueryOptions,
+  QueryResult,
+  SyncClient,
+  SyncClientEvent,
+  SyncClientOptions,
+} from "./types";
+
+/**
+ * Creates a sync client instance
+ */
+export function createSyncClient(options: SyncClientOptions): SyncClient {
+  const resolvedOptions: SyncClientOptions = { ...options };
+
+  const identityMaps = new IdentityMapRegistry(resolvedOptions.reactivity);
+  const eventListeners = new Set<(event: SyncClientEvent) => void>();
+  const missingModels = new Set<string>();
+  const pendingLoads = new Map<string, Promise<unknown | null>>();
+  const pendingIndexLoads = new Map<
+    string,
+    Promise<Record<string, unknown>[]>
+  >();
+
+  interface HistoryOperation {
+    action: TransactionAction;
+    modelName: string;
+    modelId: string;
+    payload: Record<string, unknown>;
+    original?: Record<string, unknown>;
+  }
+
+  interface HistoryEntry {
+    id?: string;
+    undo: HistoryOperation;
+    redo: HistoryOperation;
+  }
+
+  const undoStack: HistoryEntry[] = [];
+  const redoStack: HistoryEntry[] = [];
+  let suppressHistory = false;
+
+  const pushHistory = (entry: HistoryEntry | null): void => {
+    if (!entry || suppressHistory) {
+      return;
+    }
+    undoStack.push(entry);
+    redoStack.length = 0;
+  };
+
+  const removeHistoryByTxId = (clientTxId: string): void => {
+    const removeMatches = (stack: HistoryEntry[]): void => {
+      for (let i = stack.length - 1; i >= 0; i--) {
+        if (stack[i]?.id === clientTxId) {
+          stack.splice(i, 1);
+        }
+      }
+    };
+    removeMatches(undoStack);
+    removeMatches(redoStack);
+  };
+  const getModelKey = (modelName: string, id: string): string => {
+    return `${modelName}:${id}`;
+  };
+
+  const getModelData = (
+    value: Record<string, unknown>
+  ): Record<string, unknown> => {
+    const candidate = value as { toJSON?: () => Record<string, unknown> };
+    if (typeof candidate?.toJSON === "function") {
+      return candidate.toJSON();
+    }
+    return value;
+  };
+
+  const pickOriginal = (
+    existing: Record<string, unknown>,
+    changes: Record<string, unknown>
+  ): Record<string, unknown> => {
+    const original: Record<string, unknown> = {};
+    for (const key of Object.keys(changes)) {
+      original[key] = existing[key];
+    }
+    return original;
+  };
+
+  const buildHistoryEntry = (
+    action: TransactionAction,
+    modelName: string,
+    modelId: string,
+    payload: Record<string, unknown>,
+    original?: Record<string, unknown>
+  ): HistoryEntry | null => {
+    const redo: HistoryOperation = {
+      action,
+      modelName,
+      modelId,
+      payload,
+      original,
+    };
+
+    let undo: HistoryOperation | null = null;
+
+    switch (action) {
+      case "I":
+        undo = {
+          action: "D",
+          modelName,
+          modelId,
+          payload: {},
+          original: payload,
+        };
+        break;
+      case "D":
+        if (original) {
+          undo = {
+            action: "I",
+            modelName,
+            modelId,
+            payload: original,
+          };
+        }
+        break;
+      case "U":
+        if (original) {
+          undo = {
+            action: "U",
+            modelName,
+            modelId,
+            payload: original,
+            original: payload,
+          };
+        }
+        break;
+      case "A": {
+        const archivedAt = payload.archivedAt as string | undefined;
+        undo = {
+          action: "V",
+          modelName,
+          modelId,
+          payload: {},
+          original: { archivedAt },
+        };
+        break;
+      }
+      case "V": {
+        const archivedAt = original?.archivedAt as string | undefined;
+        undo = {
+          action: "A",
+          modelName,
+          modelId,
+          payload: { archivedAt: archivedAt ?? new Date().toISOString() },
+          original: { archivedAt: undefined },
+        };
+        break;
+      }
+      default:
+        break;
+    }
+
+    if (!undo) {
+      return null;
+    }
+    return { undo, redo };
+  };
+
+  const emitEvent = (event: SyncClientEvent): void => {
+    if (event.type === "modelChange") {
+      const key = getModelKey(event.modelName, event.modelId);
+      if (event.action === "delete") {
+        missingModels.add(key);
+      } else {
+        missingModels.delete(key);
+      }
+    }
+
+    for (const listener of eventListeners) {
+      listener(event);
+    }
+  };
+
+  const rollbackTransaction = (tx: Transaction): void => {
+    const map = identityMaps.getMap<Record<string, unknown>>(tx.modelName);
+    const existing = map.get(tx.modelId);
+    const original = tx.original;
+
+    switch (tx.action) {
+      case "I": {
+        if (existing) {
+          map.delete(tx.modelId);
+          emitEvent({
+            type: "modelChange",
+            modelName: tx.modelName,
+            modelId: tx.modelId,
+            action: "delete",
+          });
+        }
+        break;
+      }
+      case "D": {
+        if (original) {
+          map.set(tx.modelId, original as Record<string, unknown>);
+          emitEvent({
+            type: "modelChange",
+            modelName: tx.modelName,
+            modelId: tx.modelId,
+            action: "insert",
+          });
+        }
+        break;
+      }
+      case "U": {
+        if (!original) {
+          break;
+        }
+        if (existing) {
+          map.update(tx.modelId, original as Record<string, unknown>);
+          emitEvent({
+            type: "modelChange",
+            modelName: tx.modelName,
+            modelId: tx.modelId,
+            action: "update",
+          });
+        } else {
+          map.set(tx.modelId, original as Record<string, unknown>);
+          emitEvent({
+            type: "modelChange",
+            modelName: tx.modelName,
+            modelId: tx.modelId,
+            action: "insert",
+          });
+        }
+        break;
+      }
+      case "A":
+      case "V": {
+        if (existing) {
+          const archivedAt =
+            (original as Record<string, unknown> | undefined)?.archivedAt ??
+            undefined;
+          map.update(tx.modelId, { archivedAt } as Record<string, unknown>);
+          emitEvent({
+            type: "modelChange",
+            modelName: tx.modelName,
+            modelId: tx.modelId,
+            action: "update",
+          });
+        } else if (original) {
+          map.set(tx.modelId, original as Record<string, unknown>);
+          emitEvent({
+            type: "modelChange",
+            modelName: tx.modelName,
+            modelId: tx.modelId,
+            action: "insert",
+          });
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  };
+
+  const applyHistoryOperation = async (
+    operation: HistoryOperation
+  ): Promise<string | undefined> => {
+    const client = getClientRef();
+    let txId: string | undefined;
+    const capture = (tx: Transaction) => {
+      txId = tx.clientTxId;
+    };
+
+    switch (operation.action) {
+      case "I":
+        await client.create(operation.modelName, operation.payload, {
+          onTransactionCreated: capture,
+        });
+        break;
+      case "U":
+        await client.update(
+          operation.modelName,
+          operation.modelId,
+          operation.payload,
+          {
+            original: operation.original,
+            onTransactionCreated: capture,
+          }
+        );
+        break;
+      case "D":
+        await client.delete(operation.modelName, operation.modelId, {
+          original: operation.original,
+          onTransactionCreated: capture,
+        });
+        break;
+      case "A":
+        await client.archive(operation.modelName, operation.modelId, {
+          original: operation.original,
+          archivedAt: operation.payload.archivedAt as string | undefined,
+          onTransactionCreated: capture,
+        });
+        break;
+      case "V":
+        await client.unarchive(operation.modelName, operation.modelId, {
+          original: operation.original,
+          onTransactionCreated: capture,
+        });
+        break;
+      default:
+        break;
+    }
+
+    return txId;
+  };
+
+  const orchestrator = new SyncOrchestrator(
+    resolvedOptions,
+    identityMaps,
+    emitEvent
+  );
+
+  let yjsManagers: SyncClient["yjs"] | undefined;
+  if (resolvedOptions.yjsTransport) {
+    const clientId = getOrCreateClientId(
+      `${resolvedOptions.dbName ?? "sync-db"}_client_id`
+    );
+    const connId = generateUUID();
+    const documentManager = new YjsDocumentManager({
+      clientId,
+      connId,
+    });
+    const presenceManager = new YjsPresenceManager({
+      clientId,
+      connId,
+    });
+
+    documentManager.setTransport(resolvedOptions.yjsTransport);
+    presenceManager.setTransport(resolvedOptions.yjsTransport);
+
+    yjsManagers = { documentManager, presenceManager };
+  }
+
+  let outboxManager: OutboxManager | null = null;
+
+  const buildOutboxOptions = () => ({
+    storage: options.storage,
+    transport: options.transport,
+    clientId: orchestrator.getClientId() || "temp",
+    batchMutations: options.batchMutations,
+    batchDelay: options.batchDelay,
+    onTransactionStateChange: () => {
+      emitPendingCount().catch((error) => {
+        console.error("Failed to emit pending count", error);
+      });
+    },
+    onTransactionRejected: (tx: Transaction) => {
+      rollbackTransaction(tx);
+      removeHistoryByTxId(tx.clientTxId);
+    },
+  });
+
+  const emitPendingCount = async (): Promise<void> => {
+    if (!outboxManager) {
+      return;
+    }
+    const pendingCount = await outboxManager.getPendingCount();
+    emitEvent({ type: "outboxChange", pendingCount });
+  };
+
+  const processBatchLoadRow = async (
+    row: import("@strata-sync/core").ModelRow
+  ): Promise<string | undefined> => {
+    const rowPrimaryKey = orchestrator
+      .getRegistry()
+      .getPrimaryKey(row.modelName);
+    const rowId = row.data[rowPrimaryKey] as string;
+    if (typeof rowId !== "string") {
+      return undefined;
+    }
+    await options.storage.put(row.modelName, row.data);
+    const rowMap = identityMaps.getMap<Record<string, unknown>>(row.modelName);
+    const existed = rowMap.has(rowId);
+    rowMap.merge(rowId, row.data);
+    emitEvent({
+      type: "modelChange",
+      modelName: row.modelName,
+      modelId: rowId,
+      action: existed ? "update" : "insert",
+    });
+    return rowId;
+  };
+
+  const ensureModelInternal = async <T>(
+    modelName: string,
+    id: string
+  ): Promise<T | null> => {
+    const map = identityMaps.getMap<T & Record<string, unknown>>(modelName);
+    const cached = map.get(id);
+    if (cached) {
+      return cached as T;
+    }
+
+    const stored = await options.storage.get<T>(modelName, id);
+    if (stored) {
+      map.set(id, stored as T & Record<string, unknown>);
+      const key = getModelKey(modelName, id);
+      missingModels.delete(key);
+      return stored;
+    }
+
+    const model = orchestrator.getRegistry().getModelMetadata(modelName);
+    if (!model) {
+      return null;
+    }
+
+    const loadStrategy = model.loadStrategy ?? "instant";
+    if (loadStrategy === "instant" || loadStrategy === "local") {
+      const key = getModelKey(modelName, id);
+      missingModels.add(key);
+      return null;
+    }
+
+    const key = getModelKey(modelName, id);
+    const pending = pendingLoads.get(key);
+    if (pending) {
+      return pending as Promise<T | null>;
+    }
+
+    const loadPromise = (async () => {
+      let found: T | null = null;
+      const primaryKey = orchestrator.getRegistry().getPrimaryKey(modelName);
+      const stream = options.transport.batchLoad({
+        firstSyncId: orchestrator.getFirstSyncId(),
+        requests: [
+          {
+            modelName,
+            indexedKey: primaryKey,
+            keyValue: id,
+          },
+        ],
+      });
+
+      for await (const row of stream) {
+        const rowId = await processBatchLoadRow(row);
+        if (row.modelName === modelName && rowId === id) {
+          found = row.data as T;
+        }
+      }
+
+      if (found) {
+        missingModels.delete(key);
+      } else {
+        missingModels.add(key);
+      }
+
+      return found;
+    })();
+
+    pendingLoads.set(key, loadPromise);
+
+    try {
+      return await loadPromise;
+    } finally {
+      pendingLoads.delete(key);
+    }
+  };
+
+  const loadByIndexInternal = async <T extends Record<string, unknown>>(
+    modelName: string,
+    indexedKey: string,
+    keyValue: string
+  ): Promise<T[]> => {
+    const model = orchestrator.getRegistry().getModelMetadata(modelName);
+    const isPartial = model?.loadStrategy === "partial";
+
+    if (!isPartial) {
+      return options.storage.getByIndex<T>(modelName, indexedKey, keyValue);
+    }
+
+    const hasIndex = await options.storage.hasPartialIndex(
+      modelName,
+      indexedKey,
+      keyValue
+    );
+
+    if (hasIndex) {
+      return options.storage.getByIndex<T>(modelName, indexedKey, keyValue);
+    }
+
+    const loadKey = `${modelName}:${indexedKey}:${keyValue}`;
+    const pending = pendingIndexLoads.get(loadKey);
+    if (pending) {
+      return pending as Promise<T[]>;
+    }
+
+    const loadPromise = (async () => {
+      const stream = options.transport.batchLoad({
+        firstSyncId: orchestrator.getFirstSyncId(),
+        requests: [
+          {
+            modelName,
+            indexedKey,
+            keyValue,
+          },
+        ],
+      });
+
+      for await (const row of stream) {
+        await processBatchLoadRow(row);
+      }
+
+      await options.storage.setPartialIndex(modelName, indexedKey, keyValue);
+      return options.storage.getByIndex<T>(modelName, indexedKey, keyValue);
+    })();
+
+    pendingIndexLoads.set(loadKey, loadPromise);
+
+    try {
+      return await loadPromise;
+    } finally {
+      pendingIndexLoads.delete(loadKey);
+    }
+  };
+
+  let clientRef: SyncClient | null = null;
+
+  const getClientRef = (): SyncClient => {
+    if (!clientRef) {
+      throw new Error("Sync client is not initialized");
+    }
+    return clientRef;
+  };
+
+  const modelStore: ModelStore & SyncStore = {
+    get: ensureModelInternal,
+    getByIndex: (modelName, indexName, key) =>
+      options.storage.getByIndex(modelName, indexName, key),
+    loadByIndex: loadByIndexInternal,
+    hasPartialIndex: (modelName, indexName, key) =>
+      options.storage.hasPartialIndex(modelName, indexName, key),
+    setPartialIndex: (modelName, indexName, key) =>
+      options.storage.setPartialIndex(modelName, indexName, key),
+    create: (modelName, data) => {
+      const client = getClientRef();
+      return client.create(modelName, data);
+    },
+    update: (modelName, id, changes, options) => {
+      const client = getClientRef();
+      return client.update(modelName, id, changes, options);
+    },
+    delete: (modelName, id, options) => {
+      const client = getClientRef();
+      return client.delete(modelName, id, options);
+    },
+    archive: (modelName, id, options) => {
+      const client = getClientRef();
+      return client.archive(modelName, id, options);
+    },
+    unarchive: (modelName, id, options) => {
+      const client = getClientRef();
+      return client.unarchive(modelName, id, options);
+    },
+  };
+
+  const defaultModelFactory: ModelFactoryFactory = ({ store }) => {
+    return (modelName: string, data: Record<string, unknown>) => {
+      const ctor = ModelRegistry.getModelConstructor(modelName);
+      if (!ctor) {
+        return data;
+      }
+      const instance = new ctor() as Record<string, unknown>;
+      const candidate = instance as {
+        store?: SyncStore;
+        _applyUpdate?: (changes: Record<string, unknown>) => void;
+      };
+      if ("store" in candidate) {
+        candidate.store = store;
+      }
+      if (typeof candidate._applyUpdate === "function") {
+        candidate._applyUpdate(data);
+      } else {
+        Object.assign(instance, data);
+      }
+      return instance;
+    };
+  };
+
+  const resolveModelFactory = (
+    factory: ModelFactory | ModelFactoryFactory | undefined
+  ): ModelFactory | undefined => {
+    if (!factory) {
+      return undefined;
+    }
+    if (typeof factory === "function" && factory.length <= 1) {
+      return (factory as ModelFactoryFactory)({ store: modelStore });
+    }
+    return factory as ModelFactory;
+  };
+
+  const resolvedModelFactory = resolveModelFactory(
+    resolvedOptions.modelFactory ?? defaultModelFactory
+  );
+  identityMaps.setModelFactory(resolvedModelFactory);
+
+  const client: SyncClient = {
+    get state(): SyncClientState {
+      return orchestrator.state;
+    },
+
+    get connectionState(): ConnectionState {
+      return orchestrator.connectionState;
+    },
+
+    get lastSyncId(): number {
+      return orchestrator.getLastSyncId();
+    },
+
+    get lastError(): Error | null {
+      return orchestrator.getLastError();
+    },
+
+    get clientId(): string {
+      return orchestrator.getClientId();
+    },
+
+    yjs: yjsManagers,
+
+    async start(): Promise<void> {
+      outboxManager = new OutboxManager(buildOutboxOptions());
+      orchestrator.setOutboxManager(outboxManager);
+      orchestrator.setConflictHandler((tx) => {
+        rollbackTransaction(tx);
+        removeHistoryByTxId(tx.clientTxId);
+      });
+      await orchestrator.start();
+
+      // Recreate with correct client ID after orchestrator resolves it
+      outboxManager = new OutboxManager(buildOutboxOptions());
+      orchestrator.setOutboxManager(outboxManager);
+
+      await emitPendingCount();
+    },
+
+    async stop(): Promise<void> {
+      await orchestrator.stop();
+    },
+
+    async get<T>(modelName: string, id: string): Promise<T | null> {
+      // Try identity map first
+      const map = identityMaps.getMap<T & Record<string, unknown>>(modelName);
+      const cached = map.get(id);
+      if (cached) {
+        return cached as T;
+      }
+
+      // Fall back to storage
+      const stored = await options.storage.get<T>(modelName, id);
+      if (stored) {
+        // Cache in identity map
+        map.set(id, stored as T & Record<string, unknown>);
+      }
+      return stored;
+    },
+
+    getCached<T>(modelName: string, id: string): T | null {
+      const map = identityMaps.getMap<T & Record<string, unknown>>(modelName);
+      const cached = map.get(id);
+      return cached ? (cached as T) : null;
+    },
+
+    ensureModel<T>(modelName: string, id: string): Promise<T | null> {
+      return ensureModelInternal(modelName, id);
+    },
+
+    getAll<T>(modelName: string, queryOptions?: QueryOptions<T>): Promise<T[]> {
+      const map = identityMaps.getMap<T & Record<string, unknown>>(modelName);
+      const result = executeQuery(map, queryOptions);
+      return Promise.resolve(result.data as T[]);
+    },
+
+    query<T>(
+      modelName: string,
+      queryOptions?: QueryOptions<T>
+    ): Promise<QueryResult<T>> {
+      const map = identityMaps.getMap<T & Record<string, unknown>>(modelName);
+      return Promise.resolve(executeQuery(map, queryOptions) as QueryResult<T>);
+    },
+
+    async create<T extends Record<string, unknown>>(
+      modelName: string,
+      data: T,
+      mutationOptions?: { onTransactionCreated?: (tx: Transaction) => void }
+    ): Promise<T> {
+      const primaryKey = orchestrator.getRegistry().getPrimaryKey(modelName);
+
+      // Generate ID if not provided
+      const id = (data[primaryKey] as string) || generateUUID();
+      const fullData = { ...data, [primaryKey]: id };
+
+      // Optimistic update
+      if (resolvedOptions.optimistic !== false) {
+        const map = identityMaps.getMap<T>(modelName);
+        map.set(id, fullData);
+        missingModels.delete(getModelKey(modelName, id));
+        emitEvent({
+          type: "modelChange",
+          modelName,
+          modelId: id,
+          action: "insert",
+        });
+      }
+
+      let queuedTx: Transaction | undefined;
+      if (outboxManager) {
+        queuedTx = await outboxManager.insert(modelName, id, fullData);
+        mutationOptions?.onTransactionCreated?.(queuedTx);
+      }
+
+      const historyEntry = buildHistoryEntry("I", modelName, id, fullData);
+      if (historyEntry) {
+        historyEntry.id = queuedTx?.clientTxId;
+        pushHistory(historyEntry);
+      }
+
+      return fullData;
+    },
+
+    async update<T extends Record<string, unknown>>(
+      modelName: string,
+      id: string,
+      changes: Partial<T>,
+      mutationOptions?: {
+        original?: Record<string, unknown>;
+        onTransactionCreated?: (tx: Transaction) => void;
+      }
+    ): Promise<T> {
+      const map = identityMaps.getMap<T>(modelName);
+      const existing = map.get(id);
+
+      if (!existing) {
+        throw new Error(`Model ${modelName} with id ${id} not found`);
+      }
+
+      const existingData = getModelData(existing);
+      const original =
+        mutationOptions?.original ??
+        pickOriginal(existingData, changes as Record<string, unknown>);
+      const updated = { ...existingData, ...changes } as T;
+
+      // Optimistic update
+      if (resolvedOptions.optimistic !== false) {
+        map.update(id, changes);
+        missingModels.delete(getModelKey(modelName, id));
+        emitEvent({
+          type: "modelChange",
+          modelName,
+          modelId: id,
+          action: "update",
+        });
+      }
+
+      let queuedTx: Transaction | undefined;
+      if (outboxManager) {
+        queuedTx = await outboxManager.update(
+          modelName,
+          id,
+          changes as Record<string, unknown>,
+          original
+        );
+        mutationOptions?.onTransactionCreated?.(queuedTx);
+      }
+
+      const historyEntry = buildHistoryEntry(
+        "U",
+        modelName,
+        id,
+        changes as Record<string, unknown>,
+        original
+      );
+      if (historyEntry) {
+        historyEntry.id = queuedTx?.clientTxId;
+        pushHistory(historyEntry);
+      }
+
+      return updated;
+    },
+
+    async delete(
+      modelName: string,
+      id: string,
+      mutationOptions?: {
+        original?: Record<string, unknown>;
+        onTransactionCreated?: (tx: Transaction) => void;
+      }
+    ): Promise<void> {
+      const map = identityMaps.getMap(modelName);
+      const existing = map.get(id);
+
+      if (!existing) {
+        throw new Error(`Model ${modelName} with id ${id} not found`);
+      }
+
+      // Optimistic delete
+      if (resolvedOptions.optimistic !== false) {
+        map.delete(id);
+        emitEvent({
+          type: "modelChange",
+          modelName,
+          modelId: id,
+          action: "delete",
+        });
+      }
+
+      const original = mutationOptions?.original ?? getModelData(existing);
+      let queuedTx: Transaction | undefined;
+      if (outboxManager) {
+        queuedTx = await outboxManager.delete(modelName, id, original);
+        mutationOptions?.onTransactionCreated?.(queuedTx);
+      }
+
+      const historyEntry = buildHistoryEntry("D", modelName, id, {}, original);
+      if (historyEntry) {
+        historyEntry.id = queuedTx?.clientTxId;
+        pushHistory(historyEntry);
+      }
+    },
+
+    async archive(
+      modelName: string,
+      id: string,
+      mutationOptions?: {
+        original?: Record<string, unknown>;
+        archivedAt?: string;
+        onTransactionCreated?: (tx: Transaction) => void;
+      }
+    ): Promise<void> {
+      const map = identityMaps.getMap(modelName);
+      const existing = map.get(id);
+
+      if (!existing) {
+        throw new Error(`Model ${modelName} with id ${id} not found`);
+      }
+
+      const existingData = getModelData(existing);
+      const archivedAt =
+        mutationOptions?.archivedAt ?? new Date().toISOString();
+      const original = mutationOptions?.original ?? {
+        archivedAt: existingData.archivedAt,
+      };
+      const archived = {
+        ...existingData,
+        archivedAt,
+      };
+
+      // Optimistic archive
+      if (resolvedOptions.optimistic !== false) {
+        map.update(id, { archivedAt: archived.archivedAt } as Record<
+          string,
+          unknown
+        >);
+        emitEvent({
+          type: "modelChange",
+          modelName,
+          modelId: id,
+          action: "archive",
+        });
+      }
+
+      let queuedTx: Transaction | undefined;
+      if (outboxManager) {
+        queuedTx = await outboxManager.archive(modelName, id, {
+          original,
+          archivedAt,
+        });
+        mutationOptions?.onTransactionCreated?.(queuedTx);
+      }
+
+      const historyEntry = buildHistoryEntry(
+        "A",
+        modelName,
+        id,
+        { archivedAt },
+        original
+      );
+      if (historyEntry) {
+        historyEntry.id = queuedTx?.clientTxId;
+        pushHistory(historyEntry);
+      }
+    },
+
+    async unarchive(
+      modelName: string,
+      id: string,
+      mutationOptions?: {
+        original?: Record<string, unknown>;
+        onTransactionCreated?: (tx: Transaction) => void;
+      }
+    ): Promise<void> {
+      const map = identityMaps.getMap(modelName);
+      const existing = map.get(id);
+
+      if (!existing) {
+        throw new Error(`Model ${modelName} with id ${id} not found`);
+      }
+
+      const existingData = getModelData(existing);
+      const original = mutationOptions?.original ?? {
+        archivedAt: existingData.archivedAt,
+      };
+
+      // Optimistic unarchive
+      if (resolvedOptions.optimistic !== false) {
+        map.update(id, { archivedAt: undefined } as Record<string, unknown>);
+        emitEvent({
+          type: "modelChange",
+          modelName,
+          modelId: id,
+          action: "unarchive",
+        });
+      }
+
+      let queuedTx: Transaction | undefined;
+      if (outboxManager) {
+        queuedTx = await outboxManager.unarchive(modelName, id, { original });
+        mutationOptions?.onTransactionCreated?.(queuedTx);
+      }
+
+      const historyEntry = buildHistoryEntry("V", modelName, id, {}, original);
+      if (historyEntry) {
+        historyEntry.id = queuedTx?.clientTxId;
+        pushHistory(historyEntry);
+      }
+    },
+
+    canUndo(): boolean {
+      return undoStack.length > 0;
+    },
+
+    canRedo(): boolean {
+      return redoStack.length > 0;
+    },
+
+    async undo(): Promise<void> {
+      const entry = undoStack.pop();
+      if (!entry) {
+        return;
+      }
+
+      suppressHistory = true;
+      try {
+        const txId = await applyHistoryOperation(entry.undo);
+        entry.id = txId;
+        redoStack.push(entry);
+      } catch (error) {
+        undoStack.push(entry);
+        throw error;
+      } finally {
+        suppressHistory = false;
+      }
+    },
+
+    async redo(): Promise<void> {
+      const entry = redoStack.pop();
+      if (!entry) {
+        return;
+      }
+
+      suppressHistory = true;
+      try {
+        const txId = await applyHistoryOperation(entry.redo);
+        entry.id = txId;
+        undoStack.push(entry);
+      } catch (error) {
+        redoStack.push(entry);
+        throw error;
+      } finally {
+        suppressHistory = false;
+      }
+    },
+
+    onStateChange(callback: (state: SyncClientState) => void): () => void {
+      return orchestrator.onStateChange(callback);
+    },
+
+    onConnectionStateChange(
+      callback: (state: ConnectionState) => void
+    ): () => void {
+      return orchestrator.onConnectionStateChange(callback);
+    },
+
+    onEvent(callback: (event: SyncClientEvent) => void): () => void {
+      eventListeners.add(callback);
+      return () => {
+        eventListeners.delete(callback);
+      };
+    },
+
+    getPendingCount(): Promise<number> {
+      if (!outboxManager) {
+        return Promise.resolve(0);
+      }
+      return outboxManager.getPendingCount();
+    },
+
+    async syncNow(): Promise<void> {
+      await orchestrator.syncNow();
+    },
+
+    async clearAll(): Promise<void> {
+      identityMaps.clearAll();
+      await options.storage.clear();
+      pendingLoads.clear();
+      missingModels.clear();
+      undoStack.length = 0;
+      redoStack.length = 0;
+      emitEvent({ type: "outboxChange", pendingCount: 0 });
+    },
+
+    getIdentityMap<T>(modelName: string): Map<string, T> {
+      return identityMaps
+        .getMap<T & Record<string, unknown>>(modelName)
+        .getRawMap() as Map<string, T>;
+    },
+
+    isModelMissing(modelName: string, id: string): boolean {
+      return missingModels.has(getModelKey(modelName, id));
+    },
+  };
+
+  clientRef = client;
+  return client;
+}