@syncular/client-react 0.0.6-171 → 0.0.6-178

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client-react",
-  "version": "0.0.6-171",
+  "version": "0.0.6-178",
   "description": "React hooks and bindings for the Syncular client",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -44,7 +44,7 @@
     "release": "bunx syncular-publish"
   },
   "dependencies": {
-    "@syncular/client": "0.0.6-171"
+    "@syncular/client": "0.0.6-178"
   },
   "peerDependencies": {
     "kysely": "^0.28.0",
@@ -53,9 +53,9 @@
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.7.0",
     "@syncular/config": "0.0.0",
-    "@syncular/core": "0.0.6-171",
-    "@syncular/dialect-bun-sqlite": "0.0.6-171",
-    "@syncular/testkit": "0.0.6-171",
+    "@syncular/core": "0.0.6-178",
+    "@syncular/dialect-bun-sqlite": "0.0.6-178",
+    "@syncular/testkit": "0.0.6-178",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "happy-dom": "^20.7.0",

package/src/__tests__/hooks.test.tsx

@@ -9,6 +9,7 @@ import { beforeEach, describe, expect, it } from 'bun:test';
 import type { SyncClientDb } from '@syncular/client';
 import { act, renderHook, waitFor } from '@testing-library/react';
 import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
 import type { ReactNode } from 'react';
 import { createSyncularReact } from '../index';
 import {
@@ -506,6 +507,153 @@ describe('React Hooks', () => {
         }
       );
     });
+
+    it('tracks joined tables and refreshes when joined data changes', async () => {
+      await db.schema
+        .createTable('users')
+        .ifNotExists()
+        .addColumn('id', 'text', (col) => col.primaryKey())
+        .addColumn('name', 'text', (col) => col.notNull())
+        .execute();
+
+      await db.schema
+        .createTable('tasks')
+        .ifNotExists()
+        .addColumn('id', 'text', (col) => col.primaryKey())
+        .addColumn('user_id', 'text', (col) => col.notNull())
+        .addColumn('title', 'text', (col) => col.notNull())
+        .execute();
+
+      await sql`
+        insert into ${sql.table('users')} (${sql.ref('id')}, ${sql.ref('name')})
+        values (${sql.val('user-1')}, ${sql.val('Alice')})
+      `.execute(db);
+
+      await sql`
+        insert into ${sql.table('tasks')} (
+          ${sql.ref('id')},
+          ${sql.ref('user_id')},
+          ${sql.ref('title')}
+        )
+        values (
+          ${sql.val('task-1')},
+          ${sql.val('user-1')},
+          ${sql.val('First task')}
+        )
+      `.execute(db);
+
+      const { result } = renderHook(
+        () => {
+          const engine = useEngine();
+          const query = useSyncQuery(({ selectFrom }) =>
+            selectFrom('tasks')
+              .innerJoin('users', 'users.id', 'tasks.user_id')
+              .select([
+                'tasks.id as id',
+                'tasks.title as title',
+                'users.name as ownerName',
+              ])
+              .orderBy('tasks.id', 'asc')
+          );
+
+          return { engine, query };
+        },
+        { wrapper: createWrapper() }
+      );
+
+      await waitFor(() => {
+        expect(result.current.query.isLoading).toBe(false);
+        expect(result.current.query.data?.[0]).toMatchObject({
+          id: 'task-1',
+          ownerName: 'Alice',
+        });
+      });
+
+      await act(async () => {
+        await sql`
+          update ${sql.table('users')}
+          set ${sql.ref('name')} = ${sql.val('Bob')}
+          where ${sql.ref('id')} = ${sql.val('user-1')}
+        `.execute(db);
+
+        result.current.engine.recordLocalMutations([
+          {
+            table: 'users',
+            rowId: 'user-1',
+            op: 'upsert',
+          },
+        ]);
+      });
+
+      await waitFor(() => {
+        expect(result.current.query.data?.[0]).toMatchObject({
+          id: 'task-1',
+          ownerName: 'Bob',
+        });
+      });
+    });
+
+    it('preserves unchanged row references across keyed array refreshes', async () => {
+      await db.schema
+        .createTable('tasks')
+        .ifNotExists()
+        .addColumn('id', 'text', (col) => col.primaryKey())
+        .addColumn('title', 'text', (col) => col.notNull())
+        .execute();
+
+      await sql`
+        insert into ${sql.table('tasks')} (${sql.ref('id')}, ${sql.ref('title')})
+        values
+          (${sql.val('task-1')}, ${sql.val('First task')}),
+          (${sql.val('task-2')}, ${sql.val('Second task')})
+      `.execute(db);
+
+      const { result } = renderHook(
+        () => {
+          const engine = useEngine();
+          const query = useSyncQuery(({ selectFrom }) =>
+            selectFrom('tasks').selectAll().orderBy('id', 'asc')
+          );
+
+          return { engine, query };
+        },
+        { wrapper: createWrapper() }
+      );
+
+      await waitFor(() => {
+        expect(result.current.query.isLoading).toBe(false);
+        expect(result.current.query.data?.length).toBe(2);
+      });
+
+      const firstRow = result.current.query.data?.[0];
+      const secondRow = result.current.query.data?.[1];
+
+      await act(async () => {
+        await sql`
+          update ${sql.table('tasks')}
+          set ${sql.ref('title')} = ${sql.val('Second task updated')}
+          where ${sql.ref('id')} = ${sql.val('task-2')}
+        `.execute(db);
+
+        result.current.engine.recordLocalMutations([
+          {
+            table: 'tasks',
+            rowId: 'task-2',
+            op: 'upsert',
+          },
+        ]);
+      });
+
+      await waitFor(() => {
+        expect(result.current.query.data?.[1]).toMatchObject({
+          id: 'task-2',
+          title: 'Second task updated',
+        });
+      });
+
+      expect(result.current.query.data?.[0]).toBe(firstRow);
+      expect(result.current.query.data?.[1]).not.toBe(secondRow);
+    });
   });
 
   describe('usePresenceWithJoin', () => {

package/src/__tests__/useSyncQuery.branching.test.tsx

@@ -0,0 +1,155 @@
+import { beforeEach, describe, expect, it } from 'bun:test';
+import type { SyncClientDb } from '@syncular/client';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import type { ReactNode } from 'react';
+import { createSyncularReact } from '../index';
+import {
+  createMockDb,
+  createMockHandlerRegistry,
+  createMockSync,
+  createMockTransport,
+} from './test-utils';
+
+const { SyncProvider, useEngine, useSyncQuery } =
+  createSyncularReact<SyncClientDb>();
+
+describe('useSyncQuery branching', () => {
+  let db: Kysely<SyncClientDb>;
+
+  beforeEach(async () => {
+    db = await createMockDb();
+  });
+
+  function createWrapper() {
+    const transport = createMockTransport();
+    const handlers = createMockHandlerRegistry();
+    const sync = createMockSync({ handlers });
+
+    const Wrapper = ({ children }: { children: ReactNode }) => (
+      <SyncProvider
+        db={db}
+        transport={transport}
+        sync={sync}
+        identity={{ actorId: 'test-actor' }}
+        clientId="test-client"
+        pollIntervalMs={999999}
+        autoStart={false}
+      >
+        {children}
+      </SyncProvider>
+    );
+
+    return Wrapper;
+  }
+
+  it('does not leak joined tables from an abandoned builder branch', async () => {
+    await db.schema
+      .createTable('users')
+      .ifNotExists()
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('name', 'text', (col) => col.notNull())
+      .execute();
+
+    await db.schema
+      .createTable('tasks')
+      .ifNotExists()
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('user_id', 'text', (col) => col.notNull())
+      .addColumn('title', 'text', (col) => col.notNull())
+      .execute();
+
+    await sql`
+      insert into ${sql.table('users')} (${sql.ref('id')}, ${sql.ref('name')})
+      values (${sql.val('user-1')}, ${sql.val('Alice')})
+    `.execute(db);
+
+    await sql`
+      insert into ${sql.table('tasks')} (
+        ${sql.ref('id')},
+        ${sql.ref('user_id')},
+        ${sql.ref('title')}
+      )
+      values (
+        ${sql.val('task-1')},
+        ${sql.val('user-1')},
+        ${sql.val('First task')}
+      )
+    `.execute(db);
+
+    let executions = 0;
+
+    const { result } = renderHook(
+      () => {
+        const engine = useEngine();
+        const query = useSyncQuery(({ selectFrom }) => {
+          executions += 1;
+
+          const base = selectFrom('tasks');
+          void base.innerJoin('users', 'users.id', 'tasks.user_id');
+
+          return base
+            .select(['tasks.id as id', 'tasks.title as title'])
+            .orderBy('tasks.id', 'asc');
+        });
+
+        return { engine, query };
+      },
+      { wrapper: createWrapper() }
+    );
+
+    await waitFor(() => {
+      expect(result.current.query.isLoading).toBe(false);
+      expect(result.current.query.data?.[0]).toMatchObject({
+        id: 'task-1',
+        title: 'First task',
+      });
+    });
+
+    const initialExecutions = executions;
+
+    await act(async () => {
+      await sql`
+        update ${sql.table('users')}
+        set ${sql.ref('name')} = ${sql.val('Bob')}
+        where ${sql.ref('id')} = ${sql.val('user-1')}
+      `.execute(db);
+
+      result.current.engine.recordLocalMutations([
+        {
+          table: 'users',
+          rowId: 'user-1',
+          op: 'upsert',
+        },
+      ]);
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(executions).toBe(initialExecutions);
+
+    await act(async () => {
+      await sql`
+        update ${sql.table('tasks')}
+        set ${sql.ref('title')} = ${sql.val('First task updated')}
+        where ${sql.ref('id')} = ${sql.val('task-1')}
+      `.execute(db);
+
+      result.current.engine.recordLocalMutations([
+        {
+          table: 'tasks',
+          rowId: 'task-1',
+          op: 'upsert',
+        },
+      ]);
+    });
+
+    await waitFor(() => {
+      expect(executions).toBeGreaterThan(initialExecutions);
+      expect(result.current.query.data?.[0]).toMatchObject({
+        id: 'task-1',
+        title: 'First task updated',
+      });
+    });
+  });
+});

package/src/__tests__/useSyncQuery.structural-sharing.test.tsx

@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, it } from 'bun:test';
+import type { SyncClientDb } from '@syncular/client';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import type { Kysely } from 'kysely';
+import { sql } from 'kysely';
+import type { ReactNode } from 'react';
+import { createSyncularReact } from '../index';
+import {
+  createMockDb,
+  createMockHandlerRegistry,
+  createMockSync,
+  createMockTransport,
+} from './test-utils';
+
+const { SyncProvider, useEngine, useSyncQuery } =
+  createSyncularReact<SyncClientDb>();
+
+describe('useSyncQuery structural sharing', () => {
+  let db: Kysely<SyncClientDb>;
+
+  beforeEach(async () => {
+    db = await createMockDb();
+  });
+
+  function createWrapper() {
+    const transport = createMockTransport();
+    const handlers = createMockHandlerRegistry();
+    const sync = createMockSync({ handlers });
+
+    const Wrapper = ({ children }: { children: ReactNode }) => (
+      <SyncProvider
+        db={db}
+        transport={transport}
+        sync={sync}
+        identity={{ actorId: 'test-actor' }}
+        clientId="test-client"
+        pollIntervalMs={999999}
+        autoStart={false}
+      >
+        {children}
+      </SyncProvider>
+    );
+
+    return Wrapper;
+  }
+
+  it('preserves positional identity when joined rows share the same keyField', async () => {
+    await db.schema
+      .createTable('tasks')
+      .ifNotExists()
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('title', 'text', (col) => col.notNull())
+      .execute();
+
+    await db.schema
+      .createTable('task_notes')
+      .ifNotExists()
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('task_id', 'text', (col) => col.notNull())
+      .addColumn('note', 'text', (col) => col.notNull())
+      .execute();
+
+    await sql`
+      insert into ${sql.table('tasks')} (${sql.ref('id')}, ${sql.ref('title')})
+      values (${sql.val('task-1')}, ${sql.val('Task')})
+    `.execute(db);
+
+    await sql`
+      insert into ${sql.table('task_notes')} (
+        ${sql.ref('id')},
+        ${sql.ref('task_id')},
+        ${sql.ref('note')}
+      )
+      values
+        (${sql.val('note-1')}, ${sql.val('task-1')}, ${sql.val('First note')}),
+        (${sql.val('note-2')}, ${sql.val('task-1')}, ${sql.val('Second note')})
+    `.execute(db);
+
+    const { result } = renderHook(
+      () => {
+        const engine = useEngine();
+        const query = useSyncQuery(({ selectFrom }) =>
+          selectFrom('tasks')
+            .innerJoin('task_notes', 'task_notes.task_id', 'tasks.id')
+            .select([
+              'tasks.id as id',
+              'tasks.title as title',
+              'task_notes.id as noteId',
+              'task_notes.note as note',
+            ])
+            .orderBy('task_notes.id', 'asc')
+        );
+
+        return { engine, query };
+      },
+      { wrapper: createWrapper() }
+    );
+
+    await waitFor(() => {
+      expect(result.current.query.isLoading).toBe(false);
+      expect(result.current.query.data?.length).toBe(2);
+    });
+
+    const firstRow = result.current.query.data?.[0];
+    const secondRow = result.current.query.data?.[1];
+
+    await act(async () => {
+      await sql`
+        update ${sql.table('task_notes')}
+        set ${sql.ref('note')} = ${sql.val('Second note updated')}
+        where ${sql.ref('id')} = ${sql.val('note-2')}
+      `.execute(db);
+
+      result.current.engine.recordLocalMutations([
+        {
+          table: 'task_notes',
+          rowId: 'note-2',
+          op: 'upsert',
+        },
+      ]);
+    });
+
+    await waitFor(() => {
+      expect(result.current.query.data?.[1]).toMatchObject({
+        id: 'task-1',
+        noteId: 'note-2',
+        note: 'Second note updated',
+      });
+    });
+
+    expect(result.current.query.data?.[0]).toBe(firstRow);
+    expect(result.current.query.data?.[1]).not.toBe(secondRow);
+  });
+});

package/src/createSyncularReact-public.tsx

@@ -0,0 +1,220 @@
+import type { QueryContext, SyncClientDb } from '@syncular/client';
+import { useMemo, useRef } from 'react';
+import {
+  createSyncularReact as createSyncularReactBase,
+  type UseQueryOptions,
+  type UseQueryResult,
+  type UseSyncQueryOptions,
+  type UseSyncQueryResult,
+} from './createSyncularReact';
+
+type ExecutableQuery<TResult> = {
+  execute: () => Promise<TResult>;
+};
+
+type QueryFn<DB extends SyncClientDb, TResult> = (
+  ctx: QueryContext<DB>
+) => ExecutableQuery<TResult> | Promise<TResult>;
+
+type SyncularReactBindings<DB extends SyncClientDb> = ReturnType<
+  typeof createSyncularReactBase<DB>
+>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function shallowEqualRecords(
+  left: Record<string, unknown>,
+  right: Record<string, unknown>
+): boolean {
+  if (left === right) return true;
+
+  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;
+}
+
+function shallowEqualQueryValues(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true;
+  if (!isRecord(left) || !isRecord(right)) return false;
+  return shallowEqualRecords(left, right);
+}
+
+function getKeyedQueryValueKey<T>(value: T, keyField: string): string | null {
+  if (!isRecord(value) || !(keyField in value)) return null;
+
+  const key = value[keyField];
+  if (key === null || key === undefined) return null;
+  return String(key);
+}
+
+function buildUniqueKeyMap<T>(
+  items: T[],
+  keyField: string
+): Map<string, T> | null {
+  const itemsByKey = new Map<string, T>();
+
+  for (const item of items) {
+    const key = getKeyedQueryValueKey(item, keyField);
+    if (key === null || itemsByKey.has(key)) {
+      return null;
+    }
+    itemsByKey.set(key, item);
+  }
+
+  return itemsByKey;
+}
+
+function shareArrayResult<T>(previous: T[], next: T[], keyField: string): T[] {
+  if (previous.length === 0 || next.length === 0) {
+    return next;
+  }
+
+  const previousByKey = buildUniqueKeyMap(previous, keyField);
+  const nextByKey = buildUniqueKeyMap(next, keyField);
+  const shared = next.slice();
+
+  if (previousByKey && nextByKey) {
+    for (const [index, item] of next.entries()) {
+      const key = getKeyedQueryValueKey(item, keyField);
+      if (key === null) {
+        return next;
+      }
+
+      const previousItem = previousByKey.get(key);
+      if (
+        previousItem !== undefined &&
+        shallowEqualQueryValues(previousItem, item)
+      ) {
+        shared[index] = previousItem;
+      }
+    }
+  } else {
+    const limit = Math.min(previous.length, next.length);
+    for (let index = 0; index < limit; index += 1) {
+      const previousItem = previous[index];
+      const nextItem = next[index];
+      if (
+        previousItem !== undefined &&
+        nextItem !== undefined &&
+        shallowEqualQueryValues(previousItem, nextItem)
+      ) {
+        shared[index] = previousItem;
+      }
+    }
+  }
+
+  if (shared.length !== previous.length) {
+    return shared;
+  }
+
+  for (let index = 0; index < shared.length; index += 1) {
+    if (!Object.is(shared[index], previous[index])) {
+      return shared;
+    }
+  }
+
+  return previous;
+}
+
+function shareQueryResult<TResult>(
+  previous: TResult | undefined,
+  next: TResult | undefined,
+  keyField: string,
+  enabled: boolean
+): TResult | undefined {
+  if (!enabled || previous === undefined || next === undefined) {
+    return next;
+  }
+
+  if (Array.isArray(previous) && Array.isArray(next)) {
+    return shareArrayResult(previous, next, keyField) as TResult;
+  }
+
+  if (
+    isRecord(previous) &&
+    isRecord(next) &&
+    shallowEqualRecords(previous, next)
+  ) {
+    return previous;
+  }
+
+  return next;
+}
+
+export function createSyncularReact<
+  DB extends SyncClientDb,
+>(): SyncularReactBindings<DB> {
+  const base = createSyncularReactBase<DB>();
+
+  function useSyncQuery<TResult>(
+    queryFn: QueryFn<DB, TResult>,
+    options: UseSyncQueryOptions = {}
+  ): UseSyncQueryResult<TResult> {
+    const keyField = options.keyField ?? 'id';
+    const structuralSharing = options.structuralSharing !== false;
+    const sharedDataRef = useRef<TResult | undefined>(undefined);
+    const query = base.useSyncQuery(queryFn, {
+      ...options,
+      structuralSharing: false,
+    });
+
+    const data = useMemo(() => {
+      const shared = shareQueryResult(
+        sharedDataRef.current,
+        query.data,
+        keyField,
+        structuralSharing
+      );
+      sharedDataRef.current = shared;
+      return shared;
+    }, [query.data, keyField, structuralSharing]);
+
+    return useMemo(
+      () => ({
+        ...query,
+        data,
+      }),
+      [query, data]
+    );
+  }
+
+  function useQuery<TResult>(
+    queryFn: QueryFn<DB, TResult>,
+    options: UseQueryOptions = {}
+  ): UseQueryResult<TResult> {
+    const { enabled = true, deps = [], keyField = 'id' } = options;
+    const query = useSyncQuery(queryFn, {
+      enabled,
+      deps,
+      keyField,
+      refreshOnDataChange: false,
+      loadingOnRefresh: true,
+      transitionUpdates: false,
+    });
+
+    return useMemo(
+      () => ({
+        data: query.data,
+        isLoading: query.isLoading,
+        error: query.error,
+        refetch: query.refetch,
+      }),
+      [query.data, query.isLoading, query.error, query.refetch]
+    );
+  }
+
+  return {
+    ...base,
+    useQuery,
+    useSyncQuery,
+  } as SyncularReactBindings<DB>;
+}