@syncular/client 0.0.6-136 → 0.0.6-139

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.0.6-136",
+  "version": "0.0.6-139",
   "description": "Client-side sync engine with offline-first support, outbox, and conflict resolution",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -46,8 +46,8 @@
     "release": "bunx syncular-publish"
   },
   "dependencies": {
-    "@syncular/core": "0.0.6-136",
-    "@syncular/transport-http": "0.0.6-136"
+    "@syncular/core": "0.0.6-139",
+    "@syncular/transport-http": "0.0.6-139"
   },
   "peerDependencies": {
     "kysely": "*"

package/src/client.test.ts

@@ -141,13 +141,13 @@ describe('Client conflict events', () => {
   }
 
   async function runConflictCheck(
-    clientInstance: Client<TestDb>
+    engineInstance: SyncEngine<TestDb>
   ): Promise<void> {
-    const checker = Reflect.get(clientInstance, 'checkForNewConflicts');
+    const checker = Reflect.get(engineInstance, 'emitNewConflicts');
     if (typeof checker !== 'function') {
-      throw new Error('Expected checkForNewConflicts to be callable');
+      throw new Error('Expected emitNewConflicts to be callable');
     }
-    await checker.call(clientInstance);
+    await checker.call(engineInstance);
   }
 
   beforeEach(async () => {
@@ -184,6 +184,11 @@ describe('Client conflict events', () => {
       subscriptions: [],
     });
     Reflect.set(client, 'engine', engine);
+    const wireEngineEvents = Reflect.get(client, 'wireEngineEvents');
+    if (typeof wireEngineEvents !== 'function') {
+      throw new Error('Expected wireEngineEvents to be callable');
+    }
+    wireEngineEvents.call(client);
   });
 
   afterEach(async () => {
@@ -220,11 +225,43 @@ describe('Client conflict events', () => {
       newEvents.push(conflict.id);
     });
 
-    await runConflictCheck(client);
-    await runConflictCheck(client);
+    await runConflictCheck(engine);
+    await runConflictCheck(engine);
 
     expect(newEvents).toEqual(['conflict-1']);
   });
+
+  it('forwards push:result events from the engine', () => {
+    const pushResults: Array<{ clientCommitId: string; status: string }> = [];
+    client.on('push:result', (result) => {
+      pushResults.push({
+        clientCommitId: result.clientCommitId,
+        status: result.status,
+      });
+    });
+
+    const emit = Reflect.get(engine, 'emit');
+    if (typeof emit !== 'function') {
+      throw new Error('Expected SyncEngine.emit to be callable');
+    }
+
+    emit.call(engine, 'push:result', {
+      outboxCommitId: 'outbox-1',
+      clientCommitId: 'commit-1',
+      status: 'rejected',
+      commitSeq: null,
+      results: [],
+      errorCode: 'CONFLICT',
+      timestamp: Date.now(),
+    });
+
+    expect(pushResults).toEqual([
+      {
+        clientCommitId: 'commit-1',
+        status: 'rejected',
+      },
+    ]);
+  });
 });
 
 describe('Client blob upload queue recovery', () => {

package/src/client.ts

@@ -24,6 +24,7 @@ import type {
   ConflictInfo,
   OutboxStats,
   PresenceEntry,
+  PushResultInfo,
   SubscriptionProgress,
   SyncAwaitBootstrapOptions,
   SyncAwaitPhaseOptions,
@@ -122,21 +123,22 @@ export interface ClientOptions<DB extends SyncClientDb> {
 
   /**
    * Optional: Debounce window (ms) for coalescing `data:change` events.
-   * - `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;
   /**
    * Optional: Debounce override while sync is actively running.
    * Falls back to `dataChangeDebounceMs` when omitted.
    */
-  dataChangeDebounceMsWhenSyncing?: number;
+  dataChangeDebounceMsWhenSyncing?: number | false;
   /**
    * Optional: Debounce override while connection is reconnecting.
    * Falls back to `dataChangeDebounceMsWhenSyncing` (if syncing) and then
    * `dataChangeDebounceMs` when omitted.
    */
-  dataChangeDebounceMsWhenReconnecting?: number;
+  dataChangeDebounceMsWhenReconnecting?: number | false;
 
   /** Optional: State ID for multi-tenant scenarios */
   stateId?: string;
@@ -249,6 +251,7 @@ type ClientEventType =
   | 'sync:complete'
   | 'sync:live'
   | 'sync:error'
+  | 'push:result'
   | 'bootstrap:start'
   | 'bootstrap:progress'
   | 'bootstrap:complete'
@@ -266,6 +269,7 @@ type ClientEventPayloads = {
   'sync:complete': SyncResult;
   'sync:live': { timestamp: number };
   'sync:error': { code: string; message: string };
+  'push:result': PushResultInfo;
   'bootstrap:start': {
     timestamp: number;
     stateId: string;
@@ -332,7 +336,6 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
   private engine: SyncEngine<DB> | null = null;
   private started = false;
   private destroyed = false;
-  private emittedConflictIds = new Set<string>();
   private eventListeners = new Map<
     ClientEventType,
     Set<ClientEventHandler<any>>
@@ -758,7 +761,6 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
       },
     });
 
-    this.emittedConflictIds.delete(id);
     if (resolvedConflict) {
       this.emit('conflict:resolved', resolvedConflict);
     }
@@ -975,9 +977,14 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
 
     this.engine.on('sync:error', (error) => {
       this.emit('sync:error', { code: error.code, message: error.message });
+    });
+
+    this.engine.on('push:result', (payload) => {
+      this.emit('push:result', payload);
+    });
 
-      // Check for new conflicts after sync error
-      this.checkForNewConflicts();
+    this.engine.on('conflict:new', (payload) => {
+      this.emit('conflict:new', this.mapConflictInfo(payload));
     });
 
     this.engine.on('bootstrap:start', (payload) => {
@@ -1020,25 +1027,6 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
     });
   }
 
-  private async checkForNewConflicts(): 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);
-      }
-    }
-
-    for (const conflict of conflicts) {
-      if (this.emittedConflictIds.has(conflict.id)) {
-        continue;
-      }
-      this.emittedConflictIds.add(conflict.id);
-      this.emit('conflict:new', conflict);
-    }
-  }
-
   private mapConflictInfo(info: ConflictInfo): Conflict {
     let serverPayload: Record<string, unknown> | null = null;
     if (info.serverRowJson) {

package/src/create-client.ts

@@ -143,21 +143,22 @@ interface CreateClientOptions<DB extends SyncClientDb> {
     pollIntervalMs?: number;
     /**
      * Debounce window (ms) for coalescing `data:change` events.
-     * - `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;
     /**
      * Debounce override while sync is actively running.
      * Falls back to `dataChangeDebounceMs` when omitted.
      */
-    dataChangeDebounceMsWhenSyncing?: number;
+    dataChangeDebounceMsWhenSyncing?: number | false;
     /**
      * Debounce override while connection is reconnecting.
      * Falls back to `dataChangeDebounceMsWhenSyncing` (if syncing) and then
      * `dataChangeDebounceMs` when omitted.
      */
-    dataChangeDebounceMsWhenReconnecting?: number;
+    dataChangeDebounceMsWhenReconnecting?: number | false;
   };
 
   /** Optional: Local blob storage adapter */

package/src/engine/SyncEngine.test.ts

@@ -273,6 +273,89 @@ describe('SyncEngine WS inline apply', () => {
     expect(onDataChangeCalls).toEqual([['tasks']]);
   });
 
+  it('uses 10ms debounce by default and supports 0/false opt-out', async () => {
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
+
+    const defaultEngine = new SyncEngine<TestDb>({
+      db,
+      transport: noopTransport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-default-debounce',
+      subscriptions: [],
+      stateId: 'default',
+    });
+
+    const defaultEvents: string[][] = [];
+    defaultEngine.on('data:change', (payload) => {
+      defaultEvents.push(payload.scopes);
+    });
+
+    defaultEngine.recordLocalMutations([
+      { table: 'tasks', rowId: 'd1', op: 'upsert' },
+    ]);
+    defaultEngine.recordLocalMutations([
+      { table: 'tasks', rowId: 'd2', op: 'upsert' },
+    ]);
+    expect(defaultEvents).toEqual([]);
+
+    await new Promise<void>((resolve) => setTimeout(resolve, 20));
+    expect(defaultEvents).toEqual([['tasks']]);
+
+    const noDebounceEngine = new SyncEngine<TestDb>({
+      db,
+      transport: noopTransport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-no-debounce',
+      subscriptions: [],
+      stateId: 'default',
+      dataChangeDebounceMs: false,
+    });
+
+    const immediateEvents: string[][] = [];
+    noDebounceEngine.on('data:change', (payload) => {
+      immediateEvents.push(payload.scopes);
+    });
+
+    noDebounceEngine.recordLocalMutations([
+      { table: 'tasks', rowId: 'n1', op: 'upsert' },
+    ]);
+    expect(immediateEvents).toEqual([['tasks']]);
+
+    const zeroDebounceEngine = new SyncEngine<TestDb>({
+      db,
+      transport: noopTransport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-zero-debounce',
+      subscriptions: [],
+      stateId: 'default',
+      dataChangeDebounceMs: 0,
+    });
+
+    const zeroEvents: string[][] = [];
+    zeroDebounceEngine.on('data:change', (payload) => {
+      zeroEvents.push(payload.scopes);
+    });
+
+    zeroDebounceEngine.recordLocalMutations([
+      { table: 'tasks', rowId: 'z1', op: 'upsert' },
+    ]);
+    expect(zeroEvents).toEqual([['tasks']]);
+
+    defaultEngine.destroy();
+    noDebounceEngine.destroy();
+    zeroDebounceEngine.destroy();
+  });
+
   it('supports adaptive debounce overrides while syncing and reconnecting', async () => {
     const handlers: ClientHandlerCollection<TestDb> = [
       {
@@ -301,6 +384,11 @@ describe('SyncEngine WS inline apply', () => {
       eventScopes.push(payload.scopes);
     });
 
+    const setConnectionState = Reflect.get(engine, 'setConnectionState');
+    if (typeof setConnectionState !== 'function') {
+      throw new Error('Expected setConnectionState to be callable');
+    }
+
     const updateState = Reflect.get(engine, 'updateState');
     if (typeof updateState !== 'function') {
       throw new Error('Expected updateState to be callable');
@@ -320,17 +408,28 @@ describe('SyncEngine WS inline apply', () => {
     expect(eventScopes).toEqual([['tasks']]);
 
     updateState.call(engine, {
-      isSyncing: true,
-      connectionState: 'reconnecting',
+      isSyncing: false,
+      connectionState: 'connected',
     });
+    setConnectionState.call(engine, 'reconnecting');
 
     engine.recordLocalMutations([
       { table: 'tasks', rowId: 'reconnecting-1', op: 'upsert' },
     ]);
-    await new Promise<void>((resolve) => setTimeout(resolve, 20));
+    await new Promise<void>((resolve) => setTimeout(resolve, 50));
     expect(eventScopes).toEqual([['tasks']]);
 
-    await new Promise<void>((resolve) => setTimeout(resolve, 25));
+    setConnectionState.call(engine, 'connected');
+    const flushReconnectBatch = Reflect.get(
+      engine,
+      'flushReconnectBatchedDataChangesIfReady'
+    );
+    if (typeof flushReconnectBatch !== 'function') {
+      throw new Error(
+        'Expected flushReconnectBatchedDataChangesIfReady to be callable'
+      );
+    }
+    flushReconnectBatch.call(engine);
     expect(eventScopes).toEqual([['tasks'], ['tasks']]);
   });