@syncular/client-react 0.0.4-26 → 0.0.6-100

package/src/__tests__/SyncEngine.test.ts

@@ -4,7 +4,6 @@
 
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import {
-  ClientTableRegistry,
   enqueueOutboxCommit,
   type SyncClientDb,
   SyncEngine,
@@ -377,7 +376,7 @@ describe('SyncEngine', () => {
 
     it('should preserve first pull round commits when additional rounds run', async () => {
       const handlers = createMockHandlerRegistry();
-      handlers.register({
+      handlers.push({
         table: 'sync_outbox_commits',
         applySnapshot: async () => {},
         clearAll: async () => {},
@@ -857,15 +856,16 @@ describe('SyncEngine', () => {
     async function createTestEngine(
       args: { includeProjects?: boolean } = {}
     ): Promise<SyncEngine<TestDb>> {
-      const handlers = new ClientTableRegistry<TestDb>();
-      handlers.register({
-        table: 'tasks',
-        applySnapshot: async () => {},
-        clearAll: async () => {},
-        applyChange: async () => {},
-      });
+      const handlers: SyncEngineConfig<TestDb>['handlers'] = [
+        {
+          table: 'tasks',
+          applySnapshot: async () => {},
+          clearAll: async () => {},
+          applyChange: async () => {},
+        },
+      ];
       if (args.includeProjects) {
-        handlers.register({
+        handlers.push({
           table: 'projects',
           applySnapshot: async () => {},
           clearAll: async () => {},
@@ -1088,13 +1088,14 @@ describe('SyncEngine', () => {
       });
       const rt = createRealtimeTransport(base);
 
-      const handlers = new ClientTableRegistry();
-      handlers.register({
-        table: 'tasks',
-        applySnapshot: async () => {},
-        clearAll: async () => {},
-        applyChange: async () => {},
-      });
+      const handlers: SyncEngineConfig<SyncClientDb>['handlers'] = [
+        {
+          table: 'tasks',
+          applySnapshot: async () => {},
+          clearAll: async () => {},
+          applyChange: async () => {},
+        },
+      ];
 
       const engine = createEngine({
         transport: rt,
@@ -1222,13 +1223,14 @@ describe('SyncEngine', () => {
       });
       const rt = createRealtimeTransport(base);
 
-      const handlers = new ClientTableRegistry();
-      handlers.register({
-        table: 'tasks',
-        applySnapshot: async () => {},
-        clearAll: async () => {},
-        applyChange: async () => {},
-      });
+      const handlers: SyncEngineConfig<SyncClientDb>['handlers'] = [
+        {
+          table: 'tasks',
+          applySnapshot: async () => {},
+          clearAll: async () => {},
+          applyChange: async () => {},
+        },
+      ];
 
       const engine = createEngine({
         transport: rt,
@@ -1289,15 +1291,16 @@ describe('SyncEngine', () => {
       });
       const rt = createRealtimeTransport(base);
 
-      const handlers = new ClientTableRegistry();
-      handlers.register({
-        table: 'tasks',
-        applySnapshot: async () => {},
-        clearAll: async () => {},
-        applyChange: async () => {
-          inlineApplyCount++;
+      const handlers: SyncEngineConfig<SyncClientDb>['handlers'] = [
+        {
+          table: 'tasks',
+          applySnapshot: async () => {},
+          clearAll: async () => {},
+          applyChange: async () => {
+            inlineApplyCount++;
+          },
         },
-      });
+      ];
 
       const engine = createEngine({
         transport: rt,
@@ -1348,13 +1351,14 @@ describe('SyncEngine', () => {
       const base = createMockTransport();
       const rt = createRealtimeTransport(base);
 
-      const handlers = new ClientTableRegistry();
-      handlers.register({
-        table: 'tasks',
-        applySnapshot: async () => {},
-        clearAll: async () => {},
-        applyChange: async () => {},
-      });
+      const handlers: SyncEngineConfig<SyncClientDb>['handlers'] = [
+        {
+          table: 'tasks',
+          applySnapshot: async () => {},
+          clearAll: async () => {},
+          applyChange: async () => {},
+        },
+      ];
 
       const engine = createEngine({
         transport: rt,

package/src/__tests__/SyncProvider.strictmode.test.tsx

@@ -22,6 +22,7 @@ import { createSyncularReact } from '../index';
 import {
   createMockDb,
   createMockHandlerRegistry,
+  createMockSync,
   createMockTransport,
 } from './test-utils';
 
@@ -67,16 +68,16 @@ describe('SyncProvider (StrictMode)', () => {
   function renderWithProvider(node: React.ReactNode) {
     const transport = createMockTransport();
     const handlers = createMockHandlerRegistry();
+    const sync = createMockSync({ handlers });
 
     return render(
       <React.StrictMode>
         <SyncProvider
           db={db}
           transport={transport}
-          handlers={handlers}
-          actorId="test-actor"
+          sync={sync}
+          identity={{ actorId: 'test-actor' }}
           clientId="test-client"
-          subscriptions={[]}
           pollIntervalMs={999999}
         >
           {node}

package/src/__tests__/async-init-registry.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'bun:test';
+import { createAsyncInitRegistry } from '../async-init-registry';
+
+describe('createAsyncInitRegistry', () => {
+  it('runs initializer once per key and shares the same result', async () => {
+    const registry = createAsyncInitRegistry<string, string>();
+    let runs = 0;
+
+    const first = registry.run('client-a', async () => {
+      runs += 1;
+      return 'ok';
+    });
+    const second = registry.run('client-a', async () => {
+      runs += 1;
+      return 'unexpected';
+    });
+
+    await expect(first).resolves.toBe('ok');
+    await expect(second).resolves.toBe('ok');
+    expect(runs).toBe(1);
+  });
+
+  it('evicts failed initializers so retry can succeed', async () => {
+    const registry = createAsyncInitRegistry<string, string>();
+    let runs = 0;
+
+    await expect(
+      registry.run('client-a', async () => {
+        runs += 1;
+        throw new Error('boom');
+      })
+    ).rejects.toThrow('boom');
+
+    await expect(
+      registry.run('client-a', async () => {
+        runs += 1;
+        return 'recovered';
+      })
+    ).resolves.toBe('recovered');
+
+    expect(runs).toBe(2);
+  });
+
+  it('supports explicit invalidation', async () => {
+    const registry = createAsyncInitRegistry<string, number>();
+    let seed = 0;
+
+    await expect(
+      registry.run('client-a', async () => {
+        seed += 1;
+        return seed;
+      })
+    ).resolves.toBe(1);
+
+    registry.invalidate('client-a');
+
+    await expect(
+      registry.run('client-a', async () => {
+        seed += 1;
+        return seed;
+      })
+    ).resolves.toBe(2);
+  });
+});

package/src/__tests__/hooks/useMutation.test.tsx

@@ -21,6 +21,7 @@ import { createSyncularReact } from '../../index';
 import {
   createMockDb,
   createMockHandlerRegistry,
+  createMockSync,
   createMockTransport,
 } from '../test-utils';
 
@@ -60,15 +61,15 @@ describe('useMutation', () => {
   function createWrapper() {
     const transport = createMockTransport();
     const handlers = createMockHandlerRegistry<TestDb>();
+    const sync = createMockSync<TestDb>({ handlers });
 
     const Wrapper = ({ children }: { children: ReactNode }) => (
       <SyncProvider
         db={db}
         transport={transport}
-        handlers={handlers}
-        actorId="test-actor"
+        sync={sync}
+        identity={{ actorId: 'test-actor' }}
         clientId="test-client"
-        subscriptions={[]}
         pollIntervalMs={999999}
         autoStart={false}
       >

package/src/__tests__/hooks.test.tsx

@@ -14,6 +14,7 @@ import { createSyncularReact } from '../index';
 import {
   createMockDb,
   createMockHandlerRegistry,
+  createMockSync,
   createMockTransport,
 } from './test-utils';
 
@@ -41,15 +42,15 @@ describe('React Hooks', () => {
   function createWrapper(options?: { autoStart?: boolean }) {
     const transport = createMockTransport();
     const handlers = createMockHandlerRegistry();
+    const sync = createMockSync({ handlers });
 
     const Wrapper = ({ children }: { children: ReactNode }) => (
       <SyncProvider
         db={db}
         transport={transport}
-        handlers={handlers}
-        actorId="test-actor"
+        sync={sync}
+        identity={{ actorId: 'test-actor' }}
         clientId="test-client"
-        subscriptions={[]}
         pollIntervalMs={999999} // Long poll interval to prevent continuous polling
         autoStart={options?.autoStart ?? false} // Disable auto-start for tests
       >
@@ -213,21 +214,21 @@ describe('React Hooks', () => {
     it('supports watchTables invalidation on matching data:change scopes', async () => {
       const transport = createMockTransport();
       const handlers = createMockHandlerRegistry();
-      handlers.register({
+      handlers.push({
         table: 'tasks',
         applySnapshot: async () => {},
         clearAll: async () => {},
         applyChange: async () => {},
       });
+      const sync = createMockSync({ handlers });
 
       const Wrapper = ({ children }: { children: ReactNode }) => (
         <SyncProvider
           db={db}
           transport={transport}
-          handlers={handlers}
-          actorId="test-actor"
+          sync={sync}
+          identity={{ actorId: 'test-actor' }}
           clientId="test-client"
-          subscriptions={[]}
           pollIntervalMs={999999}
           autoStart={false}
         >

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

@@ -6,12 +6,13 @@
 
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import {
-  ClientTableRegistry,
+  type ClientHandlerCollection,
   ensureClientSyncSchema,
   type SyncClientDb,
   SyncEngine,
 } from '@syncular/client';
-import { createBunSqliteDb } from '@syncular/dialect-bun-sqlite';
+import { createDatabase } from '@syncular/core';
+import { createBunSqliteDialect } from '@syncular/dialect-bun-sqlite';
 import { cleanup, render } from '@testing-library/react';
 import type { Kysely } from 'kysely';
 import { createElement } from 'react';
@@ -38,20 +39,23 @@ interface ClientDb extends SyncClientDb {
 
 const { SyncProvider } = createSyncularReact<ClientDb>();
 
-// Create a mock ClientTableRegistry for tests
-function createMockClientTableRegistry(): ClientTableRegistry<ClientDb> {
-  return new ClientTableRegistry<ClientDb>();
+// Create mock handlers for tests
+function createMockClientHandlers(): ClientHandlerCollection<ClientDb> {
+  return [];
 }
 
 describe('SyncProvider Reconfiguration', () => {
   let server: TestServer;
   let db: Kysely<ClientDb>;
-  let mockHandlers: ClientTableRegistry<ClientDb>;
+  let mockHandlers: ClientHandlerCollection<ClientDb>;
 
   beforeEach(async () => {
     server = await createTestServer();
-    db = createBunSqliteDb<ClientDb>({ path: ':memory:' });
-    mockHandlers = createMockClientTableRegistry();
+    db = createDatabase<ClientDb>({
+      dialect: createBunSqliteDialect({ path: ':memory:' }),
+      family: 'sqlite',
+    });
+    mockHandlers = createMockClientHandlers();
 
     await ensureClientSyncSchema(db);
 
@@ -145,14 +149,16 @@ describe('SyncProvider Reconfiguration', () => {
     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} ...>';
+      "<SyncProvider key={identity.actorId + ':' + clientId} ...>";
 
     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} ...>');
+    expect(message).toContain(
+      "<SyncProvider key={identity.actorId + ':' + clientId} ...>"
+    );
   });
 
   it('engine config is immutable after creation', () => {
@@ -188,7 +194,7 @@ describe('SyncProvider Reconfiguration', () => {
 
 describe('SyncProvider React render tests', () => {
   let db: Kysely<ClientDb>;
-  let mockHandlers: ClientTableRegistry<ClientDb>;
+  let mockHandlers: ClientHandlerCollection<ClientDb>;
   const mockTransport = {
     async sync() {
       return { ok: true as const };
@@ -199,8 +205,11 @@ describe('SyncProvider React render tests', () => {
   };
 
   beforeEach(async () => {
-    db = createBunSqliteDb<ClientDb>({ path: ':memory:' });
-    mockHandlers = new ClientTableRegistry<ClientDb>();
+    db = createDatabase<ClientDb>({
+      dialect: createBunSqliteDialect({ path: ':memory:' }),
+      family: 'sqlite',
+    });
+    mockHandlers = [];
     await ensureClientSyncSchema(db);
   });
 
@@ -211,14 +220,18 @@ describe('SyncProvider React render tests', () => {
 
   it('warns when critical props change after mount', () => {
     const child = createElement('div', null, 'Test Child');
+    const sync = {
+      handlers: mockHandlers,
+      subscriptions: () => [],
+    };
 
     // Render with initial props
     const { rerender } = render(
       createElement(SyncProvider, {
         db,
         transport: mockTransport,
-        handlers: mockHandlers,
-        actorId: 'user-1',
+        sync,
+        identity: { actorId: 'user-1' },
         clientId: 'client-1',
         autoStart: false, // Disable auto-start for faster test
         // biome-ignore lint/correctness/noChildrenProp: createElement requires children prop
@@ -232,8 +245,8 @@ describe('SyncProvider React render tests', () => {
         createElement(SyncProvider, {
           db,
           transport: mockTransport,
-          handlers: mockHandlers,
-          actorId: 'user-2', // Changed!
+          sync,
+          identity: { actorId: 'user-2' }, // Changed!
           clientId: 'client-1',
           autoStart: false,
           // biome-ignore lint/correctness/noChildrenProp: createElement requires children prop
@@ -245,12 +258,16 @@ describe('SyncProvider React render tests', () => {
 
   it('does not throw when non-critical props change', () => {
     const child = createElement('div', null, 'Test Child');
+    const sync = {
+      handlers: mockHandlers,
+      subscriptions: () => [],
+    };
     const { rerender } = render(
       createElement(SyncProvider, {
         db,
         transport: mockTransport,
-        handlers: mockHandlers,
-        actorId: 'user-1',
+        sync,
+        identity: { actorId: 'user-1' },
         clientId: 'client-1',
         autoStart: false,
         pollIntervalMs: 1000,
@@ -265,8 +282,8 @@ describe('SyncProvider React render tests', () => {
         createElement(SyncProvider, {
           db,
           transport: mockTransport,
-          handlers: mockHandlers,
-          actorId: 'user-1',
+          sync,
+          identity: { actorId: 'user-1' },
           clientId: 'client-1',
           autoStart: false,
           pollIntervalMs: 5000, // Changed non-critical prop

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

@@ -7,6 +7,7 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import {
   enqueueOutboxCommit,
+  getClientHandlerOrThrow,
   getNextSendableOutboxCommit,
 } from '@syncular/client';
 
@@ -109,11 +110,10 @@ describe('Push Flow', () => {
 
   it('sync updates local row with server version after push', async () => {
     // First, apply the mutation locally (this is what useMutation does)
-    const handlers = client.handlers;
-    const handler = handlers.get('tasks');
+    const handler = getClientHandlerOrThrow(client.handlers, 'tasks');
 
     await client.db.transaction().execute(async (trx) => {
-      await handler!.applyChange(
+      await handler.applyChange(
         { trx },
         {
           table: 'tasks',

package/src/__tests__/test-utils.ts

@@ -3,13 +3,15 @@
  */
 
 import type {
+  ClientHandlerCollection,
+  ClientSyncConfig,
+  SyncClientDb,
   SyncPullRequest,
   SyncPullResponse,
   SyncPushRequest,
   SyncPushResponse,
   SyncTransport,
 } from '@syncular/client';
-import { ClientTableRegistry, type SyncClientDb } from '@syncular/client';
 import type { Kysely } from 'kysely';
 
 /**
@@ -68,8 +70,25 @@ export function createMockTransport(
  */
 export function createMockHandlerRegistry<
   DB extends SyncClientDb = SyncClientDb,
->(): ClientTableRegistry<DB> {
-  return new ClientTableRegistry<DB>();
+>(): ClientHandlerCollection<DB> {
+  return [];
+}
+
+export function createMockSync<DB extends SyncClientDb = SyncClientDb>(args?: {
+  handlers?: ClientHandlerCollection<DB>;
+  subscriptions?: Array<{
+    id: string;
+    table: string;
+    scopes?: Record<string, unknown>;
+  }>;
+}): ClientSyncConfig<DB, { actorId: string }> {
+  const handlers = args?.handlers ?? createMockHandlerRegistry<DB>();
+  const subscriptions = args?.subscriptions ?? [];
+
+  return {
+    handlers,
+    subscriptions: () => subscriptions,
+  };
 }
 
 /**
@@ -79,14 +98,14 @@ export async function createMockDb<
   DB extends SyncClientDb = SyncClientDb,
 >(): Promise<Kysely<DB>> {
   // Dynamic import to avoid bundling issues
-  const { Kysely } = await import('kysely');
-  const { BunSqliteDialect } = await import('kysely-bun-sqlite');
-  const { Database } = await import('bun:sqlite');
-
-  const db = new Kysely<DB>({
-    dialect: new BunSqliteDialect({
-      database: new Database(':memory:'),
-    }),
+  const { createDatabase } = await import('@syncular/core');
+  const { createBunSqliteDialect } = await import(
+    '@syncular/dialect-bun-sqlite'
+  );
+
+  const db = createDatabase<DB>({
+    dialect: createBunSqliteDialect({ path: ':memory:' }),
+    family: 'sqlite',
   });
 
   // Create sync tables

package/src/__tests__/use-cached-async-value.test.tsx

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'bun:test';
+import { renderHook, waitFor } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { StrictMode } from 'react';
+import {
+  clearCachedAsyncValues,
+  useCachedAsyncValue,
+} from '../use-cached-async-value';
+
+function strictModeWrapper(props: { children: ReactNode }) {
+  return <StrictMode>{props.children}</StrictMode>;
+}
+
+describe('useCachedAsyncValue', () => {
+  it('deduplicates StrictMode initialization by key', async () => {
+    clearCachedAsyncValues();
+    let runs = 0;
+
+    const { result } = renderHook(
+      () =>
+        useCachedAsyncValue(
+          async () => {
+            runs += 1;
+            return 'ready';
+          },
+          { key: 'strictmode-init' }
+        ),
+      { wrapper: strictModeWrapper }
+    );
+
+    await waitFor(() => {
+      expect(result.current[0]).toBe('ready');
+    });
+    expect(result.current[1]).toBeNull();
+    expect(runs).toBe(1);
+  });
+
+  it('retries after a failure when dependencies trigger rerun', async () => {
+    clearCachedAsyncValues();
+    let runs = 0;
+
+    const { result, rerender } = renderHook(
+      ({ attempt }: { attempt: number }) =>
+        useCachedAsyncValue(
+          async () => {
+            runs += 1;
+            if (attempt === 0) {
+              throw new Error('boom');
+            }
+            return 'recovered';
+          },
+          {
+            key: 'retryable-init',
+            deps: [attempt],
+          }
+        ),
+      {
+        initialProps: { attempt: 0 },
+      }
+    );
+
+    await waitFor(() => {
+      expect(result.current[1]?.message).toBe('boom');
+    });
+
+    rerender({ attempt: 1 });
+
+    await waitFor(() => {
+      expect(result.current[0]).toBe('recovered');
+    });
+    expect(result.current[1]).toBeNull();
+    expect(runs).toBe(2);
+  });
+
+  it('reuses cached values across component remounts', async () => {
+    clearCachedAsyncValues();
+    let runs = 0;
+
+    const first = renderHook(() =>
+      useCachedAsyncValue(
+        async () => {
+          runs += 1;
+          return 7;
+        },
+        { key: 'shared-init' }
+      )
+    );
+
+    await waitFor(() => {
+      expect(first.result.current[0]).toBe(7);
+    });
+    first.unmount();
+
+    const second = renderHook(() =>
+      useCachedAsyncValue(
+        async () => {
+          runs += 1;
+          return 9;
+        },
+        { key: 'shared-init' }
+      )
+    );
+
+    await waitFor(() => {
+      expect(second.result.current[0]).toBe(7);
+    });
+    expect(second.result.current[1]).toBeNull();
+    expect(runs).toBe(1);
+    second.unmount();
+  });
+});

package/src/__tests__/useMutations.test.tsx

@@ -11,6 +11,7 @@ import { createSyncularReact } from '../index';
 import {
   createMockDb,
   createMockHandlerRegistry,
+  createMockSync,
   createMockTransport,
 } from './test-utils';
 
@@ -54,15 +55,15 @@ describe('useMutations', () => {
   function createWrapper() {
     const transport = createMockTransport();
     const handlers = createMockHandlerRegistry<TestDb>();
+    const sync = createMockSync<TestDb>({ handlers });
 
     const Wrapper = ({ children }: { children: ReactNode }) => (
       <SyncProvider
         db={db}
         transport={transport}
-        handlers={handlers}
-        actorId="test-actor"
+        sync={sync}
+        identity={{ actorId: 'test-actor' }}
         clientId="test-client"
-        subscriptions={[]}
         pollIntervalMs={999999}
         autoStart={false}
       >