@strata-sync/client 0.1.0

package/src/identity-map.ts

@@ -0,0 +1,294 @@
+import type { ObservableMap, ReactivityAdapter } from "@strata-sync/core";
+import type { ModelFactory } from "./types";
+
+interface ModelInstanceLike {
+  _applyUpdate?: (data: Record<string, unknown>) => void;
+  makeObservable?: () => void;
+  toJSON?: () => Record<string, unknown>;
+}
+
+const isModelInstanceLike = (value: unknown): value is ModelInstanceLike => {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record._applyUpdate === "function" ||
+    typeof record.makeObservable === "function"
+  );
+};
+
+/**
+ * Identity map for managing model instances
+ * Ensures only one instance exists per model+id combination
+ */
+export class IdentityMap<T extends Record<string, unknown>> {
+  private readonly map: ObservableMap<string, T>;
+  private readonly modelName: string;
+  private readonly reactivity: ReactivityAdapter;
+  private modelFactory?: ModelFactory;
+
+  constructor(
+    modelName: string,
+    reactivity: ReactivityAdapter,
+    modelFactory?: ModelFactory
+  ) {
+    this.modelName = modelName;
+    this.reactivity = reactivity;
+    this.modelFactory = modelFactory;
+    this.map = reactivity.createMap<string, T>(undefined, {
+      name: `IdentityMap:${modelName}`,
+    });
+  }
+
+  setModelFactory(modelFactory?: ModelFactory): void {
+    this.modelFactory = modelFactory;
+  }
+
+  private ensureObservable(instance: T): T {
+    if (
+      isModelInstanceLike(instance) &&
+      typeof instance.makeObservable === "function"
+    ) {
+      instance.makeObservable();
+    }
+    return instance;
+  }
+
+  private toInstance(data: T): T {
+    if (!this.modelFactory || isModelInstanceLike(data)) {
+      return this.ensureObservable(data);
+    }
+
+    const instance = this.modelFactory(
+      this.modelName,
+      data as Record<string, unknown>
+    ) as T;
+    return this.ensureObservable(instance);
+  }
+
+  /**
+   * Gets a model instance by ID
+   */
+  get(id: string): T | undefined {
+    return this.map.get(id);
+  }
+
+  /**
+   * Checks if a model instance exists
+   */
+  has(id: string): boolean {
+    return this.map.has(id);
+  }
+
+  /**
+   * Sets a model instance, replacing any existing instance
+   */
+  set(id: string, instance: T): void {
+    this.reactivity.runInAction(() => {
+      this.map.set(id, this.toInstance(instance));
+    });
+  }
+
+  /**
+   * Updates an existing model instance in place
+   */
+  update(id: string, changes: Partial<T>): T | undefined {
+    const existing = this.map.get(id);
+    if (!existing) {
+      return undefined;
+    }
+
+    this.reactivity.runInAction(() => {
+      this.applyChanges(existing, changes);
+      this.map.set(id, this.ensureObservable(existing));
+    });
+
+    return this.map.get(id);
+  }
+
+  /**
+   * Merges data into an existing instance or creates a new one
+   */
+  merge(id: string, data: Partial<T>): T {
+    return this.reactivity.runInAction(() => {
+      const existing = this.map.get(id);
+      if (existing) {
+        this.applyChanges(existing, data);
+        this.map.set(id, this.ensureObservable(existing));
+        return existing;
+      }
+      const merged = this.toInstance(data as T);
+      this.map.set(id, merged);
+      return merged;
+    });
+  }
+
+  /**
+   * Deletes a model instance
+   */
+  delete(id: string): boolean {
+    return this.reactivity.runInAction(() => {
+      return this.map.delete(id);
+    });
+  }
+
+  /**
+   * Clears all model instances
+   */
+  clear(): void {
+    this.reactivity.runInAction(() => {
+      this.map.clear();
+    });
+  }
+
+  /**
+   * Gets all model instances
+   */
+  values(): T[] {
+    return Array.from(this.map.values());
+  }
+
+  /**
+   * Gets all model IDs
+   */
+  keys(): string[] {
+    return Array.from(this.map.keys());
+  }
+
+  /**
+   * Gets all entries
+   */
+  entries(): [string, T][] {
+    return Array.from(this.map.entries());
+  }
+
+  /**
+   * Gets the number of instances
+   */
+  get size(): number {
+    return this.map.size;
+  }
+
+  /**
+   * Iterates over all instances
+   */
+  forEach(callback: (value: T, key: string) => void): void {
+    this.map.forEach(callback);
+  }
+
+  /**
+   * Finds an instance matching a predicate
+   */
+  find(predicate: (value: T) => boolean): T | undefined {
+    for (const value of this.map.values()) {
+      if (predicate(value)) {
+        return value;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Filters instances matching a predicate
+   */
+  filter(predicate: (value: T) => boolean): T[] {
+    return this.values().filter(predicate);
+  }
+
+  /**
+   * Gets the model name
+   */
+  getModelName(): string {
+    return this.modelName;
+  }
+
+  /**
+   * Gets the underlying map (for advanced usage)
+   */
+  getRawMap(): Map<string, T> {
+    return new Map(this.map.entries());
+  }
+
+  /**
+   * Applies changes to an existing instance, preserving identity
+   */
+  private applyChanges(target: T, changes: Partial<T>): void {
+    const candidate = target as ModelInstanceLike;
+
+    if (typeof candidate._applyUpdate === "function") {
+      candidate._applyUpdate(changes as Record<string, unknown>);
+      return;
+    }
+
+    Object.assign(target, changes);
+  }
+}
+
+/**
+ * Manages identity maps for all model types
+ */
+export class IdentityMapRegistry {
+  private readonly maps: Map<string, IdentityMap<Record<string, unknown>>> =
+    new Map();
+  private readonly reactivity: ReactivityAdapter;
+  private modelFactory?: ModelFactory;
+
+  constructor(reactivity: ReactivityAdapter, modelFactory?: ModelFactory) {
+    this.reactivity = reactivity;
+    this.modelFactory = modelFactory;
+  }
+
+  setModelFactory(modelFactory?: ModelFactory): void {
+    this.modelFactory = modelFactory;
+    for (const map of this.maps.values()) {
+      map.setModelFactory(modelFactory);
+    }
+  }
+
+  /**
+   * Gets or creates an identity map for a model type
+   */
+  getMap<T extends Record<string, unknown>>(modelName: string): IdentityMap<T> {
+    let map = this.maps.get(modelName);
+    if (!map) {
+      map = new IdentityMap<Record<string, unknown>>(
+        modelName,
+        this.reactivity,
+        this.modelFactory
+      );
+      this.maps.set(modelName, map);
+    }
+    return map as IdentityMap<T>;
+  }
+
+  /**
+   * Checks if a map exists for a model type
+   */
+  hasMap(modelName: string): boolean {
+    return this.maps.has(modelName);
+  }
+
+  /**
+   * Clears all identity maps
+   */
+  clearAll(): void {
+    for (const map of this.maps.values()) {
+      map.clear();
+    }
+  }
+
+  /**
+   * Clears a specific identity map
+   */
+  clear(modelName: string): void {
+    this.maps.get(modelName)?.clear();
+  }
+
+  /**
+   * Gets all model names with identity maps
+   */
+  getModelNames(): string[] {
+    return Array.from(this.maps.keys());
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+// biome-ignore-all lint/performance/noBarrelFile: public API
+export { createSyncClient } from "./client";
+export { IdentityMap, IdentityMapRegistry } from "./identity-map";
+export { OutboxManager } from "./outbox-manager";
+export {
+  and,
+  combineSorts,
+  contains,
+  eq,
+  executeQuery,
+  gt,
+  isIn,
+  lt,
+  matches,
+  neq,
+  not,
+  or,
+  sortBy,
+} from "./query";
+export { SyncOrchestrator } from "./sync-orchestrator";
+
+export type OutboxManagerOptions =
+  import("./outbox-manager").OutboxManagerOptions;
+export type QueryOptions<T> = import("./types").QueryOptions<T>;
+export type QueryResult<T> = import("./types").QueryResult<T>;
+export type StorageAdapter = import("./types").StorageAdapter;
+export type StorageMeta = import("./types").StorageMeta;
+export type SyncClient = import("./types").SyncClient;
+export type SyncClientEvent = import("./types").SyncClientEvent;
+export type SyncClientOptions = import("./types").SyncClientOptions;
+export type SyncModelInstance<T = Record<string, unknown>> =
+  import("./types").SyncModelInstance<T>;
+export type TransportAdapter = import("./types").TransportAdapter;

package/src/outbox-manager.ts

@@ -0,0 +1,399 @@
+import type { MutateResult, Transaction } from "@strata-sync/core";
+import {
+  createArchiveTransaction,
+  createDeleteTransaction,
+  createInsertTransaction,
+  createTransactionBatch,
+  createUnarchiveTransaction,
+  createUpdateTransaction,
+} from "@strata-sync/core";
+import type { StorageAdapter, TransportAdapter } from "./types";
+
+/**
+ * Options for the outbox manager
+ */
+export interface OutboxManagerOptions {
+  /** Storage adapter for persisting transactions */
+  storage: StorageAdapter;
+  /** Transport adapter for sending transactions */
+  transport: TransportAdapter;
+  /** Client ID */
+  clientId: string;
+  /** Batch mutations together */
+  batchMutations?: boolean;
+  /** Delay before sending batch (ms) */
+  batchDelay?: number;
+  /** Maximum batch size */
+  maxBatchSize?: number;
+  /** Callback when transaction state changes */
+  onTransactionStateChange?: (tx: Transaction) => void;
+  /** Callback when transaction is rejected by server */
+  onTransactionRejected?: (tx: Transaction) => void;
+}
+
+/**
+ * Manages the outbox queue of pending transactions
+ */
+export class OutboxManager {
+  private readonly storage: StorageAdapter;
+  private readonly transport: TransportAdapter;
+  private readonly clientId: string;
+  private readonly batchMutations: boolean;
+  private readonly batchDelay: number;
+  private readonly maxBatchSize: number;
+  private readonly onTransactionStateChange?: (tx: Transaction) => void;
+  private readonly onTransactionRejected?: (tx: Transaction) => void;
+
+  private pendingBatch: Transaction[] = [];
+  private batchTimer: ReturnType<typeof setTimeout> | null = null;
+  private processing = false;
+  private processingPromise: Promise<void> | null = null;
+
+  constructor(options: OutboxManagerOptions) {
+    this.storage = options.storage;
+    this.transport = options.transport;
+    this.clientId = options.clientId;
+    this.batchMutations = options.batchMutations ?? true;
+    this.batchDelay = options.batchDelay ?? 50;
+    this.maxBatchSize = options.maxBatchSize ?? 100;
+    this.onTransactionStateChange = options.onTransactionStateChange;
+    this.onTransactionRejected = options.onTransactionRejected;
+  }
+
+  /**
+   * Queues an INSERT transaction
+   */
+  async insert(
+    modelName: string,
+    modelId: string,
+    data: Record<string, unknown>
+  ): Promise<Transaction> {
+    const tx = createInsertTransaction(this.clientId, modelName, modelId, data);
+    await this.queueTransaction(tx);
+    return tx;
+  }
+
+  /**
+   * Queues an UPDATE transaction
+   */
+  async update(
+    modelName: string,
+    modelId: string,
+    changes: Record<string, unknown>,
+    original: Record<string, unknown>
+  ): Promise<Transaction> {
+    const tx = createUpdateTransaction(
+      this.clientId,
+      modelName,
+      modelId,
+      changes,
+      original
+    );
+    await this.queueTransaction(tx);
+    return tx;
+  }
+
+  /**
+   * Queues a DELETE transaction
+   */
+  async delete(
+    modelName: string,
+    modelId: string,
+    original: Record<string, unknown>
+  ): Promise<Transaction> {
+    const tx = createDeleteTransaction(
+      this.clientId,
+      modelName,
+      modelId,
+      original
+    );
+    await this.queueTransaction(tx);
+    return tx;
+  }
+
+  /**
+   * Queues an ARCHIVE transaction
+   */
+  async archive(
+    modelName: string,
+    modelId: string,
+    options: { original?: Record<string, unknown>; archivedAt?: string } = {}
+  ): Promise<Transaction> {
+    const tx = createArchiveTransaction(
+      this.clientId,
+      modelName,
+      modelId,
+      options
+    );
+    await this.queueTransaction(tx);
+    return tx;
+  }
+
+  /**
+   * Queues an UNARCHIVE transaction
+   */
+  async unarchive(
+    modelName: string,
+    modelId: string,
+    options: { original?: Record<string, unknown> } = {}
+  ): Promise<Transaction> {
+    const tx = createUnarchiveTransaction(
+      this.clientId,
+      modelName,
+      modelId,
+      options
+    );
+    await this.queueTransaction(tx);
+    return tx;
+  }
+
+  /**
+   * Queues a transaction for sending
+   */
+  private async queueTransaction(tx: Transaction): Promise<void> {
+    // Persist to storage first
+    await this.storage.addToOutbox(tx);
+    this.onTransactionStateChange?.(tx);
+
+    if (this.batchMutations) {
+      this.pendingBatch.push(tx);
+      this.scheduleBatchSend();
+    } else {
+      await this.sendBatch([tx]);
+    }
+  }
+
+  /**
+   * Schedules sending the pending batch
+   */
+  private scheduleBatchSend(): void {
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer);
+    }
+
+    // Send immediately if batch is full
+    if (this.pendingBatch.length >= this.maxBatchSize) {
+      this.flushBatch();
+      return;
+    }
+
+    this.batchTimer = setTimeout(() => {
+      this.flushBatch();
+    }, this.batchDelay);
+  }
+
+  /**
+   * Flushes the pending batch
+   */
+  private flushBatch(): void {
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer);
+      this.batchTimer = null;
+    }
+
+    if (this.pendingBatch.length === 0) {
+      return;
+    }
+
+    const batch = this.pendingBatch;
+    this.pendingBatch = [];
+
+    this.sendBatch(batch).catch(() => {
+      // Errors are handled in sendBatch
+    });
+  }
+
+  /**
+   * Sends a batch of transactions
+   */
+  private async sendBatch(transactions: Transaction[]): Promise<void> {
+    if (transactions.length === 0) {
+      return;
+    }
+
+    // Mark transactions as sent
+    for (const tx of transactions) {
+      tx.state = "sent";
+      await this.storage.updateOutboxTransaction(tx.clientTxId, {
+        state: "sent",
+      });
+      this.onTransactionStateChange?.(tx);
+    }
+
+    const batch = createTransactionBatch(transactions);
+
+    try {
+      const result = await this.transport.mutate(batch);
+      await this.handleMutateResult(transactions, result);
+    } catch (error) {
+      // Mark transactions as failed
+      for (const tx of transactions) {
+        tx.state = "failed";
+        tx.lastError = error instanceof Error ? error.message : "Unknown error";
+        tx.retryCount++;
+        await this.storage.updateOutboxTransaction(tx.clientTxId, {
+          state: "failed",
+          lastError: tx.lastError,
+          retryCount: tx.retryCount,
+        });
+        this.onTransactionStateChange?.(tx);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Handles the result of a mutation batch
+   */
+  private async handleMutateResult(
+    transactions: Transaction[],
+    result: MutateResult
+  ): Promise<void> {
+    const txMap = new Map(transactions.map((tx) => [tx.clientTxId, tx]));
+    const maxSyncId = Math.max(
+      result.lastSyncId ?? 0,
+      ...result.results
+        .map((txResult) => txResult.syncId)
+        .filter((value): value is number => typeof value === "number")
+    );
+
+    for (const txResult of result.results) {
+      const tx = txMap.get(txResult.clientTxId);
+      if (!tx) {
+        continue;
+      }
+
+      if (txResult.success) {
+        const syncIdNeededForCompletion =
+          txResult.syncId ??
+          (Number.isFinite(maxSyncId) ? maxSyncId : undefined);
+        tx.state = "awaitingSync";
+        tx.syncIdNeededForCompletion = syncIdNeededForCompletion;
+        await this.storage.updateOutboxTransaction(tx.clientTxId, {
+          state: "awaitingSync",
+          syncIdNeededForCompletion,
+        });
+      } else {
+        tx.state = "failed";
+        tx.lastError = txResult.error ?? "Unknown error";
+        tx.retryCount++;
+        await this.storage.updateOutboxTransaction(tx.clientTxId, {
+          state: "failed",
+          lastError: tx.lastError,
+          retryCount: tx.retryCount,
+        });
+        this.onTransactionRejected?.(tx);
+      }
+
+      this.onTransactionStateChange?.(tx);
+    }
+  }
+
+  /**
+   * Processes any pending transactions from storage (e.g., after reconnect)
+   */
+  async processPendingTransactions(): Promise<void> {
+    if (this.processing) {
+      await this.processingPromise;
+      return;
+    }
+
+    this.processing = true;
+    this.processingPromise = this.doProcessPending();
+
+    try {
+      await this.processingPromise;
+    } finally {
+      this.processing = false;
+      this.processingPromise = null;
+    }
+  }
+
+  private async doProcessPending(): Promise<void> {
+    const pending = await this.storage.getOutbox();
+
+    // Reset sent transactions back to queued (they may not have been confirmed)
+    for (const tx of pending) {
+      if (tx.state === "sent") {
+        tx.state = "queued";
+        await this.storage.updateOutboxTransaction(tx.clientTxId, {
+          state: "queued",
+        });
+      }
+    }
+
+    // Filter to only queued transactions
+    const queued = pending.filter(
+      (tx) => tx.state === "queued" && tx.retryCount < 5
+    );
+
+    if (queued.length === 0) {
+      return;
+    }
+
+    // Send in batches
+    for (let i = 0; i < queued.length; i += this.maxBatchSize) {
+      const batch = queued.slice(i, i + this.maxBatchSize);
+      await this.sendBatch(batch);
+    }
+  }
+
+  /**
+   * Gets the count of pending transactions
+   */
+  async getPendingCount(): Promise<number> {
+    const outbox = await this.storage.getOutbox();
+    return outbox.filter(
+      (tx) =>
+        tx.state === "queued" ||
+        tx.state === "sent" ||
+        tx.state === "awaitingSync"
+    ).length;
+  }
+
+  /**
+   * Completes any awaiting transactions up to the given sync ID
+   */
+  async completeUpToSyncId(lastSyncId: number): Promise<number> {
+    const outbox = await this.storage.getOutbox();
+    let completed = 0;
+
+    for (const tx of outbox) {
+      if (
+        tx.state === "awaitingSync" &&
+        typeof tx.syncIdNeededForCompletion === "number" &&
+        tx.syncIdNeededForCompletion <= lastSyncId
+      ) {
+        await this.storage.removeFromOutbox(tx.clientTxId);
+        tx.state = "completed";
+        completed++;
+      }
+    }
+
+    return completed;
+  }
+
+  /**
+   * Forces an immediate flush of pending batches
+   */
+  async flush(): Promise<void> {
+    this.flushBatch();
+    await this.processingPromise;
+  }
+
+  /**
+   * Clears all pending transactions
+   */
+  async clear(): Promise<void> {
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer);
+      this.batchTimer = null;
+    }
+    this.pendingBatch = [];
+
+    const outbox = await this.storage.getOutbox();
+    for (const tx of outbox) {
+      await this.storage.removeFromOutbox(tx.clientTxId);
+    }
+  }
+}