@syncular/client 0.0.6-219 → 0.0.6-223

package/src/engine/SyncEngine.ts

@@ -14,11 +14,11 @@ import {
   type SyncOperation,
   type SyncPullResponse,
   type SyncPullSubscriptionResponse,
-  type SyncSubscriptionRequest,
   SyncTransportError,
   startSyncSpan,
 } from '@syncular/core';
 import { type Kysely, sql, type Transaction } from 'kysely';
+import { type SyncClientFailureStage, SyncClientStageError } from '../errors';
 import { getClientHandler } from '../handlers/collection';
 import { ensureClientSyncSchema } from '../migrate';
 import { withDefaultClientPlugins } from '../plugins';
@@ -53,6 +53,7 @@ import type {
   SyncBootstrapStatus,
   SyncBootstrapStatusOptions,
   SyncBootstrapSubscriptionPhase,
+  SyncClientSubscription,
   SyncConnectionState,
   SyncDiagnostics,
   SyncEngineConfig,
@@ -132,7 +133,10 @@ function createSyncError(args: {
   cause?: Error;
   retryable?: boolean;
   httpStatus?: number;
+  stage?: SyncError['stage'];
   subscriptionId?: string;
+  chunkId?: string;
+  table?: string;
   stateId?: string;
 }): SyncError {
   return {
@@ -142,7 +146,10 @@ function createSyncError(args: {
     timestamp: Date.now(),
     retryable: args.retryable ?? false,
     httpStatus: args.httpStatus,
+    stage: args.stage,
     subscriptionId: args.subscriptionId,
+    chunkId: args.chunkId,
+    table: args.table,
     stateId: args.stateId,
   };
 }
@@ -153,56 +160,150 @@ function classifySyncFailure(error: unknown): {
   cause: Error;
   retryable: boolean;
   httpStatus?: number;
+  stage?: SyncError['stage'];
+  subscriptionId?: string;
+  chunkId?: string;
+  table?: string;
+  stateId?: string;
 } {
   const cause = error instanceof Error ? error : new Error(String(error));
   const message = cause.message || 'Sync failed';
   const normalized = message.toLowerCase();
 
-  if (cause instanceof SyncTransportError) {
-    if (cause.status === 401 || cause.status === 403) {
+  const classifyTransportFailure = (
+    transportError: SyncTransportError,
+    stage?: SyncClientFailureStage
+  ) => {
+    if (transportError.status === 401 || transportError.status === 403) {
       return {
-        code: 'AUTH_FAILED',
+        code: 'AUTH_FAILED' as const,
         message,
         cause,
         retryable: false,
-        httpStatus: cause.status,
+        httpStatus: transportError.status,
+        stage,
       };
     }
 
     if (
-      cause.status === 404 &&
+      transportError.status === 404 &&
       normalized.includes('snapshot') &&
       normalized.includes('chunk')
     ) {
       return {
-        code: 'SNAPSHOT_CHUNK_NOT_FOUND',
+        code: 'SNAPSHOT_CHUNK_NOT_FOUND' as const,
         message,
         cause,
         retryable: false,
-        httpStatus: cause.status,
+        httpStatus: transportError.status,
+        stage,
       };
     }
 
     if (
-      cause.status !== undefined &&
-      (cause.status >= 500 || cause.status === 408 || cause.status === 429)
+      transportError.status !== undefined &&
+      (transportError.status >= 500 ||
+        transportError.status === 408 ||
+        transportError.status === 429)
     ) {
       return {
-        code: 'NETWORK_ERROR',
+        code: 'NETWORK_ERROR' as const,
         message,
         cause,
         retryable: true,
-        httpStatus: cause.status,
+        httpStatus: transportError.status,
+        stage,
       };
     }
 
     return {
-      code: 'SYNC_ERROR',
+      code: 'SYNC_ERROR' as const,
       message,
       cause,
       retryable: false,
-      httpStatus: cause.status,
+      httpStatus: transportError.status,
+      stage,
     };
+  };
+
+  if (cause instanceof SyncClientStageError) {
+    const stageContext = {
+      stage: cause.stage,
+      subscriptionId: cause.subscriptionId,
+      chunkId: cause.chunkId,
+      table: cause.table,
+      stateId: cause.stateId,
+    };
+    const stageCause = cause.cause instanceof Error ? cause.cause : cause;
+
+    if (stageCause instanceof SyncTransportError) {
+      return {
+        ...classifyTransportFailure(stageCause, cause.stage),
+        ...stageContext,
+      };
+    }
+
+    if (
+      normalized.includes('network') ||
+      normalized.includes('fetch') ||
+      normalized.includes('timeout') ||
+      normalized.includes('offline')
+    ) {
+      return {
+        code: 'NETWORK_ERROR',
+        message,
+        cause,
+        retryable: true,
+        ...stageContext,
+      };
+    }
+
+    switch (cause.stage) {
+      case 'snapshot-gzip-decode':
+        return {
+          code: 'SNAPSHOT_GZIP_DECODE_FAILED',
+          message,
+          cause,
+          retryable: false,
+          ...stageContext,
+        };
+      case 'snapshot-chunk-decode':
+        return {
+          code: 'SNAPSHOT_CHUNK_DECODE_FAILED',
+          message,
+          cause,
+          retryable: false,
+          ...stageContext,
+        };
+      case 'snapshot-integrity':
+        return {
+          code: 'SNAPSHOT_INTEGRITY_FAILED',
+          message,
+          cause,
+          retryable: false,
+          ...stageContext,
+        };
+      case 'snapshot-apply':
+        return {
+          code: 'SNAPSHOT_APPLY_FAILED',
+          message,
+          cause,
+          retryable: false,
+          ...stageContext,
+        };
+      default:
+        return {
+          code: 'SYNC_ERROR',
+          message,
+          cause,
+          retryable: false,
+          ...stageContext,
+        };
+    }
+  }
+
+  if (cause instanceof SyncTransportError) {
+    return classifyTransportFailure(cause, 'pull');
   }
 
   if (
@@ -273,6 +374,11 @@ function defaultSelectorEquality<T>(left: T, right: T): boolean {
   return Object.is(left, right);
 }
 
+function normalizeBootstrapPhase(value: number | undefined): number {
+  if (value === undefined) return 0;
+  return Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+
 function areMetadataRecordsEqual(
   left: Record<string, unknown> | undefined,
   right: Record<string, unknown> | undefined
@@ -736,30 +842,100 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
         completedAt: progress?.completedAt,
         lastErrorCode: progress?.lastErrorCode,
         lastErrorMessage: progress?.lastErrorMessage,
+        bootstrapPhase: normalizeBootstrapPhase(configuredSub?.bootstrapPhase),
       };
     });
 
     const expectedSubscriptions = subscriptions.filter((sub) => sub.expected);
-    const readySubscriptionIds = expectedSubscriptions
+    const activePhase =
+      expectedSubscriptions
+        .filter((sub) => !sub.ready)
+        .reduce<number | null>(
+          (lowest, sub) =>
+            lowest === null || sub.bootstrapPhase < lowest
+              ? sub.bootstrapPhase
+              : lowest,
+          null
+        ) ?? null;
+    const selectedMaxPhase =
+      options.maxPhase ??
+      (explicitIdSet.size > 0
+        ? 'all'
+        : expectedSubscriptions.length > 0
+          ? expectedSubscriptions.reduce(
+              (lowest, sub) => Math.min(lowest, sub.bootstrapPhase),
+              Number.POSITIVE_INFINITY
+            )
+          : 0);
+    const blockingSubscriptions = expectedSubscriptions.filter((sub) =>
+      selectedMaxPhase === 'all' ? true : sub.bootstrapPhase <= selectedMaxPhase
+    );
+    const readySubscriptionIds = blockingSubscriptions
       .filter((sub) => sub.ready)
       .map((sub) => sub.id);
-    const pendingSubscriptionIds = expectedSubscriptions
+    const pendingSubscriptionIds = blockingSubscriptions
       .filter((sub) => !sub.ready)
       .map((sub) => sub.id);
     const channelPhase = this.resolveChannelPhase(
       filteredStates.map((sub) => this.mapSubscriptionToProgress(sub))
     );
     const progressPercent =
-      expectedSubscriptions.length === 0
+      blockingSubscriptions.length === 0
         ? pendingSubscriptionIds.length === 0
           ? 100
           : 0
         : Math.round(
-            expectedSubscriptions.reduce(
+            blockingSubscriptions.reduce(
               (sum, sub) => sum + sub.progressPercent,
               0
-            ) / expectedSubscriptions.length
+            ) / blockingSubscriptions.length
           );
+    const phases = Array.from(
+      expectedSubscriptions.reduce(
+        (acc, sub) => {
+          const current = acc.get(sub.bootstrapPhase) ?? {
+            phase: sub.bootstrapPhase,
+            expectedSubscriptionIds: [] as string[],
+            readySubscriptionIds: [] as string[],
+            pendingSubscriptionIds: [] as string[],
+            progressPercent: 0,
+          };
+          current.expectedSubscriptionIds.push(sub.id);
+          if (sub.ready) {
+            current.readySubscriptionIds.push(sub.id);
+          } else {
+            current.pendingSubscriptionIds.push(sub.id);
+          }
+          current.progressPercent += sub.progressPercent;
+          acc.set(sub.bootstrapPhase, current);
+          return acc;
+        },
+        new Map<
+          number,
+          {
+            phase: number;
+            expectedSubscriptionIds: string[];
+            readySubscriptionIds: string[];
+            pendingSubscriptionIds: string[];
+            progressPercent: number;
+          }
+        >()
+      )
+    )
+      .sort(([left], [right]) => left - right)
+      .map(([, phase]) => ({
+        phase: phase.phase,
+        expectedSubscriptionIds: phase.expectedSubscriptionIds,
+        readySubscriptionIds: phase.readySubscriptionIds,
+        pendingSubscriptionIds: phase.pendingSubscriptionIds,
+        isReady: phase.pendingSubscriptionIds.length === 0,
+        progressPercent:
+          phase.expectedSubscriptionIds.length === 0
+            ? 100
+            : Math.round(
+                phase.progressPercent / phase.expectedSubscriptionIds.length
+              ),
+      }));
 
     return {
       stateId,
@@ -767,10 +943,13 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       progressPercent,
       isBootstrapping: pendingSubscriptionIds.length > 0,
       isReady: pendingSubscriptionIds.length === 0,
-      expectedSubscriptionIds: expectedSubscriptions.map((sub) => sub.id),
+      expectedSubscriptionIds: blockingSubscriptions.map((sub) => sub.id),
       readySubscriptionIds,
       pendingSubscriptionIds,
       subscriptions,
+      activePhase,
+      selectedMaxPhase,
+      phases,
     };
   }
 
@@ -826,25 +1005,33 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     const deadline = Date.now() + timeoutMs;
 
     while (true) {
-      const states = await this.listSubscriptionStates({ stateId });
-      const relevantStates =
-        options.subscriptionId === undefined
-          ? states
-          : states.filter(
-              (state) => state.subscriptionId === options.subscriptionId
-            );
+      if (options.subscriptionId !== undefined) {
+        const state = await this.getSubscriptionState(options.subscriptionId, {
+          stateId,
+        });
+        const hasPendingBootstrap =
+          state?.status === 'active' && state.bootstrapState !== null;
 
-      const hasPendingBootstrap = relevantStates.some(
-        (state) => state.status === 'active' && state.bootstrapState !== null
-      );
+        if (!hasPendingBootstrap) {
+          return this.getProgress();
+        }
+      } else {
+        const bootstrap = await this.getBootstrapStatus({
+          stateId,
+          maxPhase: options.maxPhase,
+        });
 
-      if (!hasPendingBootstrap) {
-        return this.getProgress();
+        if (bootstrap.isReady) {
+          return this.getProgress();
+        }
       }
 
       if (this.state.error) {
+        const detailSuffix = this.state.error.stage
+          ? ` [stage=${this.state.error.stage}]`
+          : '';
         throw new Error(
-          `[SyncEngine.awaitBootstrapComplete] Failed while waiting for bootstrap completion: ${this.state.error.message}`
+          `[SyncEngine.awaitBootstrapComplete] Failed while waiting for bootstrap completion${detailSuffix}: ${this.state.error.message}`
         );
       }
 
@@ -854,9 +1041,25 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
           options.subscriptionId === undefined
             ? `state "${stateId}"`
             : `subscription "${options.subscriptionId}" in state "${stateId}"`;
+        const bootstrap = await this.getBootstrapStatus({
+          stateId,
+          subscriptionIds:
+            options.subscriptionId === undefined
+              ? undefined
+              : [options.subscriptionId],
+          maxPhase: options.maxPhase,
+        }).catch(() => null);
+        const pendingSummary =
+          bootstrap && bootstrap.pendingSubscriptionIds.length > 0
+            ? ` Pending subscriptions: ${bootstrap.pendingSubscriptionIds.join(', ')}.`
+            : '';
+        const phaseSummary =
+          bootstrap && bootstrap.activePhase !== null
+            ? ` Active phase: ${bootstrap.activePhase}.`
+            : '';
 
         throw new Error(
-          `[SyncEngine.awaitBootstrapComplete] Timed out after ${timeoutMs}ms waiting for ${target}`
+          `[SyncEngine.awaitBootstrapComplete] Timed out after ${timeoutMs}ms waiting for ${target}. Bootstrap is still in progress.${phaseSummary}${pendingSummary}`
         );
       }
 
@@ -1668,6 +1871,18 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     }
   }
 
+  private shouldTrace(): boolean {
+    return (
+      this.config.traceEnabled === true ||
+      (this.listeners.get('sync:trace')?.size ?? 0) > 0
+    );
+  }
+
+  private emitTrace(payload: SyncEventPayloads['sync:trace']): void {
+    if (!this.shouldTrace()) return;
+    this.emit('sync:trace', payload);
+  }
+
   private updateState(partial: Partial<SyncEngineState>): void {
     const nextState = { ...this.state, ...partial };
     const unchanged =
@@ -1953,14 +2168,14 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
               clientId: this.config.clientId!,
               actorId: this.config.actorId ?? undefined,
               plugins: this.config.plugins,
-              subscriptions: this.config
-                .subscriptions as SyncSubscriptionRequest[],
+              subscriptions: this.config.subscriptions,
               limitCommits: this.config.limitCommits,
               limitSnapshotRows: this.config.limitSnapshotRows,
               maxSnapshotPages: this.config.maxSnapshotPages,
               dedupeRows: this.config.dedupeRows,
               stateId: this.config.stateId,
               sha256: this.config.sha256,
+              onTrace: (event) => this.emitTrace(event),
               trigger,
               allowSkipPullOnLocalWsPush:
                 this.state.transportMode === 'realtime',
@@ -2071,7 +2286,11 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
         cause: classified.cause,
         retryable: classified.retryable,
         httpStatus: classified.httpStatus,
-        stateId: this.getStateId(),
+        stage: classified.stage,
+        subscriptionId: classified.subscriptionId,
+        chunkId: classified.chunkId,
+        table: classified.table,
+        stateId: classified.stateId ?? this.getStateId(),
       });
 
       this.updateState({
@@ -2987,9 +3206,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   /**
    * Update subscriptions dynamically
    */
-  updateSubscriptions(
-    subscriptions: Array<Omit<SyncSubscriptionRequest, 'cursor'>>
-  ): void {
+  updateSubscriptions(subscriptions: SyncClientSubscription[]): void {
     this.config.subscriptions = subscriptions;
     // Trigger a sync to apply new subscriptions
     this.triggerSyncInBackground(undefined, 'subscription update');

package/src/engine/types.ts

@@ -13,6 +13,7 @@ import type {
   SyncTransport,
 } from '@syncular/core';
 import type { Kysely } from 'kysely';
+import type { SyncClientFailureStage } from '../errors';
 import type { ClientHandlerCollection } from '../handlers/collection';
 import type { SyncClientPlugin } from '../plugins/types';
 import type { SyncClientDb } from '../schema';
@@ -107,6 +108,20 @@ export type SyncBootstrapSubscriptionPhase =
   | SubscriptionProgressPhase
   | 'pending';
 
+export interface SyncClientSubscription
+  extends Omit<SyncSubscriptionRequest, 'cursor'> {
+  /**
+   * Local-only bootstrap phase for staged startup.
+   *
+   * Lower phases bootstrap first. Higher phases are deferred until all lower
+   * phases are ready, but once a higher-phase subscription is already ready it
+   * continues to participate in normal pull requests.
+   *
+   * Defaults to `0`.
+   */
+  bootstrapPhase?: number;
+}
+
 export interface SyncBootstrapSubscriptionStatus {
   stateId: string;
   id: string;
@@ -122,6 +137,16 @@ export interface SyncBootstrapSubscriptionStatus {
   completedAt?: number;
   lastErrorCode?: string;
   lastErrorMessage?: string;
+  bootstrapPhase: number;
+}
+
+export interface SyncBootstrapPhaseStatus {
+  phase: number;
+  expectedSubscriptionIds: string[];
+  readySubscriptionIds: string[];
+  pendingSubscriptionIds: string[];
+  isReady: boolean;
+  progressPercent: number;
 }
 
 export interface SyncBootstrapStatus {
@@ -134,11 +159,51 @@ export interface SyncBootstrapStatus {
   readySubscriptionIds: string[];
   pendingSubscriptionIds: string[];
   subscriptions: SyncBootstrapSubscriptionStatus[];
+  activePhase: number | null;
+  selectedMaxPhase: number | 'all';
+  phases: SyncBootstrapPhaseStatus[];
 }
 
 export interface SyncBootstrapStatusOptions {
   stateId?: string;
   subscriptionIds?: string[];
+  maxPhase?: number | 'all';
+}
+
+export type SyncTraceStage =
+  | 'pull:start'
+  | 'pull:response'
+  | 'pull:error'
+  | 'apply:transaction:start'
+  | 'apply:transaction:complete'
+  | 'apply:transaction:error'
+  | 'apply:subscription:start'
+  | 'apply:subscription:complete'
+  | 'apply:subscription:error'
+  | 'apply:chunk-materialize:start'
+  | 'apply:chunk-materialize:complete'
+  | 'apply:chunk-materialize:error';
+
+export interface SyncTraceEvent {
+  stage: SyncTraceStage;
+  timestamp: number;
+  stateId?: string;
+  subscriptionId?: string;
+  table?: string;
+  bootstrap?: boolean;
+  activeBootstrapPhase?: number | null;
+  transactionMode?: 'single-transaction' | 'per-subscription';
+  subscriptionIds?: string[];
+  subscriptionCount?: number;
+  commitCount?: number;
+  snapshotCount?: number;
+  chunkCount?: number;
+  chunkId?: string;
+  chunkIndex?: number;
+  rowCount?: number;
+  nextCursor?: number | null;
+  durationMs?: number;
+  errorMessage?: string;
 }
 
 /**
@@ -150,6 +215,10 @@ export interface SyncError {
     | 'NETWORK_ERROR'
     | 'AUTH_FAILED'
     | 'SNAPSHOT_CHUNK_NOT_FOUND'
+    | 'SNAPSHOT_GZIP_DECODE_FAILED'
+    | 'SNAPSHOT_CHUNK_DECODE_FAILED'
+    | 'SNAPSHOT_INTEGRITY_FAILED'
+    | 'SNAPSHOT_APPLY_FAILED'
     | 'MIGRATION_FAILED'
     | 'CONFLICT'
     | 'SYNC_ERROR'
@@ -164,8 +233,14 @@ export interface SyncError {
   retryable: boolean;
   /** HTTP status code when available */
   httpStatus?: number;
+  /** Sync stage where the error originated */
+  stage?: SyncClientFailureStage;
   /** Related subscription id when available */
   subscriptionId?: string;
+  /** Related snapshot chunk id when available */
+  chunkId?: string;
+  /** Related table when available */
+  table?: string;
   /** Related state id when available */
   stateId?: string;
 }
@@ -177,6 +252,7 @@ export type SyncEventType =
   | 'state:change'
   | 'sync:start'
   | 'sync:complete'
+  | 'sync:trace'
   | 'sync:live'
   | 'sync:error'
   | 'push:result'
@@ -223,6 +299,7 @@ export interface SyncEventPayloads {
     pullRounds: number;
     pullResponse: SyncPullResponse;
   };
+  'sync:trace': SyncTraceEvent;
   'sync:live': { timestamp: number };
   'sync:error': SyncError;
   'push:result': PushResultInfo;
@@ -287,7 +364,7 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   /** Stable device/app installation id */
   clientId: string | null | undefined;
   /** Subscriptions for partial sync */
-  subscriptions: Array<Omit<SyncSubscriptionRequest, 'cursor'>>;
+  subscriptions: SyncClientSubscription[];
   /** Pull limit (commit count per request) */
   limitCommits?: number;
   /** Bootstrap snapshot rows per page */
@@ -344,6 +421,8 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   plugins?: SyncClientPlugin[];
   /** Custom SHA-256 hash function (for platforms without crypto.subtle, e.g. React Native) */
   sha256?: (bytes: Uint8Array) => Promise<string>;
+  /** Emit structured pull/apply tracing events to the event stream and inspector buffer. */
+  traceEnabled?: boolean;
 }
 
 /**
@@ -469,6 +548,7 @@ export interface SyncAwaitBootstrapOptions {
   timeoutMs?: number;
   stateId?: string;
   subscriptionId?: string;
+  maxPhase?: number | 'all';
 }
 
 export interface SyncDiagnostics {

package/src/errors.ts

@@ -0,0 +1,59 @@
+export type SyncClientFailureStage =
+  | 'pull'
+  | 'snapshot-chunk-fetch'
+  | 'snapshot-gzip-decode'
+  | 'snapshot-chunk-decode'
+  | 'snapshot-integrity'
+  | 'snapshot-apply'
+  | 'bootstrap-timeout';
+
+export interface SyncClientFailureContext {
+  stage: SyncClientFailureStage;
+  stateId?: string;
+  subscriptionId?: string;
+  table?: string;
+  chunkId?: string;
+}
+
+function normalizeError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+export class SyncClientStageError extends Error {
+  readonly stage: SyncClientFailureStage;
+  readonly stateId?: string;
+  readonly subscriptionId?: string;
+  readonly table?: string;
+  readonly chunkId?: string;
+
+  constructor(
+    message: string,
+    context: SyncClientFailureContext,
+    cause?: unknown
+  ) {
+    const normalizedCause =
+      cause === undefined ? undefined : normalizeError(cause);
+    super(message);
+    this.name = 'SyncClientStageError';
+    this.stage = context.stage;
+    this.stateId = context.stateId;
+    this.subscriptionId = context.subscriptionId;
+    this.table = context.table;
+    this.chunkId = context.chunkId;
+    if (normalizedCause) {
+      this.cause = normalizedCause;
+    }
+  }
+}
+
+export function wrapSyncClientStageError(
+  error: unknown,
+  context: SyncClientFailureContext,
+  message?: string
+): SyncClientStageError {
+  if (error instanceof SyncClientStageError) {
+    return error;
+  }
+  const cause = normalizeError(error);
+  return new SyncClientStageError(message ?? cause.message, context, cause);
+}

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './conflicts';
 export * from './create-client';
 export * from './engine';
 export type * from './engine/types';
+export * from './errors';
 export * from './handlers/collection';
 export * from './handlers/create-handler';
 export * from './handlers/types';