@syncular/client-react 0.0.1 → 0.0.2-126

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

@@ -21,7 +21,7 @@ import React from 'react';
 import { createSyncularReact } from '../index';
 import {
   createMockDb,
-  createMockShapeRegistry,
+  createMockHandlerRegistry,
   createMockTransport,
 } from './test-utils';
 
@@ -66,14 +66,14 @@ describe('SyncProvider (StrictMode)', () => {
 
   function renderWithProvider(node: React.ReactNode) {
     const transport = createMockTransport();
-    const shapes = createMockShapeRegistry();
+    const handlers = createMockHandlerRegistry();
 
     return render(
       <React.StrictMode>
         <SyncProvider
           db={db}
           transport={transport}
-          shapes={shapes}
+          handlers={handlers}
           actorId="test-actor"
           clientId="test-client"
           subscriptions={[]}

package/src/__tests__/fingerprint.test.ts

@@ -12,7 +12,7 @@ import {
 import type { Kysely } from 'kysely';
 import {
   createMockDb,
-  createMockShapeRegistry,
+  createMockHandlerRegistry,
   createMockTransport,
 } from './test-utils';
 
@@ -32,7 +32,7 @@ describe('fingerprint utilities', () => {
     const config: SyncEngineConfig = {
       db,
       transport: createMockTransport(),
-      shapes: createMockShapeRegistry(),
+      handlers: createMockHandlerRegistry(),
       actorId: 'test-actor',
       clientId: 'test-client',
       subscriptions: [],
@@ -108,11 +108,11 @@ describe('fingerprint utilities', () => {
       await engine.start();
 
       // Simulate a mutation by calling applyLocalMutation
-      // This requires the shape handler to exist, so we'll test getMutationTimestamp directly
+      // This requires the table handler to exist, so we'll test getMutationTimestamp directly
       const beforeMutation = engine.getMutationTimestamp('tasks', 'abc');
       expect(beforeMutation).toBe(0);
 
-      // We can't easily test the full mutation flow without proper shape setup,
+      // We can't easily test the full mutation flow without proper handler setup,
       // but we can verify the fingerprint changes when timestamps change
     });
 

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

@@ -20,7 +20,7 @@ import type { ReactNode } from 'react';
 import { createSyncularReact } from '../../index';
 import {
   createMockDb,
-  createMockShapeRegistry,
+  createMockHandlerRegistry,
   createMockTransport,
 } from '../test-utils';
 
@@ -59,13 +59,13 @@ describe('useMutation', () => {
 
   function createWrapper() {
     const transport = createMockTransport();
-    const shapes = createMockShapeRegistry<TestDb>();
+    const handlers = createMockHandlerRegistry<TestDb>();
 
     const Wrapper = ({ children }: { children: ReactNode }) => (
       <SyncProvider
         db={db}
         transport={transport}
-        shapes={shapes}
+        handlers={handlers}
         actorId="test-actor"
         clientId="test-client"
         subscriptions={[]}

package/src/__tests__/hooks.test.tsx

@@ -13,14 +13,16 @@ import type { ReactNode } from 'react';
 import { createSyncularReact } from '../index';
 import {
   createMockDb,
-  createMockShapeRegistry,
+  createMockHandlerRegistry,
   createMockTransport,
 } from './test-utils';
 
 const {
   SyncProvider,
   useConflicts,
+  useEngine,
   useOutbox,
+  usePresenceWithJoin,
   useResolveConflict,
   useSyncConnection,
   useSyncEngine,
@@ -36,13 +38,13 @@ describe('React Hooks', () => {
 
   function createWrapper(options?: { autoStart?: boolean }) {
     const transport = createMockTransport();
-    const shapes = createMockShapeRegistry();
+    const handlers = createMockHandlerRegistry();
 
     const Wrapper = ({ children }: { children: ReactNode }) => (
       <SyncProvider
         db={db}
         transport={transport}
-        shapes={shapes}
+        handlers={handlers}
         actorId="test-actor"
         clientId="test-client"
         subscriptions={[]}
@@ -151,6 +153,99 @@ describe('React Hooks', () => {
     // These hook tests verify the React binding works
   });
 
+  describe('usePresenceWithJoin', () => {
+    it('does not re-join when metadata object identity changes with equal values', async () => {
+      let joinCalls = 0;
+      let leaveCalls = 0;
+
+      const { result, rerender } = renderHook(
+        ({ metadata }: { metadata: { displayName: string } }) => {
+          const engine = useEngine();
+          const presence = usePresenceWithJoin('room:1', {
+            metadata,
+            autoJoin: true,
+          });
+          return { engine, presence };
+        },
+        {
+          wrapper: createWrapper(),
+          initialProps: { metadata: { displayName: 'Alice' } },
+        }
+      );
+
+      await waitFor(() => {
+        expect(result.current.presence.isJoined).toBe(true);
+      });
+
+      const originalJoin = result.current.engine.joinPresence.bind(
+        result.current.engine
+      );
+      const originalLeave = result.current.engine.leavePresence.bind(
+        result.current.engine
+      );
+
+      result.current.engine.joinPresence = (scopeKey, metadata) => {
+        joinCalls += 1;
+        originalJoin(scopeKey, metadata);
+      };
+      result.current.engine.leavePresence = (scopeKey) => {
+        leaveCalls += 1;
+        originalLeave(scopeKey);
+      };
+
+      rerender({ metadata: { displayName: 'Alice' } });
+      await act(async () => {
+        await Promise.resolve();
+      });
+
+      expect(joinCalls).toBe(0);
+      expect(leaveCalls).toBe(0);
+    });
+
+    it('updates metadata when auto-join metadata changes', async () => {
+      let updateCalls = 0;
+
+      const { result, rerender } = renderHook(
+        ({ metadata }: { metadata: { displayName: string } }) => {
+          const engine = useEngine();
+          const presence = usePresenceWithJoin('room:2', {
+            metadata,
+            autoJoin: true,
+          });
+          return { engine, presence };
+        },
+        {
+          wrapper: createWrapper(),
+          initialProps: { metadata: { displayName: 'Alice' } },
+        }
+      );
+
+      await waitFor(() => {
+        expect(result.current.presence.isJoined).toBe(true);
+      });
+
+      const originalUpdate = result.current.engine.updatePresenceMetadata.bind(
+        result.current.engine
+      );
+      result.current.engine.updatePresenceMetadata = (scopeKey, metadata) => {
+        updateCalls += 1;
+        originalUpdate(scopeKey, metadata);
+      };
+
+      rerender({ metadata: { displayName: 'Bob' } });
+
+      await waitFor(() => {
+        expect(updateCalls).toBe(1);
+      });
+
+      await waitFor(() => {
+        expect(result.current.presence.presence[0]?.metadata).toMatchObject({
+          displayName: 'Bob',
+        });
+      });
+    });
+  });
+
   describe('useOutbox', () => {
     it('should return outbox stats', async () => {
       const { result } = renderHook(() => useOutbox(), {

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

@@ -46,12 +46,12 @@ function createMockClientTableRegistry(): ClientTableRegistry<ClientDb> {
 describe('SyncProvider Reconfiguration', () => {
   let server: TestServer;
   let db: Kysely<ClientDb>;
-  let mockShapes: ClientTableRegistry<ClientDb>;
+  let mockHandlers: ClientTableRegistry<ClientDb>;
 
   beforeEach(async () => {
     server = await createTestServer();
     db = createBunSqliteDb<ClientDb>({ path: ':memory:' });
-    mockShapes = createMockClientTableRegistry();
+    mockHandlers = createMockClientTableRegistry();
 
     await ensureClientSyncSchema(db);
 
@@ -77,14 +77,8 @@ describe('SyncProvider Reconfiguration', () => {
   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 sync() {
+        return { ok: true as const };
       },
       async fetchSnapshotChunk() {
         return new Uint8Array();
@@ -95,7 +89,7 @@ describe('SyncProvider Reconfiguration', () => {
     const engine1 = new SyncEngine({
       db,
       transport,
-      shapes: mockShapes,
+      handlers: mockHandlers,
       actorId: 'user-1',
       clientId: 'client-1',
       subscriptions: [],
@@ -110,7 +104,7 @@ describe('SyncProvider Reconfiguration', () => {
     const engine2 = new SyncEngine({
       db,
       transport,
-      shapes: mockShapes,
+      handlers: mockHandlers,
       actorId: 'user-2',
       clientId: 'client-1',
       subscriptions: [],
@@ -163,11 +157,8 @@ describe('SyncProvider Reconfiguration', () => {
 
   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 sync() {
+        return { ok: true as const };
       },
       async fetchSnapshotChunk() {
         return new Uint8Array();
@@ -177,7 +168,7 @@ describe('SyncProvider Reconfiguration', () => {
     const engine = new SyncEngine({
       db,
       transport,
-      shapes: mockShapes,
+      handlers: mockHandlers,
       actorId: 'user-1',
       clientId: 'client-1',
       subscriptions: [],
@@ -197,13 +188,10 @@ describe('SyncProvider Reconfiguration', () => {
 
 describe('SyncProvider React render tests', () => {
   let db: Kysely<ClientDb>;
-  let mockShapes: ClientTableRegistry<ClientDb>;
+  let mockHandlers: 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 sync() {
+      return { ok: true as const };
     },
     async fetchSnapshotChunk() {
       return new Uint8Array();
@@ -212,7 +200,7 @@ describe('SyncProvider React render tests', () => {
 
   beforeEach(async () => {
     db = createBunSqliteDb<ClientDb>({ path: ':memory:' });
-    mockShapes = new ClientTableRegistry<ClientDb>();
+    mockHandlers = new ClientTableRegistry<ClientDb>();
     await ensureClientSyncSchema(db);
   });
 
@@ -229,7 +217,7 @@ describe('SyncProvider React render tests', () => {
       createElement(SyncProvider, {
         db,
         transport: mockTransport,
-        shapes: mockShapes,
+        handlers: mockHandlers,
         actorId: 'user-1',
         clientId: 'client-1',
         autoStart: false, // Disable auto-start for faster test
@@ -244,7 +232,7 @@ describe('SyncProvider React render tests', () => {
         createElement(SyncProvider, {
           db,
           transport: mockTransport,
-          shapes: mockShapes,
+          handlers: mockHandlers,
           actorId: 'user-2', // Changed!
           clientId: 'client-1',
           autoStart: false,
@@ -261,7 +249,7 @@ describe('SyncProvider React render tests', () => {
       createElement(SyncProvider, {
         db,
         transport: mockTransport,
-        shapes: mockShapes,
+        handlers: mockHandlers,
         actorId: 'user-1',
         clientId: 'client-1',
         autoStart: false,
@@ -277,7 +265,7 @@ describe('SyncProvider React render tests', () => {
         createElement(SyncProvider, {
           db,
           transport: mockTransport,
-          shapes: mockShapes,
+          handlers: mockHandlers,
           actorId: 'user-1',
           clientId: 'client-1',
           autoStart: false,

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

@@ -9,7 +9,7 @@ import {
   enqueueOutboxCommit,
   getNextSendableOutboxCommit,
 } from '@syncular/client';
-import type { SyncPushRequest, SyncPushResponse } from '@syncular/core';
+
 import {
   createTestClient,
   createTestServer,
@@ -109,8 +109,8 @@ 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 shapes = client.shapes;
-    const handler = shapes.get('tasks');
+    const handlers = client.handlers;
+    const handler = handlers.get('tasks');
 
     await client.db.transaction().execute(async (trx) => {
       await handler!.applyChange(
@@ -243,31 +243,32 @@ describe('Push Flow', () => {
       clientId: 'retriable-client',
     });
 
-    // Override the transport to return retriable errors
-    const originalPush = retriableClient.transport.push.bind(
+    // Override the transport to return retriable errors on push
+    const originalSync = retriableClient.transport.sync.bind(
       retriableClient.transport
     );
     let retriableErrorCount = 0;
-    retriableClient.transport.push = async (
-      request: SyncPushRequest
-    ): Promise<SyncPushResponse> => {
-      if (retriableErrorCount < 2) {
-        // Return retriable error for first two attempts
+    retriableClient.transport.sync = async (request) => {
+      if (request.push && retriableErrorCount < 2) {
+        // Return retriable error for first two push 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,
-          })),
+          push: {
+            ok: true as const,
+            status: 'rejected' as const,
+            results: request.push.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);
+      return originalSync(request);
     };
 
     await retriableClient.engine.start();

package/src/__tests__/integration/test-setup.ts

@@ -8,8 +8,6 @@
 import type {
   SyncClientDb,
   SyncClientPlugin,
-  SyncPullRequest,
-  SyncPushRequest,
   SyncTransport,
 } from '@syncular/client';
 import {
@@ -27,6 +25,7 @@ import {
   ensureSyncSchema,
   pull,
   pushCommit,
+  readSnapshotChunk,
   recordClientCursor,
   type ServerSyncDialect,
   type ServerTableHandler,
@@ -73,7 +72,7 @@ export interface TestServer {
   /** Full database instance with app tables (also includes sync tables) */
   db: Kysely<ServerDb>;
   dialect: ServerSyncDialect;
-  shapes: TableRegistry<ServerDb>;
+  handlers: TableRegistry<ServerDb>;
 }
 
 /**
@@ -84,14 +83,14 @@ export interface TestClient {
   db: Kysely<ClientDb>;
   engine: SyncEngine<ClientDb>;
   transport: SyncTransport;
-  /** Client shapes registry */
-  shapes: ClientTableRegistry<ClientDb>;
+  /** Client handler registry */
+  handlers: ClientTableRegistry<ClientDb>;
 }
 
 /**
- * Server-side tasks shape handler for tests
+ * Server-side tasks table handler for tests
  */
-const tasksServerShape: ServerTableHandler<ServerDb> = {
+const tasksServerHandler: ServerTableHandler<ServerDb> = {
   table: 'tasks',
   scopePatterns: ['user:{user_id}'],
 
@@ -346,14 +345,14 @@ export async function createTestServer(): Promise<TestServer> {
     .addColumn('server_version', 'integer', (col) => col.notNull().defaultTo(1))
     .execute();
 
-  // Register shapes
-  const shapes = new TableRegistry<ServerDb>();
-  shapes.register(tasksServerShape);
+  // Register handlers
+  const handlers = new TableRegistry<ServerDb>();
+  handlers.register(tasksServerHandler);
 
   return {
     db,
     dialect,
-    shapes,
+    handlers,
   };
 }
 
@@ -366,39 +365,89 @@ function createInProcessTransport(
 ): SyncTransport {
   const syncDb = server.db;
 
+  async function streamToBytes(
+    stream: ReadableStream<Uint8Array>
+  ): Promise<Uint8Array> {
+    const reader = stream.getReader();
+    try {
+      const chunks: Uint8Array[] = [];
+      let total = 0;
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (!value) continue;
+        chunks.push(value);
+        total += value.length;
+      }
+
+      const merged = new Uint8Array(total);
+      let offset = 0;
+      for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.length;
+      }
+      return merged;
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
   return {
-    async pull(request: SyncPullRequest) {
-      const pulled = await pull({
-        db: syncDb,
-        dialect: server.dialect,
-        shapes: server.shapes,
-        actorId,
-        request,
-      });
-
-      await recordClientCursor(syncDb, server.dialect, {
-        clientId: request.clientId,
-        actorId,
-        cursor: pulled.clientCursor,
-        effectiveScopes: pulled.effectiveScopes,
-      });
-
-      return pulled.response;
-    },
+    async sync(request) {
+      const result: { ok: true; push?: any; pull?: any } = { ok: true };
+
+      if (request.push) {
+        const pushed = await pushCommit({
+          db: syncDb,
+          dialect: server.dialect,
+          handlers: server.handlers,
+          actorId,
+          request: {
+            clientId: request.clientId,
+            clientCommitId: request.push.clientCommitId,
+            operations: request.push.operations,
+            schemaVersion: request.push.schemaVersion,
+          },
+        });
+        result.push = pushed.response;
+      }
 
-    async push(request: SyncPushRequest) {
-      const pushed = await pushCommit({
-        db: syncDb,
-        dialect: server.dialect,
-        shapes: server.shapes,
-        actorId,
-        request,
-      });
-      return pushed.response;
+      if (request.pull) {
+        const pulled = await pull({
+          db: syncDb,
+          dialect: server.dialect,
+          handlers: server.handlers,
+          actorId,
+          request: {
+            clientId: request.clientId,
+            ...request.pull,
+          },
+        });
+
+        recordClientCursor(syncDb, server.dialect, {
+          clientId: request.clientId,
+          actorId,
+          cursor: pulled.clientCursor,
+          effectiveScopes: pulled.effectiveScopes,
+        }).catch(() => {});
+
+        result.pull = pulled.response;
+      }
+
+      return result;
     },
 
-    async fetchSnapshotChunk() {
-      return new Uint8Array();
+    async fetchSnapshotChunk(request) {
+      const chunk = await readSnapshotChunk(syncDb, request.chunkId);
+      if (!chunk) {
+        throw new Error(`Snapshot chunk not found: ${request.chunkId}`);
+      }
+
+      if (chunk.body instanceof Uint8Array) {
+        return new Uint8Array(chunk.body);
+      }
+
+      return streamToBytes(chunk.body);
     },
   };
 }
@@ -429,9 +478,9 @@ export async function createTestClient(
     .addColumn('server_version', 'integer', (col) => col.notNull().defaultTo(0))
     .execute();
 
-  // Create client shapes registry
-  const shapes = new ClientTableRegistry<ClientDb>();
-  shapes.register({
+  // Create client handler registry
+  const handlers = new ClientTableRegistry<ClientDb>();
+  handlers.register({
     table: 'tasks',
 
     async applySnapshot(ctx, snapshot) {
@@ -509,11 +558,11 @@ export async function createTestClient(
   const config: SyncEngineConfig<ClientDb> = {
     db,
     transport,
-    shapes,
+    handlers,
     actorId: options.actorId,
     clientId: options.clientId,
     subscriptions: [
-      { id: 'my-tasks', shape: 'tasks', scopes: { user_id: options.actorId } },
+      { id: 'my-tasks', table: 'tasks', scopes: { user_id: options.actorId } },
     ],
     pollIntervalMs: 999999, // Disable polling for tests
     realtimeEnabled: false,
@@ -522,7 +571,7 @@ export async function createTestClient(
 
   const engine = new SyncEngine<ClientDb>(config);
 
-  return { db, engine, transport, shapes };
+  return { db, engine, transport, handlers };
 }
 
 /**