@syncular/client 0.0.6-219 → 0.0.6-223

package/src/sync-loop.ts

@@ -11,12 +11,15 @@ import type {
   SyncPushBatchCommitResponse,
   SyncPushRequest,
   SyncPushResponse,
-  SyncSubscriptionRequest,
   SyncTransport,
 } from '@syncular/core';
 import type { Kysely } from 'kysely';
 import { upsertConflictsForRejectedCommit } from './conflicts';
-import type { PushResultInfo } from './engine/types';
+import type {
+  PushResultInfo,
+  SyncClientSubscription,
+  SyncTraceEvent,
+} from './engine/types';
 import type { ClientHandlerCollection } from './handlers/collection';
 import {
   getNextSendableOutboxCommit,
@@ -482,6 +485,16 @@ function mergePullResponse(
   }
 }
 
+function emitTrace(
+  onTrace: SyncOnceOptions['onTrace'] | SyncPullOnceOptions['onTrace'],
+  event: Omit<SyncTraceEvent, 'timestamp'>
+): void {
+  onTrace?.({
+    timestamp: Date.now(),
+    ...event,
+  });
+}
+
 function canSkipPullAfterLocalWsPush(
   pullState: SyncPullRequestState,
   pushResponse: SyncPushResponse | null,
@@ -551,7 +564,7 @@ export interface SyncOnceOptions {
   clientId: string;
   actorId?: string;
   plugins?: SyncPushOnceOptions['plugins'];
-  subscriptions: Array<Omit<SyncSubscriptionRequest, 'cursor'>>;
+  subscriptions: SyncClientSubscription[];
   limitCommits?: number;
   limitSnapshotRows?: number;
   maxSnapshotPages?: number;
@@ -565,6 +578,8 @@ export interface SyncOnceOptions {
   allowSkipPullOnLocalWsPush?: boolean;
   /** Custom SHA-256 hash function (for platforms without crypto.subtle) */
   sha256?: (bytes: Uint8Array) => Promise<string>;
+  /** Optional structured tracing hook for pull/apply lifecycle diagnostics. */
+  onTrace?: (event: SyncTraceEvent) => void;
 }
 
 export interface SyncOnceResult {
@@ -600,6 +615,7 @@ async function syncOnceCombined<DB extends SyncClientDb>(
     dedupeRows: options.dedupeRows,
     stateId: options.stateId,
     sha256: options.sha256,
+    onTrace: options.onTrace,
   };
 
   // Build pull request (reads subscription state)
@@ -682,6 +698,15 @@ async function syncOnceCombined<DB extends SyncClientDb>(
         advanceSequentialBaseVersionsInBatch(combinedPushCommits);
     }
 
+    const pullSubscriptionIds = pullState.request.subscriptions.map(
+      (subscription) => subscription.id
+    );
+    emitTrace(options.onTrace, {
+      stage: 'pull:start',
+      stateId: pullOpts.stateId,
+      subscriptionIds: pullSubscriptionIds,
+      subscriptionCount: pullSubscriptionIds.length,
+    });
     try {
       combined = await transport.sync({
         clientId,
@@ -704,7 +729,31 @@ async function syncOnceCombined<DB extends SyncClientDb>(
           subscriptions: pullState.request.subscriptions,
         },
       });
+      const pullSubscriptions = combined.pull?.subscriptions ?? [];
+      emitTrace(options.onTrace, {
+        stage: 'pull:response',
+        stateId: pullOpts.stateId,
+        subscriptionIds: pullSubscriptions.map(
+          (subscription) => subscription.id
+        ),
+        subscriptionCount: pullSubscriptions.length,
+        commitCount: pullSubscriptions.reduce(
+          (sum, subscription) => sum + (subscription.commits?.length ?? 0),
+          0
+        ),
+        snapshotCount: pullSubscriptions.reduce(
+          (sum, subscription) => sum + (subscription.snapshots?.length ?? 0),
+          0
+        ),
+      });
     } catch (err) {
+      emitTrace(options.onTrace, {
+        stage: 'pull:error',
+        stateId: pullOpts.stateId,
+        subscriptionIds: pullSubscriptionIds,
+        subscriptionCount: pullSubscriptionIds.length,
+        errorMessage: err instanceof Error ? err.message : String(err),
+      });
       if (combinedPushCommits.length > 0) {
         const message = err instanceof Error ? err.message : 'Unknown error';
         await markClaimedOutboxCommitsPending(

package/src/sync.ts

@@ -5,9 +5,9 @@ import type {
   ScopeValue,
   ScopeValuesFromPatterns,
   SyncIdentityBase,
-  SyncSubscriptionRequest,
 } from '@syncular/core';
 import { registerTableOrThrow } from '@syncular/core';
+import type { SyncClientSubscription } from './engine/types';
 import {
   type CreateClientHandlerOptions,
   createClientHandler,
@@ -16,7 +16,7 @@ import type { ClientTableHandler } from './handlers/types';
 import type { SyncClientDb } from './schema';
 
 type ClientSyncSubscription<ScopeDefs extends readonly ScopeDefinition[]> =
-  Omit<SyncSubscriptionRequest, 'cursor' | 'table' | 'scopes'> & {
+  Omit<SyncClientSubscription, 'table' | 'scopes'> & {
     table: string;
     scopes?: ScopeValuesFromPatterns<ScopeDefs>;
   };
@@ -51,9 +51,7 @@ export interface ClientSyncConfig<
   Identity extends SyncIdentityBase = SyncIdentityBase,
 > {
   handlers: ClientTableHandler<DB>[];
-  subscriptions(
-    identity: Identity
-  ): Array<Omit<SyncSubscriptionRequest, 'cursor'>>;
+  subscriptions(identity: Identity): SyncClientSubscription[];
 }
 
 export interface DefineClientSyncOptions {
@@ -143,10 +141,8 @@ export function defineClientSync<
       );
       return sync;
     },
-    subscriptions(
-      identity: Identity
-    ): Array<Omit<SyncSubscriptionRequest, 'cursor'>> {
-      const resolved: Array<Omit<SyncSubscriptionRequest, 'cursor'>> = [];
+    subscriptions(identity: Identity): SyncClientSubscription[] {
+      const resolved: SyncClientSubscription[] = [];
       for (const [table, subscribe] of subscriptionsByTable.entries()) {
         if (!subscribe) continue;
         const value =
@@ -160,6 +156,7 @@ export function defineClientSync<
             scopes: toScopeValues(entry.scopes),
             params: entry.params,
             bootstrapState: entry.bootstrapState,
+            bootstrapPhase: entry.bootstrapPhase,
           });
         }
       }