@syncular/client-react 0.0.1

package/src/__tests__/integration/provider-reconfig.test.ts

@@ -0,0 +1,291 @@
+/**
+ * Integration tests for SyncProvider reconfiguration
+ *
+ * Tests that verify the SyncProvider correctly handles changes to critical props.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import {
+  ClientTableRegistry,
+  ensureClientSyncSchema,
+  type SyncClientDb,
+  SyncEngine,
+} from '@syncular/client';
+import { createBunSqliteDb } from '@syncular/dialect-bun-sqlite';
+import { cleanup, render } from '@testing-library/react';
+import type { Kysely } from 'kysely';
+import { createElement } from 'react';
+import { createSyncularReact } from '../../index';
+import {
+  createTestServer,
+  destroyTestServer,
+  type TestServer,
+} from './test-setup';
+import '../setup'; // Ensure happy-dom is registered
+
+/**
+ * Client database schema for tests
+ */
+interface ClientDb extends SyncClientDb {
+  tasks: {
+    id: string;
+    title: string;
+    completed: number;
+    user_id: string;
+    server_version: number;
+  };
+}
+
+const { SyncProvider } = createSyncularReact<ClientDb>();
+
+// Create a mock ClientTableRegistry for tests
+function createMockClientTableRegistry(): ClientTableRegistry<ClientDb> {
+  return new ClientTableRegistry<ClientDb>();
+}
+
+describe('SyncProvider Reconfiguration', () => {
+  let server: TestServer;
+  let db: Kysely<ClientDb>;
+  let mockShapes: ClientTableRegistry<ClientDb>;
+
+  beforeEach(async () => {
+    server = await createTestServer();
+    db = createBunSqliteDb<ClientDb>({ path: ':memory:' });
+    mockShapes = createMockClientTableRegistry();
+
+    await ensureClientSyncSchema(db);
+
+    // Create tasks table
+    await db.schema
+      .createTable('tasks')
+      .ifNotExists()
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('title', 'text', (col) => col.notNull())
+      .addColumn('completed', 'integer', (col) => col.notNull().defaultTo(0))
+      .addColumn('user_id', 'text', (col) => col.notNull())
+      .addColumn('server_version', 'integer', (col) =>
+        col.notNull().defaultTo(0)
+      )
+      .execute();
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+    await destroyTestServer(server);
+  });
+
+  it('SyncEngine recreates when actorId changes', async () => {
+    // Create a simple transport for testing
+    const transport = {
+      async pull() {
+        return {
+          ok: true as const,
+          subscriptions: [],
+        };
+      },
+      async push() {
+        return { ok: true as const, status: 'applied' as const, results: [] };
+      },
+      async fetchSnapshotChunk() {
+        return new Uint8Array();
+      },
+    };
+
+    // Create first engine with actorId 'user-1'
+    const engine1 = new SyncEngine({
+      db,
+      transport,
+      shapes: mockShapes,
+      actorId: 'user-1',
+      clientId: 'client-1',
+      subscriptions: [],
+      pollIntervalMs: 999999,
+      realtimeEnabled: false,
+    });
+
+    // Verify engine has correct actorId
+    expect(engine1.getActorId()).toBe('user-1');
+
+    // Create second engine with different actorId
+    const engine2 = new SyncEngine({
+      db,
+      transport,
+      shapes: mockShapes,
+      actorId: 'user-2',
+      clientId: 'client-1',
+      subscriptions: [],
+      pollIntervalMs: 999999,
+      realtimeEnabled: false,
+    });
+
+    // Verify new engine has different actorId
+    expect(engine2.getActorId()).toBe('user-2');
+
+    // Engines should be different instances
+    expect(engine1).not.toBe(engine2);
+
+    // Cleanup
+    engine1.destroy();
+    engine2.destroy();
+  });
+
+  it('error message format for prop changes is correct', () => {
+    // Tests that the error message format is correct for prop changes
+    // In dev mode, SyncProvider throws an error when critical props change
+    // In production, it logs an error
+
+    const initialProps = {
+      actorId: 'user-1',
+      clientId: 'client-1',
+    };
+
+    const newActorId = 'user-2';
+    const changedProps: string[] = [];
+
+    if (newActorId !== initialProps.actorId) changedProps.push('actorId');
+
+    // Verify message construction
+    expect(changedProps.length).toBe(1);
+    expect(changedProps[0]).toBe('actorId');
+
+    const message =
+      `[SyncProvider] Critical props changed after mount: ${changedProps.join(', ')}. ` +
+      'This is not supported. Use a React key prop to force remount, e.g., ' +
+      '<SyncProvider key={actorId} ...>';
+
+    expect(message).toContain(
+      '[SyncProvider] Critical props changed after mount'
+    );
+    expect(message).toContain('actorId');
+    expect(message).toContain('This is not supported');
+    expect(message).toContain('<SyncProvider key={actorId} ...>');
+  });
+
+  it('engine config is immutable after creation', () => {
+    const transport = {
+      async pull() {
+        return { ok: true as const, subscriptions: [] };
+      },
+      async push() {
+        return { ok: true as const, status: 'applied' as const, results: [] };
+      },
+      async fetchSnapshotChunk() {
+        return new Uint8Array();
+      },
+    };
+
+    const engine = new SyncEngine({
+      db,
+      transport,
+      shapes: mockShapes,
+      actorId: 'user-1',
+      clientId: 'client-1',
+      subscriptions: [],
+      pollIntervalMs: 999999,
+      realtimeEnabled: false,
+    });
+
+    const originalActorId = engine.getActorId();
+    expect(originalActorId).toBe('user-1');
+
+    // Engine should maintain its original config
+    expect(engine.getActorId()).toBe('user-1');
+
+    engine.destroy();
+  });
+});
+
+describe('SyncProvider React render tests', () => {
+  let db: Kysely<ClientDb>;
+  let mockShapes: ClientTableRegistry<ClientDb>;
+  const mockTransport = {
+    async pull() {
+      return { ok: true as const, subscriptions: [] };
+    },
+    async push() {
+      return { ok: true as const, status: 'applied' as const, results: [] };
+    },
+    async fetchSnapshotChunk() {
+      return new Uint8Array();
+    },
+  };
+
+  beforeEach(async () => {
+    db = createBunSqliteDb<ClientDb>({ path: ':memory:' });
+    mockShapes = new ClientTableRegistry<ClientDb>();
+    await ensureClientSyncSchema(db);
+  });
+
+  afterEach(async () => {
+    cleanup();
+    await db.destroy();
+  });
+
+  it('warns when critical props change after mount', () => {
+    const child = createElement('div', null, 'Test Child');
+
+    // Render with initial props
+    const { rerender } = render(
+      createElement(SyncProvider, {
+        db,
+        transport: mockTransport,
+        shapes: mockShapes,
+        actorId: 'user-1',
+        clientId: 'client-1',
+        autoStart: false, // Disable auto-start for faster test
+        // biome-ignore lint/correctness/noChildrenProp: createElement requires children prop
+        children: child,
+      })
+    );
+
+    // Re-render with changed actorId should warn but not throw
+    expect(() => {
+      rerender(
+        createElement(SyncProvider, {
+          db,
+          transport: mockTransport,
+          shapes: mockShapes,
+          actorId: 'user-2', // Changed!
+          clientId: 'client-1',
+          autoStart: false,
+          // biome-ignore lint/correctness/noChildrenProp: createElement requires children prop
+          children: child,
+        })
+      );
+    }).not.toThrow();
+  });
+
+  it('does not throw when non-critical props change', () => {
+    const child = createElement('div', null, 'Test Child');
+    const { rerender } = render(
+      createElement(SyncProvider, {
+        db,
+        transport: mockTransport,
+        shapes: mockShapes,
+        actorId: 'user-1',
+        clientId: 'client-1',
+        autoStart: false,
+        pollIntervalMs: 1000,
+        // biome-ignore lint/correctness/noChildrenProp: createElement requires children prop
+        children: child,
+      })
+    );
+
+    // Re-render with changed pollIntervalMs should not throw
+    expect(() => {
+      rerender(
+        createElement(SyncProvider, {
+          db,
+          transport: mockTransport,
+          shapes: mockShapes,
+          actorId: 'user-1',
+          clientId: 'client-1',
+          autoStart: false,
+          pollIntervalMs: 5000, // Changed non-critical prop
+          // biome-ignore lint/correctness/noChildrenProp: createElement requires children prop
+          children: child,
+        })
+      );
+    }).not.toThrow();
+  });
+});

package/src/__tests__/integration/push-flow.test.ts

@@ -0,0 +1,320 @@
+/**
+ * Integration tests for push flow
+ *
+ * Tests that verify the full push flow from mutation to server.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import {
+  enqueueOutboxCommit,
+  getNextSendableOutboxCommit,
+} from '@syncular/client';
+import type { SyncPushRequest, SyncPushResponse } from '@syncular/core';
+import {
+  createTestClient,
+  createTestServer,
+  destroyTestClient,
+  destroyTestServer,
+  type TestClient,
+  type TestServer,
+} from './test-setup';
+
+describe('Push Flow', () => {
+  let server: TestServer;
+  let client: TestClient;
+
+  const userId = 'test-user';
+
+  beforeEach(async () => {
+    server = await createTestServer();
+    client = await createTestClient(server, {
+      actorId: userId,
+      clientId: 'test-client',
+    });
+    await client.engine.start();
+  });
+
+  afterEach(async () => {
+    await destroyTestClient(client);
+    await destroyTestServer(server);
+  });
+
+  it('enqueue creates outbox commit with pending status', async () => {
+    // Enqueue a commit
+    const result = await enqueueOutboxCommit(client.db, {
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'task-1',
+          op: 'upsert',
+          payload: { title: 'Test Task', completed: 0, user_id: userId },
+          base_version: null,
+        },
+      ],
+    });
+
+    expect(result.id).toBeTruthy();
+    expect(result.clientCommitId).toBeTruthy();
+
+    // Verify the commit is in the outbox
+    // Note: getNextSendableOutboxCommit atomically claims the commit, so it returns with 'sending' status
+    const nextCommit = await getNextSendableOutboxCommit(client.db);
+    expect(nextCommit).not.toBeNull();
+    expect(nextCommit!.status).toBe('sending');
+    expect(nextCommit!.operations.length).toBe(1);
+  });
+
+  it('sync pushes outbox commits to server', async () => {
+    // Enqueue a commit
+    await enqueueOutboxCommit(client.db, {
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'push-task-1',
+          op: 'upsert',
+          payload: { title: 'Pushed Task', completed: 0, user_id: userId },
+          base_version: null,
+        },
+      ],
+    });
+
+    // Before sync, verify commit exists with pending status (using direct query to avoid claiming)
+    const pendingCommit = await client.db
+      .selectFrom('sync_outbox_commits')
+      .selectAll()
+      .where('status', '=', 'pending')
+      .executeTakeFirst();
+    expect(pendingCommit).not.toBeNull();
+
+    // Sync
+    const result = await client.engine.sync();
+    expect(result.success).toBe(true);
+    expect(result.pushedCommits).toBe(1);
+
+    // After sync, outbox should be empty (commit acked)
+    const remainingCommit = await getNextSendableOutboxCommit(client.db);
+    expect(remainingCommit).toBeNull();
+
+    // Verify task is on server
+    const serverTasks = await server.db
+      .selectFrom('tasks')
+      .where('id', '=', 'push-task-1')
+      .selectAll()
+      .execute();
+
+    expect(serverTasks.length).toBe(1);
+    expect(serverTasks[0]!.title).toBe('Pushed Task');
+    expect(serverTasks[0]!.server_version).toBe(1);
+  });
+
+  it('sync updates local row with server version after push', async () => {
+    // First, apply the mutation locally (this is what useMutation does)
+    const shapes = client.shapes;
+    const handler = shapes.get('tasks');
+
+    await client.db.transaction().execute(async (trx) => {
+      await handler!.applyChange(
+        { trx },
+        {
+          table: 'tasks',
+          row_id: 'version-test',
+          op: 'upsert',
+          row_json: { title: 'Local Task', completed: 0, user_id: userId },
+          row_version: null, // Local optimistic - no server version yet
+          scopes: { user_id: userId },
+        }
+      );
+    });
+
+    // Verify local row has version 0
+    let localRow = await client.db
+      .selectFrom('tasks')
+      .where('id', '=', 'version-test')
+      .selectAll()
+      .executeTakeFirst();
+    expect(localRow).toBeTruthy();
+    expect(localRow!.server_version).toBe(0);
+
+    // Enqueue the commit
+    await enqueueOutboxCommit(client.db, {
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'version-test',
+          op: 'upsert',
+          payload: { title: 'Local Task', completed: 0, user_id: userId },
+          base_version: null,
+        },
+      ],
+    });
+
+    // Sync (push + pull)
+    await client.engine.sync();
+
+    // After sync, local row should have server version
+    localRow = await client.db
+      .selectFrom('tasks')
+      .where('id', '=', 'version-test')
+      .selectAll()
+      .executeTakeFirst();
+    expect(localRow).toBeTruthy();
+    expect(localRow!.server_version).toBe(1);
+  });
+
+  it('multiple syncs push multiple commits', async () => {
+    // Enqueue first commit
+    await enqueueOutboxCommit(client.db, {
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'multi-1',
+          op: 'upsert',
+          payload: { title: 'Task 1', completed: 0, user_id: userId },
+          base_version: null,
+        },
+      ],
+    });
+
+    // First sync
+    let result = await client.engine.sync();
+    expect(result.pushedCommits).toBe(1);
+
+    // Enqueue second commit
+    await enqueueOutboxCommit(client.db, {
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'multi-2',
+          op: 'upsert',
+          payload: { title: 'Task 2', completed: 0, user_id: userId },
+          base_version: null,
+        },
+      ],
+    });
+
+    // Second sync
+    result = await client.engine.sync();
+    expect(result.pushedCommits).toBe(1);
+
+    // Verify both on server
+    const serverTasks = await server.db
+      .selectFrom('tasks')
+      .where('user_id', '=', userId)
+      .selectAll()
+      .execute();
+
+    expect(serverTasks.length).toBe(2);
+  });
+
+  it('outbox stats reflect pending commits', async () => {
+    // Initially no pending
+    let stats = await client.engine.refreshOutboxStats();
+    expect(stats.pending).toBe(0);
+
+    // Enqueue a commit
+    await enqueueOutboxCommit(client.db, {
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'stats-test',
+          op: 'upsert',
+          payload: { title: 'Stats Task', completed: 0, user_id: userId },
+          base_version: null,
+        },
+      ],
+    });
+
+    // Should show 1 pending
+    stats = await client.engine.refreshOutboxStats();
+    expect(stats.pending).toBe(1);
+
+    // Sync
+    await client.engine.sync();
+
+    // Should show 0 pending
+    stats = await client.engine.refreshOutboxStats();
+    expect(stats.pending).toBe(0);
+  });
+
+  it('keeps commit pending when server returns retriable error', async () => {
+    // Create a client with a transport that returns retriable errors
+    const retriableClient = await createTestClient(server, {
+      actorId: userId,
+      clientId: 'retriable-client',
+    });
+
+    // Override the transport to return retriable errors
+    const originalPush = retriableClient.transport.push.bind(
+      retriableClient.transport
+    );
+    let retriableErrorCount = 0;
+    retriableClient.transport.push = async (
+      request: SyncPushRequest
+    ): Promise<SyncPushResponse> => {
+      if (retriableErrorCount < 2) {
+        // Return retriable error for first two attempts
+        retriableErrorCount++;
+        return {
+          ok: true as const,
+          status: 'rejected' as const,
+          results: request.operations.map((_, i) => ({
+            opIndex: i,
+            status: 'error' as const,
+            error: 'TEMPORARY_FAILURE',
+            code: 'TEMPORARY',
+            retriable: true,
+          })),
+        };
+      }
+      // After that, use the real transport
+      return originalPush(request);
+    };
+
+    await retriableClient.engine.start();
+
+    try {
+      // Enqueue a commit
+      await enqueueOutboxCommit(retriableClient.db, {
+        operations: [
+          {
+            table: 'tasks',
+            row_id: 'retriable-task',
+            op: 'upsert',
+            payload: { title: 'Retriable Task', completed: 0, user_id: userId },
+            base_version: null,
+          },
+        ],
+      });
+
+      // Verify commit is pending before sync
+      let stats = await retriableClient.engine.refreshOutboxStats();
+      expect(stats.pending).toBe(1);
+      expect(stats.failed).toBe(0);
+
+      // First sync - will hit retriable error but commit stays pending (not failed)
+      await retriableClient.engine.sync();
+
+      // Commit should still be pending (not failed) after retriable error
+      stats = await retriableClient.engine.refreshOutboxStats();
+      expect(stats.failed).toBe(0);
+      // Commit may still be pending since it wasn't terminal failure
+      // Note: pushedCommits counts attempts, which may be > 0
+
+      // After enough retries, the commit should eventually succeed
+      // Keep syncing until successful or we've tried enough times
+      for (let i = 0; i < 5 && stats.pending > 0; i++) {
+        await retriableClient.engine.sync();
+        stats = await retriableClient.engine.refreshOutboxStats();
+      }
+
+      // Now should be empty (commit succeeded) and no failures
+      expect(stats.pending).toBe(0);
+      expect(stats.failed).toBe(0);
+
+      // Verify the retriable error was actually returned (at least twice before success)
+      expect(retriableErrorCount).toBe(2);
+    } finally {
+      await destroyTestClient(retriableClient);
+    }
+  });
+});