@syncular/client-react 0.0.1 → 0.0.2-127

package/src/__tests__/SyncEngine.test.ts

@@ -9,11 +9,12 @@ import {
   type SyncClientDb,
   SyncEngine,
   type SyncEngineConfig,
+  type SyncPullSubscriptionResponse,
 } from '@syncular/client';
 import type { Kysely } from 'kysely';
 import {
   createMockDb,
-  createMockShapeRegistry,
+  createMockHandlerRegistry,
   createMockTransport,
   flushPromises,
   waitFor,
@@ -35,7 +36,7 @@ describe('SyncEngine', () => {
     const config: SyncEngineConfig = {
       db,
       transport: createMockTransport(),
-      shapes: createMockShapeRegistry(),
+      handlers: createMockHandlerRegistry(),
       actorId: 'test-actor',
       clientId: 'test-client',
       subscriptions: [],
@@ -77,6 +78,39 @@ describe('SyncEngine', () => {
 
       expect(state.transportMode).toBe('polling');
     });
+
+    it('should auto-detect realtime mode for realtime-capable transport', () => {
+      type ConnState = 'disconnected' | 'connecting' | 'connected';
+
+      let currentState: ConnState = 'disconnected';
+      const base = createMockTransport();
+      const realtimeTransport = {
+        ...base,
+        connect(
+          _args: { clientId: string },
+          _onEvent: (_event: unknown) => void,
+          onStateChange?: (state: ConnState) => void
+        ) {
+          currentState = 'connected';
+          onStateChange?.('connected');
+          return () => {
+            currentState = 'disconnected';
+            onStateChange?.('disconnected');
+          };
+        },
+        getConnectionState(): ConnState {
+          return currentState;
+        },
+        reconnect() {
+          currentState = 'connected';
+        },
+      };
+
+      const engine = createEngine({ transport: realtimeTransport });
+      const state = engine.getState();
+
+      expect(state.transportMode).toBe('realtime');
+    });
   });
 
   describe('start/stop lifecycle', () => {
@@ -171,6 +205,70 @@ describe('SyncEngine', () => {
       expect(connectCount).toBe(2);
     });
 
+    it('should run a catch-up sync after realtime reconnect', async () => {
+      type ConnState = 'disconnected' | 'connecting' | 'connected';
+
+      let currentState: ConnState = 'disconnected';
+      let currentStateCallback: ((state: ConnState) => void) | null = null;
+      let pullCount = 0;
+
+      const base = createMockTransport({
+        onPull: () => {
+          pullCount += 1;
+        },
+      });
+
+      const realtimeTransport = {
+        ...base,
+        connect(
+          _args: { clientId: string },
+          _onEvent: (_event: unknown) => void,
+          onStateChange?: (state: ConnState) => void
+        ) {
+          currentStateCallback = onStateChange ?? null;
+          currentState = 'connecting';
+          currentStateCallback?.('connecting');
+          queueMicrotask(() => {
+            currentState = 'connected';
+            currentStateCallback?.('connected');
+          });
+          return () => {
+            currentState = 'disconnected';
+            currentStateCallback?.('disconnected');
+          };
+        },
+        getConnectionState(): ConnState {
+          return currentState;
+        },
+        reconnect() {
+          currentState = 'connecting';
+          currentStateCallback?.('connecting');
+          queueMicrotask(() => {
+            currentState = 'connected';
+            currentStateCallback?.('connected');
+          });
+        },
+      };
+
+      const engine = createEngine({
+        transport: realtimeTransport,
+        realtimeEnabled: true,
+      });
+      await engine.start();
+      await waitFor(
+        () => engine.getState().connectionState === 'connected',
+        500
+      );
+
+      pullCount = 0;
+
+      engine.disconnect();
+      engine.reconnect();
+
+      await waitFor(() => pullCount >= 2, 2_000);
+      expect(pullCount).toBeGreaterThanOrEqual(2);
+    });
+
     it('should stop and disconnect', async () => {
       const engine = createEngine();
       await engine.start();
@@ -228,7 +326,7 @@ describe('SyncEngine', () => {
 
     it('should emit sync:error on failure', async () => {
       const transport = createMockTransport();
-      transport.pull = async () => {
+      transport.sync = async () => {
         throw new Error('Network error');
       };
 
@@ -277,37 +375,258 @@ describe('SyncEngine', () => {
       expect(pullCount).toBe(2);
     });
 
-    it('should flush outbox commits enqueued during pull via queued sync', async () => {
-      let enableInjection = false;
-      let injected = false;
-      const transport = createMockTransport({
-        onPull: () => {},
+    it('should preserve first pull round commits when additional rounds run', async () => {
+      const handlers = createMockHandlerRegistry();
+      handlers.register({
+        table: 'sync_outbox_commits',
+        applySnapshot: async () => {},
+        clearAll: async () => {},
+        applyChange: async () => {},
       });
 
-      // Delay pull so we can enqueue a new commit after push finished.
-      transport.pull = async (_request) => {
-        if (enableInjection && !injected) {
-          injected = true;
-          await enqueueOutboxCommit(db, {
-            operations: [
+      let pullCallCount = 0;
+      const transport = createMockTransport();
+      transport.sync = async (request) => {
+        const result: {
+          ok: true;
+          pull?: { ok: true; subscriptions: SyncPullSubscriptionResponse[] };
+        } = { ok: true };
+
+        if (!request.pull) {
+          return result;
+        }
+
+        pullCallCount += 1;
+
+        if (pullCallCount === 2) {
+          result.pull = {
+            ok: true,
+            subscriptions: [
               {
-                table: 'tasks',
-                row_id: 'late-commit',
-                op: 'upsert',
-                payload: { title: 'Late' },
-                base_version: null,
+                id: 'sub-1',
+                status: 'active',
+                scopes: {},
+                bootstrap: false,
+                nextCursor: 1,
+                commits: [
+                  {
+                    commitSeq: 1,
+                    createdAt: new Date(1).toISOString(),
+                    actorId: 'peer',
+                    changes: [
+                      {
+                        table: 'sync_outbox_commits',
+                        row_id: 'peer-row',
+                        op: 'upsert',
+                        row_json: { id: 'peer-row' },
+                        row_version: 1,
+                        scopes: {},
+                      },
+                    ],
+                  },
+                ],
+                snapshots: [],
               },
             ],
+          };
+        } else {
+          result.pull = {
+            ok: true,
+            subscriptions: [
+              {
+                id: 'sub-1',
+                status: 'active',
+                scopes: {},
+                bootstrap: false,
+                nextCursor: pullCallCount >= 2 ? 1 : -1,
+                commits: [],
+                snapshots: [],
+              },
+            ],
+          };
+        }
+
+        return result;
+      };
+
+      const engine = createEngine({
+        transport,
+        handlers,
+        subscriptions: [
+          {
+            id: 'sub-1',
+            table: 'sync_outbox_commits',
+            scopes: {},
+            params: {},
+          },
+        ],
+      });
+
+      await engine.start();
+
+      const result = await engine.sync();
+      expect(result.success).toBe(true);
+      expect(result.pullRounds).toBe(2);
+      expect(result.pullResponse.subscriptions).toHaveLength(1);
+      expect(result.pullResponse.subscriptions[0]?.commits).toHaveLength(1);
+      expect(
+        result.pullResponse.subscriptions[0]?.commits[0]?.changes
+      ).toHaveLength(1);
+    });
+
+    it('should use WS push for the first outbox commit when available', async () => {
+      const base = createMockTransport();
+      const syncRequests: Array<{ hasPush: boolean; hasPull: boolean }> = [];
+      let wsPushCount = 0;
+
+      const transport = {
+        ...base,
+        async sync(request: Parameters<typeof base.sync>[0]) {
+          syncRequests.push({
+            hasPush: request.push !== undefined,
+            hasPull: request.pull !== undefined,
           });
+          return base.sync(request);
+        },
+        async pushViaWs(request: {
+          clientId: string;
+          clientCommitId: string;
+          operations: Array<{ op: 'upsert' | 'delete' }>;
+          schemaVersion: number;
+        }) {
+          wsPushCount += 1;
+          return {
+            ok: true as const,
+            status: 'applied' as const,
+            commitSeq: 101,
+            results: request.operations.map((_, i) => ({
+              opIndex: i,
+              status: 'applied' as const,
+            })),
+          };
+        },
+      };
 
-          // Request another sync while this pull is in-flight.
-          void engine.sync();
-        }
+      const engine = createEngine({ transport });
+      await engine.start();
+
+      syncRequests.length = 0;
+      wsPushCount = 0;
+
+      await enqueueOutboxCommit(db, {
+        operations: [
+          {
+            table: 'tasks',
+            row_id: 'ws-first',
+            op: 'upsert',
+            payload: { title: 'WS first' },
+            base_version: null,
+          },
+        ],
+      });
+
+      const result = await engine.sync();
+      expect(result.success).toBe(true);
+      expect(wsPushCount).toBe(1);
+      expect(syncRequests.some((r) => r.hasPull)).toBe(true);
+      expect(syncRequests.some((r) => r.hasPush)).toBe(false);
+
+      const rows = await db
+        .selectFrom('sync_outbox_commits')
+        .select(['status', 'acked_commit_seq'])
+        .execute();
+
+      expect(rows).toHaveLength(1);
+      expect(rows[0]?.status).toBe('acked');
+      expect(rows[0]?.acked_commit_seq).toBe(101);
+    });
 
-        // Small delay so the second sync request is definitely concurrent.
-        await new Promise((r) => setTimeout(r, 10));
+    it('should fall back to HTTP push when WS push returns null', async () => {
+      let httpPushCount = 0;
+      const base = createMockTransport({
+        onPush: () => {
+          httpPushCount += 1;
+        },
+      });
+      const syncRequests: Array<{ hasPush: boolean; hasPull: boolean }> = [];
+      let wsPushCount = 0;
 
-        return { ok: true, subscriptions: [] };
+      const transport = {
+        ...base,
+        async sync(request: Parameters<typeof base.sync>[0]) {
+          syncRequests.push({
+            hasPush: request.push !== undefined,
+            hasPull: request.pull !== undefined,
+          });
+          return base.sync(request);
+        },
+        async pushViaWs() {
+          wsPushCount += 1;
+          return null;
+        },
+      };
+
+      const engine = createEngine({ transport });
+      await engine.start();
+
+      syncRequests.length = 0;
+      wsPushCount = 0;
+      httpPushCount = 0;
+
+      await enqueueOutboxCommit(db, {
+        operations: [
+          {
+            table: 'tasks',
+            row_id: 'http-fallback',
+            op: 'upsert',
+            payload: { title: 'HTTP fallback' },
+            base_version: null,
+          },
+        ],
+      });
+
+      const result = await engine.sync();
+      expect(result.success).toBe(true);
+      expect(wsPushCount).toBe(1);
+      expect(httpPushCount).toBe(1);
+      expect(syncRequests.some((r) => r.hasPull)).toBe(true);
+      expect(syncRequests.some((r) => r.hasPush)).toBe(true);
+    });
+
+    it('should flush outbox commits enqueued during pull via queued sync', async () => {
+      let enableInjection = false;
+      let injected = false;
+      const transport = createMockTransport({
+        onPull: () => {},
+      });
+
+      // Delay pull part of sync so we can enqueue a new commit after push finished.
+      const originalSync = transport.sync.bind(transport);
+      transport.sync = async (request) => {
+        if (request.pull) {
+          if (enableInjection && !injected) {
+            injected = true;
+            await enqueueOutboxCommit(db, {
+              operations: [
+                {
+                  table: 'tasks',
+                  row_id: 'late-commit',
+                  op: 'upsert',
+                  payload: { title: 'Late' },
+                  base_version: null,
+                },
+              ],
+            });
+
+            // Request another sync while this pull is in-flight.
+            void engine.sync();
+          }
+
+          // Small delay so the second sync request is definitely concurrent.
+          await new Promise((r) => setTimeout(r, 10));
+        }
+
+        return originalSync(request);
       };
 
       const engine = createEngine({ transport });
@@ -444,7 +763,7 @@ describe('SyncEngine', () => {
       const initialPullCount = pullCount;
 
       engine.updateSubscriptions([
-        { id: 'new-sub', shape: 'test', scopes: {} },
+        { id: 'new-sub', table: 'test', scopes: {} },
       ]);
 
       await flushPromises();
@@ -474,15 +793,15 @@ describe('SyncEngine', () => {
     async function createTestEngine(
       args: { includeProjects?: boolean } = {}
     ): Promise<SyncEngine<TestDb>> {
-      const shapes = new ClientTableRegistry<TestDb>();
-      shapes.register({
+      const handlers = new ClientTableRegistry<TestDb>();
+      handlers.register({
         table: 'tasks',
         applySnapshot: async () => {},
         clearAll: async () => {},
         applyChange: async () => {},
       });
       if (args.includeProjects) {
-        shapes.register({
+        handlers.register({
           table: 'projects',
           applySnapshot: async () => {},
           clearAll: async () => {},
@@ -494,7 +813,7 @@ describe('SyncEngine', () => {
       const config: SyncEngineConfig<TestDb> = {
         db: testDb,
         transport: createMockTransport(),
-        shapes,
+        handlers,
         actorId: 'test-actor',
         clientId: 'test-client',
         subscriptions: [],
@@ -650,4 +969,364 @@ describe('SyncEngine', () => {
       expect(dataChangeEvent.timestamp).toBeGreaterThan(0);
     });
   });
+
+  describe('WS delivery skip-HTTP', () => {
+    type ConnState = 'disconnected' | 'connecting' | 'connected';
+
+    function createRealtimeTransport(
+      baseTransport: ReturnType<typeof createMockTransport>
+    ) {
+      let onEventCb:
+        | ((event: {
+            event: string;
+            data: { cursor?: number; changes?: unknown[]; timestamp: number };
+          }) => void)
+        | null = null;
+      let onStateCb: ((state: ConnState) => void) | null = null;
+
+      const rt = {
+        ...baseTransport,
+        connect(
+          _args: { clientId: string },
+          onEvent: typeof onEventCb,
+          onStateChange?: typeof onStateCb
+        ) {
+          onEventCb = onEvent;
+          onStateCb = onStateChange ?? null;
+          queueMicrotask(() => onStateCb?.('connected'));
+          return () => {};
+        },
+        getConnectionState(): ConnState {
+          return 'connected';
+        },
+        reconnect() {},
+        // Helpers for tests
+        simulateSyncEvent(data: {
+          cursor?: number;
+          changes?: unknown[];
+          timestamp?: number;
+        }) {
+          onEventCb?.({
+            event: 'sync',
+            data: { timestamp: Date.now(), ...data },
+          });
+        },
+      };
+      return rt;
+    }
+
+    it('should skip HTTP sync when WS delivers changes with cursor', async () => {
+      let syncCallCount = 0;
+      const base = createMockTransport({
+        onPull: () => {
+          syncCallCount++;
+        },
+      });
+      const rt = createRealtimeTransport(base);
+
+      const handlers = new ClientTableRegistry();
+      handlers.register({
+        table: 'tasks',
+        applySnapshot: async () => {},
+        clearAll: async () => {},
+        applyChange: async () => {},
+      });
+
+      const engine = createEngine({
+        transport: rt,
+        handlers,
+        realtimeEnabled: true,
+      });
+      await engine.start();
+      await waitFor(
+        () => engine.getState().connectionState === 'connected',
+        500
+      );
+
+      // Reset after initial sync
+      syncCallCount = 0;
+
+      let syncCompleteCount = 0;
+      engine.on('sync:complete', () => {
+        syncCompleteCount++;
+      });
+
+      // Simulate WS delivering inline changes with cursor
+      rt.simulateSyncEvent({
+        cursor: 100,
+        changes: [
+          {
+            table: 'tasks',
+            row_id: 'task-1',
+            op: 'upsert',
+            row_json: { id: 'task-1', title: 'Hello' },
+            row_version: 1,
+            scopes: {},
+          },
+        ],
+      });
+
+      // Wait for handleWsDelivery to complete
+      await flushPromises();
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Should NOT have called transport.sync (HTTP pull)
+      expect(syncCallCount).toBe(0);
+      // Should have emitted sync:complete
+      expect(syncCompleteCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should fall back to HTTP sync when no cursor in WS event', async () => {
+      let syncCallCount = 0;
+      const base = createMockTransport({
+        onPull: () => {
+          syncCallCount++;
+        },
+      });
+      const rt = createRealtimeTransport(base);
+
+      const engine = createEngine({
+        transport: rt,
+        realtimeEnabled: true,
+      });
+      await engine.start();
+      await waitFor(
+        () => engine.getState().connectionState === 'connected',
+        500
+      );
+
+      syncCallCount = 0;
+
+      // Simulate WS event with changes but no cursor
+      rt.simulateSyncEvent({
+        changes: [
+          {
+            table: 'tasks',
+            row_id: 'task-1',
+            op: 'upsert',
+            row_json: {},
+            row_version: 1,
+            scopes: {},
+          },
+        ],
+      });
+
+      await flushPromises();
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Should fall back to HTTP
+      expect(syncCallCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should fall back to HTTP sync when no changes in WS event (cursor-only)', async () => {
+      let syncCallCount = 0;
+      const base = createMockTransport({
+        onPull: () => {
+          syncCallCount++;
+        },
+      });
+      const rt = createRealtimeTransport(base);
+
+      const engine = createEngine({
+        transport: rt,
+        realtimeEnabled: true,
+      });
+      await engine.start();
+      await waitFor(
+        () => engine.getState().connectionState === 'connected',
+        500
+      );
+
+      syncCallCount = 0;
+
+      // Simulate cursor-only WS event (no inline changes)
+      rt.simulateSyncEvent({ cursor: 100 });
+
+      await flushPromises();
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Should fall back to HTTP
+      expect(syncCallCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should fall back to HTTP sync when outbox has pending commits', async () => {
+      let syncCallCount = 0;
+      const base = createMockTransport({
+        onPull: () => {
+          syncCallCount++;
+        },
+      });
+      const rt = createRealtimeTransport(base);
+
+      const handlers = new ClientTableRegistry();
+      handlers.register({
+        table: 'tasks',
+        applySnapshot: async () => {},
+        clearAll: async () => {},
+        applyChange: async () => {},
+      });
+
+      const engine = createEngine({
+        transport: rt,
+        handlers,
+        realtimeEnabled: true,
+      });
+      await engine.start();
+      await waitFor(
+        () => engine.getState().connectionState === 'connected',
+        500
+      );
+
+      // Enqueue a commit to create pending outbox state
+      await enqueueOutboxCommit(db, {
+        operations: [
+          {
+            table: 'tasks',
+            row_id: 'task-1',
+            op: 'upsert',
+            payload: { title: 'Test' },
+            base_version: null,
+          },
+        ],
+      });
+      await engine.refreshOutboxStats();
+
+      syncCallCount = 0;
+
+      // Simulate WS with inline changes
+      rt.simulateSyncEvent({
+        cursor: 100,
+        changes: [
+          {
+            table: 'tasks',
+            row_id: 'task-2',
+            op: 'upsert',
+            row_json: { id: 'task-2' },
+            row_version: 1,
+            scopes: {},
+          },
+        ],
+      });
+
+      await flushPromises();
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Should fall back to HTTP to push outbox
+      expect(syncCallCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should fall back to HTTP sync when afterPull plugins exist', async () => {
+      let syncCallCount = 0;
+      let inlineApplyCount = 0;
+      const base = createMockTransport({
+        onPull: () => {
+          syncCallCount++;
+        },
+      });
+      const rt = createRealtimeTransport(base);
+
+      const handlers = new ClientTableRegistry();
+      handlers.register({
+        table: 'tasks',
+        applySnapshot: async () => {},
+        clearAll: async () => {},
+        applyChange: async () => {
+          inlineApplyCount++;
+        },
+      });
+
+      const engine = createEngine({
+        transport: rt,
+        handlers,
+        realtimeEnabled: true,
+        plugins: [
+          {
+            name: 'test-plugin',
+            async afterPull(_ctx, args) {
+              return args.response;
+            },
+          },
+        ],
+      });
+      await engine.start();
+      await waitFor(
+        () => engine.getState().connectionState === 'connected',
+        500
+      );
+
+      syncCallCount = 0;
+
+      // Simulate WS with inline changes
+      rt.simulateSyncEvent({
+        cursor: 100,
+        changes: [
+          {
+            table: 'tasks',
+            row_id: 'task-1',
+            op: 'upsert',
+            row_json: { id: 'task-1' },
+            row_version: 1,
+            scopes: {},
+          },
+        ],
+      });
+
+      await flushPromises();
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Should fall back to HTTP because afterPull plugin exists
+      expect(syncCallCount).toBeGreaterThanOrEqual(1);
+      // Should not apply inline WS payload when afterPull plugins are present.
+      expect(inlineApplyCount).toBe(0);
+    });
+
+    it('should emit data:change when WS delivery skips HTTP', async () => {
+      const base = createMockTransport();
+      const rt = createRealtimeTransport(base);
+
+      const handlers = new ClientTableRegistry();
+      handlers.register({
+        table: 'tasks',
+        applySnapshot: async () => {},
+        clearAll: async () => {},
+        applyChange: async () => {},
+      });
+
+      const engine = createEngine({
+        transport: rt,
+        handlers,
+        realtimeEnabled: true,
+      });
+      await engine.start();
+      await waitFor(
+        () => engine.getState().connectionState === 'connected',
+        500
+      );
+
+      const dataChangeScopes: string[][] = [];
+      engine.on('data:change', (payload) => {
+        dataChangeScopes.push(payload.scopes);
+      });
+
+      rt.simulateSyncEvent({
+        cursor: 100,
+        changes: [
+          {
+            table: 'tasks',
+            row_id: 'task-1',
+            op: 'upsert',
+            row_json: { id: 'task-1' },
+            row_version: 1,
+            scopes: {},
+          },
+        ],
+      });
+
+      await flushPromises();
+      await new Promise((r) => setTimeout(r, 50));
+
+      // Should have emitted data:change with 'tasks'
+      expect(dataChangeScopes.some((s) => s.includes('tasks'))).toBe(true);
+    });
+  });
 });