@syncular/client 0.0.1 → 0.0.2-126

package/src/engine/SyncEngine.ts

@@ -5,10 +5,15 @@
  * and provides a clean API for framework bindings to consume.
  */
 
-import type {
-  SyncChange,
-  SyncPullResponse,
-  SyncSubscriptionRequest,
+import {
+  captureSyncException,
+  countSyncMetric,
+  distributionSyncMetric,
+  isRecord,
+  type SyncChange,
+  type SyncPullResponse,
+  type SyncSubscriptionRequest,
+  startSyncSpan,
 } from '@syncular/core';
 import { type Kysely, sql } from 'kysely';
 import { syncPushOnce } from '../push-engine';
@@ -39,6 +44,7 @@ const DEFAULT_MAX_RETRIES = 5;
 const INITIAL_RETRY_DELAY_MS = 1000;
 const MAX_RETRY_DELAY_MS = 60000;
 const EXPONENTIAL_FACTOR = 2;
+const REALTIME_RECONNECT_CATCHUP_DELAY_MS = 500;
 
 function calculateRetryDelay(attemptIndex: number): number {
   return Math.min(
@@ -70,8 +76,10 @@ function createSyncError(
   };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+function resolveSyncTriggerLabel(
+  trigger?: 'ws' | 'local' | 'poll'
+): 'ws' | 'local' | 'poll' | 'auto' {
+  return trigger ?? 'auto';
 }
 
 /**
@@ -99,6 +107,8 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   private syncPromise: Promise<SyncResult> | null = null;
   private syncRequestedWhileRunning = false;
   private retryTimeoutId: ReturnType<typeof setTimeout> | null = null;
+  private realtimeCatchupTimeoutId: ReturnType<typeof setTimeout> | null = null;
+  private hasRealtimeConnectedOnce = false;
 
   /**
    * In-memory map tracking local mutation timestamps by rowId.
@@ -282,7 +292,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
   private detectTransportMode(): SyncTransportMode {
     if (
-      this.config.realtimeEnabled &&
+      this.config.realtimeEnabled !== false &&
       isRealtimeTransport(this.config.transport)
     ) {
       return 'realtime';
@@ -473,12 +483,18 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       clearTimeout(this.retryTimeoutId);
       this.retryTimeoutId = null;
     }
+    if (this.realtimeCatchupTimeoutId) {
+      clearTimeout(this.realtimeCatchupTimeoutId);
+      this.realtimeCatchupTimeoutId = null;
+    }
   }
 
   /**
    * Trigger a manual sync
    */
-  async sync(): Promise<SyncResult> {
+  async sync(opts?: {
+    trigger?: 'ws' | 'local' | 'poll';
+  }): Promise<SyncResult> {
     // Dedupe concurrent sync calls
     if (this.syncPromise) {
       // A sync is already in-flight; queue one more run so we don't miss
@@ -501,7 +517,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       };
     }
 
-    this.syncPromise = this.performSyncLoop();
+    this.syncPromise = this.performSyncLoop(opts?.trigger);
     try {
       return await this.syncPromise;
     } finally {
@@ -509,7 +525,9 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     }
   }
 
-  private async performSyncLoop(): Promise<SyncResult> {
+  private async performSyncLoop(
+    trigger?: 'ws' | 'local' | 'poll'
+  ): Promise<SyncResult> {
     let lastResult: SyncResult = {
       success: false,
       pushedCommits: 0,
@@ -520,7 +538,9 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
     do {
       this.syncRequestedWhileRunning = false;
-      lastResult = await this.performSyncOnce();
+      lastResult = await this.performSyncOnce(trigger);
+      // After the first iteration, clear trigger context
+      trigger = undefined;
       // If the sync failed, let retry logic handle backoff instead of tight looping.
       if (!lastResult.success) break;
     } while (
@@ -532,27 +552,45 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     return lastResult;
   }
 
-  private async performSyncOnce(): Promise<SyncResult> {
+  private async performSyncOnce(
+    trigger?: 'ws' | 'local' | 'poll'
+  ): Promise<SyncResult> {
     const timestamp = Date.now();
+    const startedAtMs = timestamp;
+    const triggerLabel = resolveSyncTriggerLabel(trigger);
     this.updateState({ isSyncing: true });
     this.emit('sync:start', { timestamp });
+    countSyncMetric('sync.client.sync.attempts', 1, {
+      attributes: { trigger: triggerLabel },
+    });
 
     try {
       const pullApplyTimestamp = Date.now();
-      const result = await syncOnce(
-        this.config.db,
-        this.config.transport,
-        this.config.shapes,
+      const result = await startSyncSpan(
         {
-          clientId: this.config.clientId!,
-          actorId: this.config.actorId ?? undefined,
-          plugins: this.config.plugins,
-          subscriptions: this.config.subscriptions as SyncSubscriptionRequest[],
-          limitCommits: this.config.limitCommits,
-          limitSnapshotRows: this.config.limitSnapshotRows,
-          maxSnapshotPages: this.config.maxSnapshotPages,
-          stateId: this.config.stateId,
-        }
+          name: 'sync.client.sync',
+          op: 'sync.client.sync',
+          attributes: { trigger: triggerLabel },
+        },
+        () =>
+          syncOnce(
+            this.config.db,
+            this.config.transport,
+            this.config.handlers,
+            {
+              clientId: this.config.clientId!,
+              actorId: this.config.actorId ?? undefined,
+              plugins: this.config.plugins,
+              subscriptions: this.config
+                .subscriptions as SyncSubscriptionRequest[],
+              limitCommits: this.config.limitCommits,
+              limitSnapshotRows: this.config.limitSnapshotRows,
+              maxSnapshotPages: this.config.maxSnapshotPages,
+              stateId: this.config.stateId,
+              sha256: this.config.sha256,
+              trigger,
+            }
+          )
       );
 
       const syncResult: SyncResult = {
@@ -594,8 +632,42 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
         this.config.onDataChange?.(changedTables);
       }
 
-      // Refresh outbox stats
-      await this.refreshOutboxStats();
+      // Refresh outbox stats (fire-and-forget — don't block sync:complete)
+      this.refreshOutboxStats().catch((error) => {
+        console.warn(
+          '[SyncEngine] Failed to refresh outbox stats after sync:',
+          error
+        );
+      });
+
+      const durationMs = Math.max(0, Date.now() - startedAtMs);
+      countSyncMetric('sync.client.sync.results', 1, {
+        attributes: {
+          trigger: triggerLabel,
+          status: 'success',
+        },
+      });
+      distributionSyncMetric('sync.client.sync.duration_ms', durationMs, {
+        unit: 'millisecond',
+        attributes: {
+          trigger: triggerLabel,
+          status: 'success',
+        },
+      });
+      distributionSyncMetric(
+        'sync.client.sync.pushed_commits',
+        result.pushedCommits,
+        {
+          attributes: { trigger: triggerLabel },
+        }
+      );
+      distributionSyncMetric(
+        'sync.client.sync.pull_rounds',
+        result.pullRounds,
+        {
+          attributes: { trigger: triggerLabel },
+        }
+      );
 
       return syncResult;
     } catch (err) {
@@ -614,6 +686,25 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
       this.handleError(error);
 
+      const durationMs = Math.max(0, Date.now() - startedAtMs);
+      countSyncMetric('sync.client.sync.results', 1, {
+        attributes: {
+          trigger: triggerLabel,
+          status: 'error',
+        },
+      });
+      distributionSyncMetric('sync.client.sync.duration_ms', durationMs, {
+        unit: 'millisecond',
+        attributes: {
+          trigger: triggerLabel,
+          status: 'error',
+        },
+      });
+      captureSyncException(err, {
+        event: 'sync.client.sync',
+        trigger: triggerLabel,
+      });
+
       // Schedule retry if under max retries
       const maxRetries = this.config.maxRetries ?? DEFAULT_MAX_RETRIES;
       if (this.state.retryCount < maxRetries) {
@@ -652,6 +743,165 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     return Array.from(tables);
   }
 
+  /**
+   * Apply changes delivered inline over WebSocket for instant UI updates.
+   * Returns true if changes were applied and cursor updated successfully,
+   * false if anything failed (caller should fall back to HTTP sync).
+   */
+  private async applyWsDeliveredChanges(
+    changes: SyncChange[],
+    cursor: number
+  ): Promise<boolean> {
+    try {
+      await this.config.db.transaction().execute(async (trx) => {
+        for (const change of changes) {
+          const handler = this.config.handlers.get(change.table);
+          if (!handler) {
+            throw new Error(
+              `Missing client table handler for WS change table "${change.table}"`
+            );
+          }
+          await handler.applyChange({ trx }, change);
+        }
+
+        // Update subscription cursors
+        const stateId = this.config.stateId ?? 'default';
+        await sql`
+          update ${sql.table('sync_subscription_state')}
+          set ${sql.ref('cursor')} = ${sql.val(cursor)}
+          where ${sql.ref('state_id')} = ${sql.val(stateId)}
+            and ${sql.ref('cursor')} < ${sql.val(cursor)}
+        `.execute(trx);
+      });
+
+      // Update mutation timestamps BEFORE emitting data:change so that
+      // React hooks re-querying the DB see fresh fingerprints immediately.
+      const now = Date.now();
+      for (const change of changes) {
+        if (!change.table || !change.row_id) continue;
+        if (change.op === 'delete') {
+          this.mutationTimestamps.delete(`${change.table}:${change.row_id}`);
+        } else {
+          this.bumpMutationTimestamp(change.table, change.row_id, now);
+        }
+      }
+
+      // Emit data change for immediate UI update
+      const changedTables = [...new Set(changes.map((c) => c.table))];
+      if (changedTables.length > 0) {
+        this.emit('data:change', {
+          scopes: changedTables,
+          timestamp: Date.now(),
+        });
+        this.config.onDataChange?.(changedTables);
+      }
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Handle WS-delivered changes: apply them and decide whether to skip HTTP pull.
+   * Falls back to full HTTP sync when conditions require it.
+   */
+  private async handleWsDelivery(
+    changes: SyncChange[],
+    cursor: number
+  ): Promise<void> {
+    // If a sync is already in-flight, let it handle everything
+    if (this.syncPromise) {
+      countSyncMetric('sync.client.ws.delivery.events', 1, {
+        attributes: { path: 'inflight_sync' },
+      });
+      this.triggerSyncInBackground(
+        { trigger: 'ws' },
+        'ws delivery with in-flight sync'
+      );
+      return;
+    }
+
+    // If there are pending outbox commits, need to push via HTTP
+    if (this.state.pendingCount > 0) {
+      countSyncMetric('sync.client.ws.delivery.events', 1, {
+        attributes: { path: 'pending_outbox' },
+      });
+      this.triggerSyncInBackground(
+        { trigger: 'ws' },
+        'ws delivery with pending outbox'
+      );
+      return;
+    }
+
+    // If afterPull plugins exist, inline WS changes may require transforms
+    // (e.g. decryption). Fall back to HTTP sync and do not apply inline payload.
+    const hasAfterPullPlugins = this.config.plugins?.some(
+      (p) => typeof p.afterPull === 'function'
+    );
+    if (hasAfterPullPlugins) {
+      countSyncMetric('sync.client.ws.delivery.events', 1, {
+        attributes: { path: 'after_pull_plugins' },
+      });
+      this.triggerSyncInBackground(
+        { trigger: 'ws' },
+        'ws delivery with afterPull plugins'
+      );
+      return;
+    }
+
+    // Apply changes + update cursor
+    const inlineApplyStartedAtMs = Date.now();
+    const applied = await this.applyWsDeliveredChanges(changes, cursor);
+    const inlineApplyDurationMs = Math.max(
+      0,
+      Date.now() - inlineApplyStartedAtMs
+    );
+    distributionSyncMetric(
+      'sync.client.ws.inline_apply.duration_ms',
+      inlineApplyDurationMs,
+      {
+        unit: 'millisecond',
+      }
+    );
+
+    if (!applied) {
+      countSyncMetric('sync.client.ws.delivery.events', 1, {
+        attributes: { path: 'inline_fallback' },
+      });
+      this.triggerSyncInBackground(
+        { trigger: 'ws' },
+        'ws inline apply fallback'
+      );
+      return;
+    }
+
+    // All clear — skip HTTP pull entirely
+    countSyncMetric('sync.client.ws.delivery.events', 1, {
+      attributes: { path: 'inline_applied' },
+    });
+    this.updateState({
+      lastSyncAt: Date.now(),
+      error: null,
+      retryCount: 0,
+      isRetrying: false,
+    });
+
+    this.emit('sync:complete', {
+      timestamp: Date.now(),
+      pushedCommits: 0,
+      pullRounds: 0,
+      pullResponse: { ok: true, subscriptions: [] },
+    });
+
+    this.refreshOutboxStats().catch((error) => {
+      console.warn(
+        '[SyncEngine] Failed to refresh outbox stats after WS apply:',
+        error
+      );
+    });
+  }
+
   private timestampCounter = 0;
 
   private nextPreciseTimestamp(now: number): number {
@@ -758,7 +1008,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     this.retryTimeoutId = setTimeout(() => {
       this.retryTimeoutId = null;
       if (!this.isDestroyed) {
-        this.sync();
+        this.triggerSyncInBackground(undefined, 'retry timer');
       }
     }, delay);
   }
@@ -768,13 +1018,25 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     this.config.onError?.(error);
   }
 
+  private triggerSyncInBackground(
+    opts?: { trigger?: 'ws' | 'local' | 'poll' },
+    reason = 'background'
+  ): void {
+    void this.sync(opts).catch((error) => {
+      console.error(
+        `[SyncEngine] Unexpected sync failure during ${reason}:`,
+        error
+      );
+    });
+  }
+
   private setupPolling(): void {
     this.stopPolling();
 
     const interval = this.config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     this.pollerId = setInterval(() => {
       if (!this.state.isSyncing && !this.isDestroyed) {
-        this.sync();
+        this.triggerSyncInBackground(undefined, 'polling interval');
       }
     }, interval);
 
@@ -827,16 +1089,38 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       { clientId: this.config.clientId! },
       (event) => {
         if (event.event === 'sync') {
-          this.sync();
+          countSyncMetric('sync.client.ws.events', 1, {
+            attributes: { type: 'sync' },
+          });
+          const hasInlineChanges =
+            Array.isArray(event.data.changes) && event.data.changes.length > 0;
+          const cursor = event.data.cursor;
+
+          if (hasInlineChanges && typeof cursor === 'number') {
+            // WS delivered changes + cursor — may skip HTTP pull
+            this.handleWsDelivery(event.data.changes as SyncChange[], cursor);
+          } else {
+            // Cursor-only wake-up or no cursor — must HTTP sync
+            countSyncMetric('sync.client.ws.delivery.events', 1, {
+              attributes: { path: 'cursor_wakeup' },
+            });
+            this.triggerSyncInBackground({ trigger: 'ws' }, 'ws cursor wakeup');
+          }
         }
       },
       (state) => {
         switch (state) {
-          case 'connected':
+          case 'connected': {
+            const wasConnectedBefore = this.hasRealtimeConnectedOnce;
+            this.hasRealtimeConnectedOnce = true;
             this.setConnectionState('connected');
             this.stopFallbackPolling();
-            this.sync();
+            this.triggerSyncInBackground(undefined, 'realtime connected state');
+            if (wasConnectedBefore) {
+              this.scheduleRealtimeReconnectCatchupSync();
+            }
             break;
+          }
           case 'connecting':
             this.setConnectionState('connecting');
             break;
@@ -850,6 +1134,10 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   }
 
   private stopRealtime(): void {
+    if (this.realtimeCatchupTimeoutId) {
+      clearTimeout(this.realtimeCatchupTimeoutId);
+      this.realtimeCatchupTimeoutId = null;
+    }
     if (this.realtimePresenceUnsub) {
       this.realtimePresenceUnsub();
       this.realtimePresenceUnsub = null;
@@ -861,13 +1149,28 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     this.stopFallbackPolling();
   }
 
+  private scheduleRealtimeReconnectCatchupSync(): void {
+    if (this.realtimeCatchupTimeoutId) {
+      clearTimeout(this.realtimeCatchupTimeoutId);
+    }
+
+    this.realtimeCatchupTimeoutId = setTimeout(() => {
+      this.realtimeCatchupTimeoutId = null;
+
+      if (this.isDestroyed || !this.isEnabled()) return;
+      if (this.state.connectionState !== 'connected') return;
+
+      this.triggerSyncInBackground(undefined, 'realtime reconnect catchup');
+    }, REALTIME_RECONNECT_CATCHUP_DELAY_MS);
+  }
+
   private startFallbackPolling(): void {
     if (this.fallbackPollerId) return;
 
     const interval = this.config.realtimeFallbackPollMs ?? 30_000;
     this.fallbackPollerId = setInterval(() => {
       if (!this.state.isSyncing && !this.isDestroyed) {
-        this.sync();
+        this.triggerSyncInBackground(undefined, 'realtime fallback poll');
       }
     }, interval);
   }
@@ -879,6 +1182,25 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     }
   }
 
+  /**
+   * Clear all in-memory mutation state and emit data:change so UI re-renders.
+   * Call this after deleting local data (e.g. reset flow) so that React hooks
+   * recompute fingerprints from scratch instead of seeing stale timestamps.
+   */
+  resetLocalState(): void {
+    const tables = [...this.tableMutationTimestamps.keys()];
+    this.mutationTimestamps.clear();
+    this.tableMutationTimestamps.clear();
+
+    if (tables.length > 0) {
+      this.emit('data:change', {
+        scopes: tables,
+        timestamp: Date.now(),
+      });
+      this.config.onDataChange?.(tables);
+    }
+  }
+
   /**
    * Reconnect
    */
@@ -901,10 +1223,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     // Polling mode: restart the poller and trigger a sync immediately.
     if (this.state.transportMode === 'polling') {
       this.setupPolling();
-      // Trigger sync in background - errors are handled internally by sync()
-      this.sync().catch((err) => {
-        console.error('Unexpected error during reconnect sync:', err);
-      });
+      this.triggerSyncInBackground(undefined, 'reconnect');
     }
   }
 
@@ -1061,7 +1380,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   ): void {
     this.config.subscriptions = subscriptions;
     // Trigger a sync to apply new subscriptions
-    this.sync();
+    this.triggerSyncInBackground(undefined, 'subscription update');
   }
 
   /**
@@ -1077,13 +1396,13 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     }>
   ): Promise<void> {
     const db = this.config.db;
-    const shapes = this.config.shapes;
+    const handlers = this.config.handlers;
     const affectedTables = new Set<string>();
     const now = Date.now();
 
     await db.transaction().execute(async (trx) => {
       for (const input of inputs) {
-        const handler = shapes.get(input.table);
+        const handler = handlers.get(input.table);
         if (!handler) continue;
 
         affectedTables.add(input.table);

package/src/engine/types.ts

@@ -6,6 +6,8 @@
 
 import type {
   SyncPullResponse,
+  SyncPushRequest,
+  SyncPushResponse,
   SyncSubscriptionRequest,
   SyncTransport,
 } from '@syncular/core';
@@ -137,8 +139,8 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   db: Kysely<DB>;
   /** Sync transport */
   transport: SyncTransport;
-  /** Client shape registry */
-  shapes: ClientTableRegistry<DB>;
+  /** Client table handler registry */
+  handlers: ClientTableRegistry<DB>;
   /** Actor id for sync scoping (null/undefined disables sync) */
   actorId: string | null | undefined;
   /** Stable device/app installation id */
@@ -161,7 +163,11 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   migrate?: (db: Kysely<DB>) => Promise<void>;
   /** Called when migration fails. Receives the error. */
   onMigrationError?: (error: Error) => void;
-  /** Enable realtime mode (WebSocket wake-ups) if transport supports it */
+  /**
+   * Enable realtime mode (WebSocket wake-ups).
+   * Default behavior is auto-enable when transport supports realtime.
+   * Set to false to force polling.
+   */
   realtimeEnabled?: boolean;
   /** Fallback poll interval when realtime reconnecting */
   realtimeFallbackPollMs?: number;
@@ -173,6 +179,8 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   onDataChange?: (scopes: string[]) => void;
   /** Optional client plugins (e.g. encryption) */
   plugins?: SyncClientPlugin[];
+  /** Custom SHA-256 hash function (for platforms without crypto.subtle, e.g. React Native) */
+  sha256?: (bytes: Uint8Array) => Promise<string>;
 }
 
 /**
@@ -205,7 +213,12 @@ export interface RealtimeTransportLike extends SyncTransport {
     args: { clientId: string },
     onEvent: (event: {
       event: string;
-      data: { cursor?: number; error?: string; timestamp: number };
+      data: {
+        cursor?: number;
+        changes?: unknown[];
+        error?: string;
+        timestamp: number;
+      };
     }) => void,
     onStateChange?: (state: 'disconnected' | 'connecting' | 'connected') => void
   ): () => void;
@@ -227,6 +240,11 @@ export interface RealtimeTransportLike extends SyncTransport {
       entries?: PresenceEntry[];
     }) => void
   ): () => void;
+  /**
+   * Push a commit via WebSocket (bypasses HTTP).
+   * Returns `null` if WS is not connected or times out (caller should fall back to HTTP).
+   */
+  pushViaWs?(request: SyncPushRequest): Promise<SyncPushResponse | null>;
 }
 
 /**