@syncular/client-react 0.0.1 → 0.0.2-127

package/src/__tests__/test-utils.ts

@@ -24,37 +24,49 @@ export function createMockTransport(
   } = {}
 ): SyncTransport {
   return {
-    async pull(request: SyncPullRequest): Promise<SyncPullResponse> {
-      options.onPull?.(request);
-      return {
-        ok: true,
-        subscriptions: [],
-        ...options.pullResponse,
-      };
-    },
-    async push(request: SyncPushRequest): Promise<SyncPushResponse> {
-      options.onPush?.(request);
-      return {
-        ok: true,
-        status: 'applied',
-        results: request.operations.map((_, i) => ({
-          opIndex: i,
-          status: 'applied' as const,
-        })),
-        ...options.pushResponse,
-      };
+    async sync(request) {
+      const result: { ok: true; push?: any; pull?: any } = { ok: true };
+
+      if (request.push) {
+        options.onPush?.({
+          clientId: request.clientId,
+          ...request.push,
+        } as SyncPushRequest);
+        result.push = {
+          ok: true,
+          status: 'applied',
+          results: request.push.operations.map((_, i) => ({
+            opIndex: i,
+            status: 'applied' as const,
+          })),
+          ...options.pushResponse,
+        };
+      }
+
+      if (request.pull) {
+        options.onPull?.({
+          clientId: request.clientId,
+          ...request.pull,
+        } as SyncPullRequest);
+        result.pull = {
+          ok: true,
+          subscriptions: [],
+          ...options.pullResponse,
+        };
+      }
+
+      return result;
     },
     async fetchSnapshotChunk(): Promise<Uint8Array> {
-      // Return empty gzipped NDJSON (empty array)
       return new Uint8Array();
     },
   };
 }
 
 /**
- * Create a mock shape registry
+ * Create a mock handler registry
  */
-export function createMockShapeRegistry<
+export function createMockHandlerRegistry<
   DB extends SyncClientDb = SyncClientDb,
 >(): ClientTableRegistry<DB> {
   return new ClientTableRegistry<DB>();
@@ -83,7 +95,7 @@ export async function createMockDb<
     .ifNotExists()
     .addColumn('state_id', 'text', (col) => col.notNull())
     .addColumn('subscription_id', 'text', (col) => col.notNull())
-    .addColumn('shape', 'text', (col) => col.notNull())
+    .addColumn('table', 'text', (col) => col.notNull())
     .addColumn('scopes_json', 'text', (col) => col.notNull())
     .addColumn('params_json', 'text', (col) => col.notNull())
     .addColumn('cursor', 'integer', (col) => col.notNull())

package/src/__tests__/useMutations.test.tsx

@@ -10,7 +10,7 @@ import type { ReactNode } from 'react';
 import { createSyncularReact } from '../index';
 import {
   createMockDb,
-  createMockShapeRegistry,
+  createMockHandlerRegistry,
   createMockTransport,
 } from './test-utils';
 
@@ -53,13 +53,13 @@ describe('useMutations', () => {
 
   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/createSyncularReact.tsx

@@ -68,17 +68,33 @@ function isExecutableQuery<TResult>(
   return typeof value.execute === 'function';
 }
 
+function isPresenceMetadataEqual(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true;
+  if (!isRecord(left) || !isRecord(right)) return false;
+
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) return false;
+
+  for (const key of leftKeys) {
+    if (!(key in right)) return false;
+    if (!Object.is(left[key], right[key])) return false;
+  }
+
+  return true;
+}
+
 export interface SyncContextValue<DB extends SyncClientDb> {
   engine: SyncEngine<DB>;
   db: Kysely<DB>;
   transport: SyncTransport;
-  shapes: ClientTableRegistry<DB>;
+  handlers: ClientTableRegistry<DB>;
 }
 
 export interface SyncProviderProps<DB extends SyncClientDb> {
   db: Kysely<DB>;
   transport: SyncTransport;
-  shapes: ClientTableRegistry<DB>;
+  handlers: ClientTableRegistry<DB>;
   actorId?: string | null;
   clientId?: string | null;
   subscriptions?: Array<Omit<SyncSubscriptionRequest, 'cursor'>>;
@@ -96,6 +112,8 @@ export interface SyncProviderProps<DB extends SyncClientDb> {
   onConflict?: (conflict: ConflictInfo) => void;
   onDataChange?: (scopes: string[]) => void;
   plugins?: SyncClientPlugin[];
+  /** Custom SHA-256 hash function (for platforms without crypto.subtle, e.g. React Native) */
+  sha256?: (bytes: Uint8Array) => Promise<string>;
   autoStart?: boolean;
   renderWhileStarting?: boolean;
   children: ReactNode;
@@ -107,6 +125,7 @@ export interface UseSyncEngineResult {
   reconnect: () => void;
   disconnect: () => void;
   start: () => Promise<void>;
+  resetLocalState: () => void;
 }
 
 export interface SyncStatus {
@@ -297,7 +316,7 @@ export function createSyncularReact<DB extends SyncClientDb>() {
   function SyncProvider({
     db,
     transport,
-    shapes,
+    handlers,
     actorId,
     clientId,
     subscriptions = [],
@@ -315,15 +334,16 @@ export function createSyncularReact<DB extends SyncClientDb>() {
     onConflict,
     onDataChange,
     plugins,
+    sha256,
     autoStart = true,
-    renderWhileStarting = false,
+    renderWhileStarting = true,
     children,
   }: SyncProviderProps<DB>): ReactNode {
     const config = useMemo<SyncEngineConfig<DB>>(
       () => ({
         db,
         transport,
-        shapes,
+        handlers,
         actorId,
         clientId,
         subscriptions,
@@ -341,11 +361,12 @@ export function createSyncularReact<DB extends SyncClientDb>() {
         onConflict,
         onDataChange,
         plugins,
+        sha256,
       }),
       [
         db,
         transport,
-        shapes,
+        handlers,
         actorId,
         clientId,
         subscriptions,
@@ -363,6 +384,7 @@ export function createSyncularReact<DB extends SyncClientDb>() {
         onConflict,
         onDataChange,
         plugins,
+        sha256,
       ]
     );
 
@@ -373,7 +395,7 @@ export function createSyncularReact<DB extends SyncClientDb>() {
       clientId,
       db,
       transport,
-      shapes,
+      handlers,
     }));
 
     useEffect(() => {
@@ -382,7 +404,7 @@ export function createSyncularReact<DB extends SyncClientDb>() {
       if (clientId !== initialProps.clientId) changedProps.push('clientId');
       if (db !== initialProps.db) changedProps.push('db');
       if (transport !== initialProps.transport) changedProps.push('transport');
-      if (shapes !== initialProps.shapes) changedProps.push('shapes');
+      if (handlers !== initialProps.handlers) changedProps.push('handlers');
 
       if (changedProps.length > 0) {
         const message =
@@ -399,7 +421,7 @@ export function createSyncularReact<DB extends SyncClientDb>() {
           );
         }
       }
-    }, [actorId, clientId, db, transport, shapes, initialProps]);
+    }, [actorId, clientId, db, transport, handlers, initialProps]);
 
     const [isReady, setIsReady] = useState(false);
 
@@ -441,12 +463,12 @@ export function createSyncularReact<DB extends SyncClientDb>() {
         engine,
         db,
         transport,
-        shapes,
+        handlers,
       }),
-      [engine, db, transport, shapes]
+      [engine, db, transport, handlers]
     );
 
-    if (!isReady && !renderWhileStarting) {
+    if (!isReady && renderWhileStarting === false) {
       return null;
     }
 
@@ -480,6 +502,10 @@ export function createSyncularReact<DB extends SyncClientDb>() {
     const reconnect = useCallback(() => engine.reconnect(), [engine]);
     const disconnect = useCallback(() => engine.disconnect(), [engine]);
     const start = useCallback(() => engine.start(), [engine]);
+    const resetLocalState = useCallback(
+      () => engine.resetLocalState(),
+      [engine]
+    );
 
     return {
       state,
@@ -487,6 +513,7 @@ export function createSyncularReact<DB extends SyncClientDb>() {
       reconnect,
       disconnect,
       start,
+      resetLocalState,
     };
   }
 
@@ -1272,6 +1299,8 @@ export function createSyncularReact<DB extends SyncClientDb>() {
     const engine = useEngine();
     const { presence, isLoading } = usePresence<TMetadata>(scopeKey);
     const [isJoined, setIsJoined] = useState(false);
+    const previousMetadataRef = useRef<TMetadata | undefined>(initialMetadata);
+    const autoJoinMetadataRef = useRef<TMetadata | undefined>(initialMetadata);
 
     const join = useCallback(
       (metadata?: TMetadata) => {
@@ -1299,16 +1328,42 @@ export function createSyncularReact<DB extends SyncClientDb>() {
       [engine, scopeKey]
     );
 
+    useEffect(() => {
+      autoJoinMetadataRef.current = initialMetadata;
+    }, [initialMetadata]);
+
     useEffect(() => {
       if (autoJoin) {
-        join(initialMetadata);
+        const metadata = autoJoinMetadataRef.current;
+        join(metadata);
+        previousMetadataRef.current = metadata;
       }
 
       return () => {
         leave();
       };
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [autoJoin, initialMetadata, join, leave]);
+    }, [autoJoin, join, leave]);
+
+    useEffect(() => {
+      if (!autoJoin || !isJoined) {
+        previousMetadataRef.current = initialMetadata;
+        return;
+      }
+
+      if (initialMetadata === undefined) {
+        previousMetadataRef.current = initialMetadata;
+        return;
+      }
+
+      if (
+        isPresenceMetadataEqual(previousMetadataRef.current, initialMetadata)
+      ) {
+        return;
+      }
+
+      previousMetadataRef.current = initialMetadata;
+      updateMetadata(initialMetadata);
+    }, [autoJoin, initialMetadata, isJoined, updateMetadata]);
 
     return {
       presence,

package/src/index.ts

@@ -5,5 +5,32 @@
  * typed to your application's DB schema.
  */
 
+export type {
+  ConflictResolution,
+  FluentMutation,
+  MutationInput,
+  MutationResult,
+  MutationsHook,
+  OutboxCommit,
+  SyncContextValue,
+  SyncProviderProps,
+  SyncStatus,
+  UseConflictsResult,
+  UseMutationOptions,
+  UseMutationResult,
+  UseMutationsOptions,
+  UseOutboxResult,
+  UsePresenceResult,
+  UsePresenceWithJoinOptions,
+  UsePresenceWithJoinResult,
+  UseQueryOptions,
+  UseQueryResult,
+  UseResolveConflictOptions,
+  UseResolveConflictResult,
+  UseSyncConnectionResult,
+  UseSyncEngineResult,
+  UseSyncQueryOptions,
+  UseSyncQueryResult,
+} from './createSyncularReact';
 // Re-export core client types for convenience.
 export { createSyncularReact } from './createSyncularReact';