@syncular/client 0.0.6-219 → 0.0.6-223

package/src/client.ts

@@ -26,6 +26,9 @@ import type {
   SubscriptionProgress,
   SyncAwaitBootstrapOptions,
   SyncAwaitPhaseOptions,
+  SyncBootstrapStatus,
+  SyncBootstrapStatusOptions,
+  SyncClientSubscription,
   SyncDiagnostics,
   SyncEngineState,
   SyncInspectorOptions,
@@ -35,6 +38,7 @@ import type {
   SyncResetOptions,
   SyncResetResult,
   SyncResult,
+  SyncTraceEvent,
   TransportHealth,
 } from './engine/types';
 import type { ClientHandlerCollection } from './handlers/collection';
@@ -74,16 +78,14 @@ export interface ClientOptions<DB extends SyncClientDb> {
   actorId: string;
 
   /** Subscriptions to sync */
-  subscriptions: Array<{
-    id: string;
-    table: string;
-    scopes?: Record<string, string | string[]>;
-    params?: Record<string, unknown>;
-  }>;
+  subscriptions: SyncClientSubscription[];
 
   /** Optional: Sync plugins */
   plugins?: SyncClientPlugin[];
 
+  /** Optional: Emit structured pull/apply tracing to client events and inspector snapshots. */
+  traceEnabled?: boolean;
+
   /** Optional: Enable realtime transport mode */
   realtimeEnabled?: boolean;
 
@@ -145,7 +147,17 @@ export interface ClientState {
   /** Last successful sync timestamp */
   lastSyncAt: number | null;
   /** Current error if any */
-  error: { code: string; message: string } | null;
+  error: {
+    code: string;
+    message: string;
+    stage?: string;
+    retryable?: boolean;
+    httpStatus?: number;
+    subscriptionId?: string;
+    chunkId?: string;
+    table?: string;
+    stateId?: string;
+  } | null;
   /** Outbox statistics */
   outbox: OutboxStats;
 }
@@ -175,6 +187,7 @@ export interface MigrationInfo {
 type ClientEventType =
   | 'sync:start'
   | 'sync:complete'
+  | 'sync:trace'
   | 'sync:live'
   | 'sync:error'
   | 'push:result'
@@ -193,8 +206,19 @@ type ClientEventType =
 type ClientEventPayloads = {
   'sync:start': { timestamp: number };
   'sync:complete': SyncResult;
+  'sync:trace': SyncTraceEvent;
   'sync:live': { timestamp: number };
-  'sync:error': { code: string; message: string };
+  'sync:error': {
+    code: string;
+    message: string;
+    stage?: string;
+    retryable?: boolean;
+    httpStatus?: number;
+    subscriptionId?: string;
+    chunkId?: string;
+    table?: string;
+    stateId?: string;
+  };
   'push:result': PushResultInfo;
   'bootstrap:start': {
     timestamp: number;
@@ -361,8 +385,11 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
         table: s.table,
         scopes: s.scopes ?? {},
         params: s.params ?? {},
+        bootstrapState: s.bootstrapState,
+        bootstrapPhase: s.bootstrapPhase,
       })),
       plugins: this.options.plugins,
+      traceEnabled: this.options.traceEnabled,
       realtimeEnabled: this.options.realtimeEnabled,
       pollIntervalMs: this.options.pollIntervalMs,
       dedupeRows: this.options.dedupeRows,
@@ -423,22 +450,14 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
   /**
    * Update subscriptions.
    */
-  updateSubscriptions(
-    subscriptions: Array<{
-      id: string;
-      table: string;
-      scopes?: Record<string, string | string[]>;
-      params?: Record<string, unknown>;
-    }>
-  ): void {
+  updateSubscriptions(subscriptions: SyncClientSubscription[]): void {
     this.options.subscriptions = subscriptions;
     if (this.engine) {
       this.engine.updateSubscriptions(
-        subscriptions.map((s) => ({
-          id: s.id,
-          table: s.table,
-          scopes: s.scopes ?? {},
-          params: s.params ?? {},
+        subscriptions.map((subscription) => ({
+          ...subscription,
+          scopes: subscription.scopes ?? {},
+          params: subscription.params ?? {},
         }))
       );
     }
@@ -447,17 +466,14 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
   /**
    * Get current subscriptions.
    */
-  getSubscriptions(): Array<{
-    id: string;
-    table: string;
-    scopes: Record<string, string | string[]>;
-    params: Record<string, unknown>;
-  }> {
+  getSubscriptions(): SyncClientSubscription[] {
     return this.options.subscriptions.map((s) => ({
       id: s.id,
       table: s.table,
       scopes: s.scopes ?? {},
       params: s.params ?? {},
+      bootstrapState: s.bootstrapState,
+      bootstrapPhase: s.bootstrapPhase,
     }));
   }
 
@@ -502,7 +518,17 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
       connectionState: engineState.connectionState,
       lastSyncAt: engineState.lastSyncAt,
       error: engineState.error
-        ? { code: engineState.error.code, message: engineState.error.message }
+        ? {
+            code: engineState.error.code,
+            message: engineState.error.message,
+            stage: engineState.error.stage,
+            retryable: engineState.error.retryable,
+            httpStatus: engineState.error.httpStatus,
+            subscriptionId: engineState.error.subscriptionId,
+            chunkId: engineState.error.chunkId,
+            table: engineState.error.table,
+            stateId: engineState.error.stateId,
+          }
         : null,
       outbox: this.outboxStats,
     };
@@ -524,6 +550,16 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
     return this.engine.getProgress();
   }
 
+  /**
+   * Get bootstrap readiness for the configured blocking phase or a selected subset.
+   */
+  async getBootstrapStatus(
+    options?: SyncBootstrapStatusOptions
+  ): Promise<SyncBootstrapStatus | null> {
+    if (!this.engine) return null;
+    return this.engine.getBootstrapStatus(options);
+  }
+
   /**
    * Get a diagnostics snapshot for support/debug flows.
    */
@@ -957,12 +993,26 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
       });
     });
 
+    this.engine.on('sync:trace', (payload) => {
+      this.emit('sync:trace', payload);
+    });
+
     this.engine.on('sync:live', (payload) => {
       this.emit('sync:live', payload);
     });
 
     this.engine.on('sync:error', (error) => {
-      this.emit('sync:error', { code: error.code, message: error.message });
+      this.emit('sync:error', {
+        code: error.code,
+        message: error.message,
+        stage: error.stage,
+        retryable: error.retryable,
+        httpStatus: error.httpStatus,
+        subscriptionId: error.subscriptionId,
+        chunkId: error.chunkId,
+        table: error.table,
+        stateId: error.stateId,
+      });
     });
 
     this.engine.on('push:result', (payload) => {

package/src/engine/SyncEngine.test.ts

@@ -225,6 +225,70 @@ describe('SyncEngine WS inline apply', () => {
     expect(snapshot.diagnostics).toBeDefined();
   });
 
+  it('emits structured pull/apply trace events when tracing is enabled', async () => {
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
+
+    const transport: SyncTransport = {
+      async sync() {
+        return {
+          pull: {
+            ok: true,
+            subscriptions: [
+              {
+                id: 'sub-1',
+                status: 'active',
+                table: 'tasks',
+                scopes: {},
+                bootstrap: false,
+                commits: [],
+                snapshots: [],
+                nextCursor: 0,
+              },
+            ],
+          },
+        };
+      },
+    };
+
+    const engine = new SyncEngine<TestDb>({
+      db,
+      transport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-trace',
+      subscriptions: [{ id: 'sub-1', table: 'tasks', scopes: {} }],
+      stateId: 'default',
+      traceEnabled: true,
+    });
+
+    const stages: string[] = [];
+    engine.on('sync:trace', (payload) => {
+      stages.push(payload.stage);
+    });
+
+    await engine.start();
+
+    expect(stages).toContain('pull:start');
+    expect(stages).toContain('pull:response');
+    expect(stages).toContain('apply:transaction:start');
+    expect(stages).toContain('apply:transaction:complete');
+    expect(stages).toContain('apply:subscription:start');
+    expect(stages).toContain('apply:subscription:complete');
+
+    const snapshot = await engine.getInspectorSnapshot({ eventLimit: 50 });
+    const traceEvents = snapshot.recentEvents.filter(
+      (event) => event.event === 'sync:trace'
+    );
+    expect(traceEvents.length).toBeGreaterThan(0);
+  });
+
   it('coalesces rapid data:change emissions when debounce is configured', async () => {
     const handlers: ClientHandlerCollection<TestDb> = [
       {
@@ -681,11 +745,185 @@ describe('SyncEngine WS inline apply', () => {
 
     const state = engine.getState();
     expect(state.error?.code).toBe('SNAPSHOT_CHUNK_NOT_FOUND');
+    expect(state.error?.stage).toBe('pull');
     expect(state.error?.retryable).toBe(false);
     expect(state.retryCount).toBe(1);
     expect(state.isRetrying).toBe(false);
   });
 
+  it('classifies gzip decode failures with chunk metadata', async () => {
+    const invalidCompressed = new Uint8Array(
+      gzipSync(new TextEncoder().encode('truncated-gzip')).subarray(0, 8)
+    );
+    const transport: SyncTransport = {
+      capabilities: {
+        snapshotChunkReadMode: 'bytes',
+        preferMaterializedSnapshots: true,
+      },
+      async sync() {
+        return {
+          pull: {
+            ok: true,
+            subscriptions: [
+              {
+                id: 'sub-1',
+                status: 'active',
+                scopes: {},
+                bootstrap: true,
+                bootstrapState: null,
+                nextCursor: 1,
+                commits: [],
+                snapshots: [
+                  {
+                    table: 'tasks',
+                    rows: [],
+                    chunks: [
+                      {
+                        id: 'chunk-1',
+                        byteLength: invalidCompressed.length,
+                        sha256: '',
+                        encoding: 'json-row-frame-v1',
+                        compression: 'gzip',
+                      },
+                    ],
+                    isFirstPage: true,
+                    isLastPage: true,
+                  },
+                ],
+              },
+            ],
+          },
+        };
+      },
+      async fetchSnapshotChunk() {
+        return invalidCompressed;
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
+
+    const engine = new SyncEngine<TestDb>({
+      db,
+      transport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-gzip-failure',
+      subscriptions: [
+        {
+          id: 'sub-1',
+          table: 'tasks',
+          scopes: {},
+        },
+      ],
+      stateId: 'default',
+      pollIntervalMs: 60_000,
+      maxRetries: 1,
+    });
+
+    await engine.start();
+    engine.stop();
+
+    const state = engine.getState();
+    expect(state.error?.code).toBe('SNAPSHOT_GZIP_DECODE_FAILED');
+    expect(state.error?.stage).toBe('snapshot-gzip-decode');
+    expect(state.error?.subscriptionId).toBe('sub-1');
+    expect(state.error?.chunkId).toBe('chunk-1');
+    expect(state.error?.table).toBe('tasks');
+    expect(state.error?.retryable).toBe(false);
+  });
+
+  it('classifies snapshot apply failures with stage metadata', async () => {
+    const rows = [{ id: 't2', title: 'new', server_version: 1 }];
+    const encoded = encodeSnapshotRows(rows);
+    const compressed = new Uint8Array(gzipSync(encoded));
+    const transport: SyncTransport = {
+      async sync() {
+        return {
+          pull: {
+            ok: true,
+            subscriptions: [
+              {
+                id: 'sub-1',
+                status: 'active',
+                scopes: {},
+                bootstrap: true,
+                bootstrapState: null,
+                nextCursor: 1,
+                commits: [],
+                snapshots: [
+                  {
+                    table: 'tasks',
+                    rows: [],
+                    chunks: [
+                      {
+                        id: 'chunk-1',
+                        byteLength: compressed.length,
+                        sha256: '',
+                        encoding: 'json-row-frame-v1',
+                        compression: 'gzip',
+                      },
+                    ],
+                    isFirstPage: true,
+                    isLastPage: true,
+                  },
+                ],
+              },
+            ],
+          },
+        };
+      },
+      async fetchSnapshotChunk() {
+        return compressed;
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {
+          throw new Error('forced snapshot apply failure');
+        },
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
+
+    const engine = new SyncEngine<TestDb>({
+      db,
+      transport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-apply-failure',
+      subscriptions: [
+        {
+          id: 'sub-1',
+          table: 'tasks',
+          scopes: {},
+        },
+      ],
+      stateId: 'default',
+      pollIntervalMs: 60_000,
+      maxRetries: 1,
+    });
+
+    await engine.start();
+    engine.stop();
+
+    const state = engine.getState();
+    expect(state.error?.code).toBe('SNAPSHOT_APPLY_FAILED');
+    expect(state.error?.stage).toBe('snapshot-apply');
+    expect(state.error?.subscriptionId).toBe('sub-1');
+    expect(state.error?.table).toBe('tasks');
+    expect(state.error?.retryable).toBe(false);
+  });
+
   it('skips outbox and conflict refresh after a read-only successful sync', async () => {
     const handlers: ClientHandlerCollection<TestDb> = [
       {