@syncular/client 0.0.6-136 → 0.0.6-139

package/src/engine/SyncEngine.ts

@@ -37,6 +37,7 @@ import type {
   ConflictInfo,
   OutboxStats,
   PresenceEntry,
+  PushResultInfo,
   RealtimeTransportLike,
   SubscriptionProgress,
   SyncAwaitBootstrapOptions,
@@ -70,6 +71,7 @@ const REALTIME_RECONNECT_CATCHUP_DELAY_MS = 500;
 const DEFAULT_AWAIT_TIMEOUT_MS = 60_000;
 const DEFAULT_INSPECTOR_EVENT_LIMIT = 100;
 const MAX_INSPECTOR_EVENT_LIMIT = 500;
+const DEFAULT_DATA_CHANGE_DEBOUNCE_MS = 10;
 
 function calculateRetryDelay(attemptIndex: number): number {
   return Math.min(
@@ -303,6 +305,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   private dataChangeDebounceTimeoutId: ReturnType<typeof setTimeout> | null =
     null;
   private pendingDataChangeScopes = new Set<string>();
+  private batchDataChangeUntilReconnectSettles = false;
   private hasRealtimeConnectedOnce = false;
   private transportHealth: TransportHealth = {
     mode: 'disconnected',
@@ -313,6 +316,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   };
   private activeBootstrapSubscriptions = new Set<string>();
   private bootstrapStartedAt = new Map<string, number>();
+  private emittedConflictIds = new Set<string>();
   private inspectorEvents: SyncInspectorEvent[] = [];
   private nextInspectorEventId = 1;
 
@@ -809,19 +813,41 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     this.emit('state:change', {});
   }
 
-  private resolveDataChangeDebounceMs(): number {
-    const normalize = (value: number | undefined): number | undefined => {
-      if (value === undefined) return undefined;
-      return Number.isFinite(value) ? Math.max(0, value) : 0;
-    };
+  private normalizeDataChangeDebounceMs(
+    value: number | false | undefined
+  ): number | false | undefined {
+    if (value === undefined) return undefined;
+    if (value === false) return false;
+    return Number.isFinite(value) ? Math.max(0, value) : 0;
+  }
+
+  private resolveReconnectDataChangeDebounceMs(): number | false {
+    const reconnectDebounce = this.normalizeDataChangeDebounceMs(
+      this.config.dataChangeDebounceMsWhenReconnecting
+    );
+    if (reconnectDebounce !== undefined) {
+      return reconnectDebounce;
+    }
+
+    const syncingDebounce = this.normalizeDataChangeDebounceMs(
+      this.config.dataChangeDebounceMsWhenSyncing
+    );
+    if (syncingDebounce !== undefined) {
+      return syncingDebounce;
+    }
+
+    return (
+      this.normalizeDataChangeDebounceMs(this.config.dataChangeDebounceMs) ??
+      DEFAULT_DATA_CHANGE_DEBOUNCE_MS
+    );
+  }
+
+  private resolveDataChangeDebounceMs(): number | false {
+    const normalize = (value: number | false | undefined) =>
+      this.normalizeDataChangeDebounceMs(value);
 
     if (this.state.connectionState === 'reconnecting') {
-      const reconnectDebounce = normalize(
-        this.config.dataChangeDebounceMsWhenReconnecting
-      );
-      if (reconnectDebounce !== undefined) {
-        return reconnectDebounce;
-      }
+      return this.resolveReconnectDataChangeDebounceMs();
     }
 
     if (this.state.isSyncing) {
@@ -833,7 +859,24 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       }
     }
 
-    return normalize(this.config.dataChangeDebounceMs) ?? 0;
+    return (
+      normalize(this.config.dataChangeDebounceMs) ??
+      DEFAULT_DATA_CHANGE_DEBOUNCE_MS
+    );
+  }
+
+  private flushReconnectBatchedDataChangesIfReady(): void {
+    if (!this.batchDataChangeUntilReconnectSettles) return;
+    if (this.state.isSyncing || this.state.connectionState === 'reconnecting') {
+      return;
+    }
+
+    this.batchDataChangeUntilReconnectSettles = false;
+    if (this.dataChangeDebounceTimeoutId) {
+      clearTimeout(this.dataChangeDebounceTimeoutId);
+      this.dataChangeDebounceTimeoutId = null;
+    }
+    this.flushDataChange();
   }
 
   private emitDataChange(scopes: Iterable<string>): void {
@@ -847,7 +890,19 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     if (normalizedScopes.size === 0) return;
 
     const debounceMs = this.resolveDataChangeDebounceMs();
-    if (debounceMs <= 0) {
+    const shouldBatchWithoutTimer =
+      (this.batchDataChangeUntilReconnectSettles ||
+        this.state.connectionState === 'reconnecting') &&
+      debounceMs !== false &&
+      debounceMs > 0;
+    if (shouldBatchWithoutTimer) {
+      for (const scope of normalizedScopes) {
+        this.pendingDataChangeScopes.add(scope);
+      }
+      return;
+    }
+
+    if (debounceMs === false || debounceMs <= 0) {
       this.flushDataChange(normalizedScopes);
       return;
     }
@@ -1133,6 +1188,49 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     }
   }
 
+  private emitPushResult(result: PushResultInfo): void {
+    this.emit('push:result', result);
+    this.config.onPushResult?.(result);
+  }
+
+  private async emitNewConflicts(): Promise<void> {
+    const conflicts = await this.getConflicts();
+    const activeIds = new Set(conflicts.map((conflict) => conflict.id));
+
+    for (const id of this.emittedConflictIds) {
+      if (!activeIds.has(id)) {
+        this.emittedConflictIds.delete(id);
+      }
+    }
+
+    const sorted = [...conflicts].sort((left, right) => {
+      if (left.createdAt !== right.createdAt) {
+        return left.createdAt - right.createdAt;
+      }
+      return left.opIndex - right.opIndex;
+    });
+
+    for (const conflict of sorted) {
+      if (this.emittedConflictIds.has(conflict.id)) {
+        continue;
+      }
+      this.emittedConflictIds.add(conflict.id);
+      this.emit('conflict:new', conflict);
+      this.config.onConflict?.(conflict);
+    }
+  }
+
+  private async emitNewConflictsSafe(context: string): Promise<void> {
+    try {
+      await this.emitNewConflicts();
+    } catch (error) {
+      console.warn(
+        `[SyncEngine] Failed to emit conflict:new during ${context}`,
+        error
+      );
+    }
+  }
+
   private async resolveResetTargets(
     options: SyncResetOptions
   ): Promise<SubscriptionState[]> {
@@ -1279,6 +1377,9 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
     this.resetLocalState();
     await this.refreshOutboxStats();
+    if (result.deletedConflicts > 0) {
+      this.emittedConflictIds.clear();
+    }
     this.updateState({ error: null });
 
     return result;
@@ -1399,9 +1500,41 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
   private setConnectionState(state: SyncConnectionState): void {
     const previous = this.state.connectionState;
-    if (previous !== state) {
-      this.updateState({ connectionState: state });
-      this.emit('connection:change', { previous, current: state });
+    if (previous === state) return;
+
+    const reconnectDebounceMs = this.resolveReconnectDataChangeDebounceMs();
+    if (
+      state === 'reconnecting' &&
+      reconnectDebounceMs !== false &&
+      reconnectDebounceMs > 0
+    ) {
+      this.batchDataChangeUntilReconnectSettles = true;
+      if (this.dataChangeDebounceTimeoutId) {
+        clearTimeout(this.dataChangeDebounceTimeoutId);
+        this.dataChangeDebounceTimeoutId = null;
+      }
+    }
+
+    this.updateState({ connectionState: state });
+    this.emit('connection:change', { previous, current: state });
+
+    if (previous === 'reconnecting' && state === 'connected') {
+      queueMicrotask(() => {
+        this.flushReconnectBatchedDataChangesIfReady();
+      });
+    }
+
+    if (previous === 'reconnecting' && state !== 'connected') {
+      this.batchDataChangeUntilReconnectSettles = false;
+      if (this.dataChangeDebounceTimeoutId) {
+        clearTimeout(this.dataChangeDebounceTimeoutId);
+        this.dataChangeDebounceTimeoutId = null;
+      }
+      this.flushDataChange();
+    }
+
+    if (state === 'disconnected') {
+      this.batchDataChangeUntilReconnectSettles = false;
     }
   }
 
@@ -1446,6 +1579,9 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
                 }
               );
               pushed = result.pushed;
+              if (result.pushResult) {
+                this.emitPushResult(result.pushResult);
+              }
             }
           }
         } catch {
@@ -1636,6 +1772,10 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
           )
       );
 
+      for (const pushResult of result.pushResults) {
+        this.emitPushResult(pushResult);
+      }
+
       const syncResult: SyncResult = {
         success: true,
         pushedCommits: result.pushedCommits,
@@ -1674,6 +1814,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
         this.emitDataChange(changedTables);
       }
       this.handleBootstrapLifecycle(result.pullResponse);
+      await this.emitNewConflictsSafe('sync success');
 
       // Refresh outbox stats (fire-and-forget — don't block sync:complete)
       this.refreshOutboxStats().catch((error) => {
@@ -1711,6 +1852,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
           attributes: { trigger: triggerLabel },
         }
       );
+      this.flushReconnectBatchedDataChangesIfReady();
 
       return syncResult;
     } catch (err) {
@@ -1732,6 +1874,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       });
 
       this.handleError(error);
+      await this.emitNewConflictsSafe('sync error');
 
       const durationMs = Math.max(0, Date.now() - startedAtMs);
       countSyncMetric('sync.client.sync.results', 1, {
@@ -1757,6 +1900,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       if (error.retryable && this.state.retryCount < maxRetries) {
         this.scheduleRetry();
       }
+      this.flushReconnectBatchedDataChangesIfReady();
 
       return {
         success: false,
@@ -1797,9 +1941,17 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
    */
   private async applyWsDeliveredChanges(
     changes: SyncChange[],
-    cursor: number
+    cursor: number,
+    metadata?: {
+      commitSeq?: number;
+      actorId?: string | null;
+      createdAt?: string | null;
+    }
   ): Promise<boolean> {
     try {
+      const commitSeq = metadata?.commitSeq ?? cursor;
+      const actorId = metadata?.actorId ?? null;
+      const createdAt = metadata?.createdAt ?? null;
       await this.config.db.transaction().execute(async (trx) => {
         for (const change of changes) {
           const handler = getClientHandler(this.config.handlers, change.table);
@@ -1808,7 +1960,15 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
               `Missing client table handler for WS change table "${change.table}"`
             );
           }
-          await handler.applyChange({ trx }, change);
+          await handler.applyChange(
+            {
+              trx,
+              commitSeq,
+              actorId,
+              createdAt,
+            },
+            change
+          );
         }
 
         // Update subscription cursors
@@ -1851,7 +2011,12 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
    */
   private async handleWsDelivery(
     changes: SyncChange[],
-    cursor: number
+    cursor: number,
+    metadata?: {
+      commitSeq?: number;
+      actorId?: string | null;
+      createdAt?: string | null;
+    }
   ): Promise<void> {
     // If a sync is already in-flight, let it handle everything
     if (this.syncPromise) {
@@ -1895,7 +2060,11 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
 
     // Apply changes + update cursor
     const inlineApplyStartedAtMs = Date.now();
-    const applied = await this.applyWsDeliveredChanges(changes, cursor);
+    const applied = await this.applyWsDeliveredChanges(
+      changes,
+      cursor,
+      metadata
+    );
     const inlineApplyDurationMs = Math.max(
       0,
       Date.now() - inlineApplyStartedAtMs
@@ -2161,10 +2330,27 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
           const hasInlineChanges =
             Array.isArray(event.data.changes) && event.data.changes.length > 0;
           const cursor = event.data.cursor;
+          const commitSeqRaw = event.data.commitSeq;
+          const commitSeq =
+            typeof commitSeqRaw === 'number'
+              ? commitSeqRaw
+              : typeof cursor === 'number'
+                ? cursor
+                : undefined;
+          const actorId =
+            typeof event.data.actorId === 'string' ? event.data.actorId : null;
+          const createdAt =
+            typeof event.data.createdAt === 'string'
+              ? event.data.createdAt
+              : null;
 
           if (hasInlineChanges && typeof cursor === 'number') {
             // WS delivered changes + cursor — may skip HTTP pull
-            this.handleWsDelivery(event.data.changes as SyncChange[], cursor);
+            this.handleWsDelivery(event.data.changes as SyncChange[], cursor, {
+              commitSeq,
+              actorId,
+              createdAt,
+            });
           } else {
             // Cursor-only wake-up or no cursor — must HTTP sync
             countSyncMetric('sync.client.ws.delivery.events', 1, {

package/src/engine/types.ts

@@ -140,14 +140,28 @@ export type SyncEventType =
   | 'sync:complete'
   | 'sync:live'
   | 'sync:error'
+  | 'push:result'
   | 'bootstrap:start'
   | 'bootstrap:progress'
   | 'bootstrap:complete'
   | 'connection:change'
   | 'outbox:change'
   | 'data:change'
+  | 'conflict:new'
   | 'presence:change';
 
+export type PushResultStatus = 'applied' | 'cached' | 'rejected' | 'retriable';
+
+export interface PushResultInfo {
+  outboxCommitId: string;
+  clientCommitId: string;
+  status: PushResultStatus;
+  commitSeq: number | null;
+  results: SyncPushResponse['results'];
+  errorCode: string | null;
+  timestamp: number;
+}
+
 /**
  * Presence entry for a client connected to a scope
  */
@@ -172,6 +186,7 @@ export interface SyncEventPayloads {
   };
   'sync:live': { timestamp: number };
   'sync:error': SyncError;
+  'push:result': PushResultInfo;
   'bootstrap:start': {
     timestamp: number;
     stateId: string;
@@ -203,6 +218,7 @@ export interface SyncEventPayloads {
     scopes: string[];
     timestamp: number;
   };
+  'conflict:new': ConflictInfo;
   'presence:change': {
     scopeKey: string;
     presence: PresenceEntry[];
@@ -260,25 +276,28 @@ export interface SyncEngineConfig<DB extends SyncClientDb = SyncClientDb> {
   onError?: (error: SyncError) => void;
   /** Conflict callback */
   onConflict?: (conflict: ConflictInfo) => void;
+  /** Per-commit push outcome callback */
+  onPushResult?: (result: PushResultInfo) => void;
   /** Data change callback */
   onDataChange?: (scopes: string[]) => void;
   /**
    * Debounce window for coalescing `data:change` emissions.
-   * - `0` (default): emit immediately
+   * - default: `10`
+   * - `0`/`false`: emit immediately (disable debounce)
    * - `>0`: merge scopes and emit once per window
    */
-  dataChangeDebounceMs?: number;
+  dataChangeDebounceMs?: number | false;
   /**
    * Override debounce window while `isSyncing === true`.
    * If omitted, `dataChangeDebounceMs` is used.
    */
-  dataChangeDebounceMsWhenSyncing?: number;
+  dataChangeDebounceMsWhenSyncing?: number | false;
   /**
    * Override debounce window while `connectionState === "reconnecting"`.
    * If omitted, `dataChangeDebounceMsWhenSyncing` (if syncing) or
    * `dataChangeDebounceMs` is used.
    */
-  dataChangeDebounceMsWhenReconnecting?: number;
+  dataChangeDebounceMsWhenReconnecting?: number | false;
   /** Optional client plugins (e.g. encryption) */
   plugins?: SyncClientPlugin[];
   /** Custom SHA-256 hash function (for platforms without crypto.subtle, e.g. React Native) */
@@ -317,8 +336,11 @@ export interface RealtimeTransportLike extends SyncTransport {
       event: string;
       data: {
         cursor?: number;
+        commitSeq?: number;
         changes?: unknown[];
         error?: string;
+        actorId?: string;
+        createdAt?: string;
         timestamp: number;
       };
     }) => void,

package/src/handlers/types.ts

@@ -16,6 +16,15 @@ import type { Transaction } from 'kysely';
 export interface ClientHandlerContext<DB> {
   /** Database transaction */
   trx: Transaction<DB>;
+  /**
+   * Commit metadata for server-delivered changes.
+   * Undefined for local optimistic changes.
+   */
+  commitSeq?: number | null;
+  /** Actor that authored the server commit, when available. */
+  actorId?: string | null;
+  /** Commit creation timestamp (ISO string), when available. */
+  createdAt?: string | null;
 }
 
 /**

package/src/pull-engine.test.ts

@@ -818,4 +818,98 @@ describe('applyPullResponse chunk streaming', () => {
       .executeTakeFirst();
     expect(Number(state?.cursor ?? -1)).toBe(2);
   });
+
+  it('passes commit metadata to applyChange handler context', async () => {
+    const transport: SyncTransport = {
+      async sync() {
+        return {};
+      },
+      async fetchSnapshotChunk() {
+        return new Uint8Array();
+      },
+    };
+
+    const appliedContexts: Array<{
+      commitSeq: number | null | undefined;
+      actorId: string | null | undefined;
+      createdAt: string | null | undefined;
+    }> = [];
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'items',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange(ctx) {
+          appliedContexts.push({
+            commitSeq: ctx.commitSeq,
+            actorId: ctx.actorId,
+            createdAt: ctx.createdAt,
+          });
+        },
+      },
+    ];
+
+    const options = {
+      clientId: 'client-1',
+      subscriptions: [
+        {
+          id: 'items-sub',
+          table: 'items',
+          scopes: {},
+        },
+      ],
+      stateId: 'default',
+    };
+
+    const pullState = await buildPullRequest(db, options);
+    const response: SyncPullResponse = {
+      ok: true,
+      subscriptions: [
+        {
+          id: 'items-sub',
+          status: 'active',
+          scopes: {},
+          bootstrap: false,
+          bootstrapState: null,
+          nextCursor: 7,
+          commits: [
+            {
+              commitSeq: 7,
+              actorId: 'remote-user',
+              createdAt: '2026-02-28T12:00:00.000Z',
+              changes: [
+                {
+                  table: 'items',
+                  row_id: 'item-ctx',
+                  op: 'upsert',
+                  row_version: 1,
+                  row_json: { id: 'item-ctx', name: 'ctx-test' },
+                  scopes: {},
+                },
+              ],
+            },
+          ],
+          snapshots: [],
+        },
+      ],
+    };
+
+    await applyPullResponse(
+      db,
+      transport,
+      handlers,
+      options,
+      pullState,
+      response
+    );
+
+    expect(appliedContexts).toEqual([
+      {
+        commitSeq: 7,
+        actorId: 'remote-user',
+        createdAt: '2026-02-28T12:00:00.000Z',
+      },
+    ]);
+  });
 });

package/src/pull-engine.ts

@@ -888,9 +888,20 @@ export async function applyPullResponse<DB extends SyncClientDb>(
       } else {
         // Apply incremental changes
         for (const commit of sub.commits) {
+          const commitSeq = commit.commitSeq ?? null;
+          const actorId = commit.actorId ?? null;
+          const createdAt = commit.createdAt ?? null;
           for (const change of commit.changes) {
             const handler = getClientHandlerOrThrow(handlers, change.table);
-            await handler.applyChange({ trx }, change);
+            await handler.applyChange(
+              {
+                trx,
+                commitSeq,
+                actorId,
+                createdAt,
+              },
+              change
+            );
           }
         }
       }