@syncular/react 0.2.0

package/src/query-churn.ts

@@ -0,0 +1,248 @@
+/**
+ * Live-query churn hardening — the three cheap levers the query hooks share
+ * (block 4 "live-query churn" item). Under constant sync churn a naive live
+ * query re-renders and re-queries once per invalidation event; these levers
+ * cap both without reaching for IVM:
+ *
+ * 1. {@link reconcileRows} — result stability. After a re-run, compare the new
+ *    result to the previous one. Whole-result equal → the caller skips
+ *    `setRows` entirely (zero re-render). Otherwise build the new array but
+ *    REUSE the previous row object for every row whose content is unchanged,
+ *    so `React.memo`'d row components keyed by row identity skip re-render.
+ * 2. {@link FrameScheduler} — frame-coalesced re-query scheduling. Many
+ *    invalidation events between paints collapse to ONE re-run per query.
+ * 3. scope-key filtering lives in {@link ../use-sync-query} `eventMatches`
+ *    (it needs the event + the hook's options), documented there.
+ *
+ * Row identity mechanism (the honest key): the hook knows no primary key —
+ * rows are plain JSON-able objects out of SQLite — so per-row content equality
+ * IS the identity. We hash each row once with a stable JSON serialization
+ * (sorted keys, so column order can't spuriously differ) and match by index:
+ * a live query's ORDER BY makes index the stable position, and an unchanged
+ * row at position i keeps its object so memoized components skip. This is O(n)
+ * in the row count with one string hash per row — bounded and measured (~0.2ms
+ * for 1k narrow rows in bun; see query-churn.test.ts).
+ */
+
+/**
+ * A stable content hash for one row: JSON with keys sorted, so two rows with
+ * the same columns in a different order hash equal (SQLite projection order is
+ * stable per query, but sorting removes any dependence on it and is cheap for
+ * the narrow rows a row-component renders). Uint8Array values (rare in a
+ * projection) serialize by byte view so a fresh copy of equal bytes hashes
+ * equal rather than to `{}`.
+ */
+export function hashRow(row: unknown): string {
+  return JSON.stringify(row, replacer);
+}
+
+function replacer(_key: string, value: unknown): unknown {
+  if (value instanceof Uint8Array) return { __u8: [...value] };
+  if (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  ) {
+    // Sort keys so column/field order never spuriously changes the hash.
+    const sorted: Record<string, unknown> = {};
+    for (const k of Object.keys(value as Record<string, unknown>).sort()) {
+      sorted[k] = (value as Record<string, unknown>)[k];
+    }
+    return sorted;
+  }
+  return value;
+}
+
+/** The precomputed hash carrier for the previous result, so we hash once. */
+export interface HashedRows<Row> {
+  readonly rows: readonly Row[];
+  readonly hashes: readonly string[];
+}
+
+export function hashRows<Row>(rows: readonly Row[]): HashedRows<Row> {
+  const hashes = new Array<string>(rows.length);
+  for (let i = 0; i < rows.length; i++) hashes[i] = hashRow(rows[i]);
+  return { rows, hashes };
+}
+
+export interface ReconcileResult<Row> {
+  /**
+   * `undefined` → the whole result is unchanged; the caller MUST NOT call
+   * setRows (zero re-render, lever 1a). Otherwise the reconciled array to set,
+   * with previous row objects reused wherever a row's content was unchanged
+   * (lever 1b).
+   */
+  readonly next: HashedRows<Row> | undefined;
+}
+
+/**
+ * Reconcile a freshly-queried result against the previous hashed result.
+ * Returns `next: undefined` when nothing changed at all; otherwise a new
+ * hashed result whose row objects are the PREVIOUS objects wherever content is
+ * unchanged (matched by index), so identity-keyed memo components skip.
+ */
+export function reconcileRows<Row>(
+  prev: HashedRows<Row> | undefined,
+  fresh: readonly Row[],
+): ReconcileResult<Row> {
+  const freshHashes = new Array<string>(fresh.length);
+  for (let i = 0; i < fresh.length; i++) freshHashes[i] = hashRow(fresh[i]);
+
+  if (prev !== undefined && prev.rows.length === fresh.length) {
+    let identical = true;
+    for (let i = 0; i < fresh.length; i++) {
+      if (prev.hashes[i] !== freshHashes[i]) {
+        identical = false;
+        break;
+      }
+    }
+    if (identical) return { next: undefined };
+  }
+
+  // Changed: reuse the previous row object at each index whose hash matches,
+  // so unchanged rows keep their identity for memoized row components.
+  const rows = new Array<Row>(fresh.length);
+  for (let i = 0; i < fresh.length; i++) {
+    const reuse =
+      prev !== undefined &&
+      i < prev.rows.length &&
+      prev.hashes[i] === freshHashes[i];
+    // `i < fresh.length` bounds this loop, so `fresh[i]` is defined; the reuse
+    // branch is additionally guarded by `i < prev.rows.length`.
+    rows[i] = reuse ? (prev.rows[i] as Row) : (fresh[i] as Row);
+  }
+  return { next: { rows, hashes: freshHashes } };
+}
+
+/**
+ * A per-query re-run scheduler that coalesces bursts of invalidation events
+ * into ONE run per paint. Multiple `schedule()` calls before the next flush
+ * run the callback once. A `schedule()` that arrives WHILE the callback is
+ * running (re-entrant, or an event during an async re-query) marks dirty and
+ * runs the callback exactly once more after — never lost, never concurrent.
+ *
+ * Timing source: `requestAnimationFrame` when the host has it (a real browser
+ * paints one frame; the coalescing window is a frame), else a microtask via a
+ * resolved promise (bun tests have no rAF — this keeps them deterministic and
+ * timer-free, honoring the no-timers doctrine: it's a readiness turn, not a
+ * wall-clock sleep). {@link flush} runs any pending callback synchronously for
+ * tests, so no arbitrary sleeps are needed to observe coalescing.
+ */
+export class FrameScheduler {
+  #scheduled = false;
+  #running = false;
+  #dirty = false;
+  #callback: (() => void | Promise<void>) | undefined;
+
+  constructor(callback: () => void | Promise<void>) {
+    this.#callback = callback;
+    liveSchedulers.add(this);
+  }
+
+  /** Request a run. Coalesces until the next frame/microtask boundary. */
+  schedule(): void {
+    if (this.#running) {
+      // An event arrived during a run — remember it and re-run once after.
+      this.#dirty = true;
+      return;
+    }
+    if (this.#scheduled) return;
+    this.#scheduled = true;
+    scheduleFrame(() => this.#fire());
+  }
+
+  #fire(): void {
+    this.#run();
+  }
+
+  /**
+   * Run the callback once, honoring the running/dirty contract: a `schedule()`
+   * during the run marks `#dirty`, and on completion we re-schedule exactly
+   * one more run — never lost, never concurrent. Returns the callback's result
+   * (a Promise for the async host path) so `flush` can hand it to a test.
+   */
+  #run(): void | Promise<void> {
+    this.#scheduled = false;
+    if (this.#callback === undefined) return;
+    this.#running = true;
+    this.#dirty = false;
+    const done = () => {
+      this.#running = false;
+      if (this.#dirty && this.#callback !== undefined) {
+        this.#dirty = false;
+        // An invalidation landed mid-run: re-run once more, coalesced.
+        this.schedule();
+      }
+    };
+    let result: void | Promise<void>;
+    try {
+      result = this.#callback();
+    } catch {
+      done();
+      return;
+    }
+    if (result && typeof (result as Promise<void>).then === 'function') {
+      return (result as Promise<void>).then(done, done);
+    }
+    done();
+    return;
+  }
+
+  /**
+   * Synchronously run any pending scheduled callback NOW (test determinism).
+   * Returns whatever the callback returned (a Promise for the async host path)
+   * so a test can await the re-query settling without a sleep. A no-op when
+   * nothing is pending.
+   */
+  flush(): void | Promise<void> {
+    if (!this.#scheduled || this.#callback === undefined) return;
+    return this.#run();
+  }
+
+  /** Drop the callback so a torn-down hook's pending frame is a no-op. */
+  dispose(): void {
+    this.#callback = undefined;
+    liveSchedulers.delete(this);
+  }
+}
+
+/**
+ * Live schedulers, weakly tracked for the test-only flush below. A Set (not
+ * WeakSet) so we can iterate; entries are removed on `dispose()`, so a mounted
+ * hook holds at most one entry and unmount clears it.
+ */
+const liveSchedulers = new Set<FrameScheduler>();
+
+/**
+ * TEST-ONLY: synchronously flush every live scheduler's pending frame, so a
+ * test can observe the coalesced re-query without a wall-clock sleep (the
+ * no-timers doctrine — a readiness flush, injected, not a timer). Returns a
+ * Promise that settles when every flushed async re-query has settled.
+ */
+export function flushQuerySchedulers(): Promise<void> {
+  const pending: Array<Promise<void>> = [];
+  for (const s of liveSchedulers) {
+    const r = s.flush();
+    if (r && typeof (r as Promise<void>).then === 'function') {
+      pending.push(r as Promise<void>);
+    }
+  }
+  return Promise.all(pending).then(() => undefined);
+}
+
+const raf: ((cb: () => void) => unknown) | undefined =
+  typeof globalThis.requestAnimationFrame === 'function'
+    ? globalThis.requestAnimationFrame.bind(globalThis)
+    : undefined;
+
+function scheduleFrame(cb: () => void): void {
+  if (raf !== undefined) {
+    raf(cb);
+    return;
+  }
+  // No rAF (bun test / worker): a microtask is the deterministic, timer-free
+  // coalescing boundary. Everything queued in the current synchronous run
+  // (a burst of emits) has already called schedule() before this drains.
+  queueMicrotask(cb);
+}

package/src/typed.ts

@@ -0,0 +1,6 @@
+/**
+ * `@syncular/react/typed` — the Kysely-typed live-query hook, kept behind
+ * this subpath so the main barrel never imports Kysely. Requires the
+ * `@syncular/kysely` and `kysely` peer dependencies.
+ */
+export { useTypedQuery } from './use-typed-query';

package/src/use-client.ts

@@ -0,0 +1,14 @@
+import { useContext } from 'react';
+import type { NormalizedClient } from './client';
+import { SyncContext } from './provider';
+
+/** Read the normalized client from context; throws outside a `SyncProvider`. */
+export function useSyncClient(): NormalizedClient {
+  const client = useContext(SyncContext);
+  if (client === undefined) {
+    throw new Error(
+      '@syncular/react: no client in context — wrap your tree in <SyncProvider client={…}>',
+    );
+  }
+  return client;
+}

package/src/use-conflicts.ts

@@ -0,0 +1,47 @@
+/**
+ * `useConflicts` — the accumulated conflict records (§6.2/§6.5) and
+ * rejections (§6.3) the client has surfaced. Re-read after every apply
+ * batch (a push result lands through the same choke point) plus on mount.
+ */
+
+import type { ConflictRecord, RejectionRecord } from '@syncular/client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useSyncClient } from './use-client';
+
+export interface UseConflictsResult {
+  readonly conflicts: readonly ConflictRecord[];
+  readonly rejections: readonly RejectionRecord[];
+  readonly refresh: () => void;
+}
+
+export function useConflicts(): UseConflictsResult {
+  const client = useSyncClient();
+  const [conflicts, setConflicts] = useState<readonly ConflictRecord[]>([]);
+  const [rejections, setRejections] = useState<readonly RejectionRecord[]>([]);
+  const readRef = useRef<() => void>(() => {});
+  const refresh = useCallback(() => readRef.current(), []);
+
+  useEffect(() => {
+    let cancelled = false;
+    const read = () => {
+      Promise.all([client.conflicts(), client.rejections()])
+        .then(([c, r]) => {
+          if (cancelled) return;
+          setConflicts(c);
+          setRejections(r);
+        })
+        .catch(() => {
+          /* transient read failure — the next batch re-reads */
+        });
+    };
+    readRef.current = read;
+    read();
+    const unsubscribe = client.onInvalidate(read);
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [client]);
+
+  return { conflicts, rejections, refresh };
+}

package/src/use-mutation.ts

@@ -0,0 +1,47 @@
+/**
+ * `useMutation` — submit local mutations (§6.1). Returns a stable `mutate`
+ * that appends to the outbox and applies the optimistic overlay immediately
+ * (§7.1); the referencing `useSyncQuery` re-runs on the resulting
+ * invalidation batch, so optimistic writes appear without a manual refetch.
+ * `mutate` resolves to the `clientCommitId` (track it against
+ * `useConflicts`/status). `isPending`/`error` cover the (usually instant)
+ * submit; server acceptance is observed through status + conflicts, not
+ * here.
+ */
+
+import type { MutationInput } from '@syncular/client';
+import { useCallback, useState } from 'react';
+import { useSyncClient } from './use-client';
+
+export interface UseMutationResult {
+  /** Submit mutations; resolves to the clientCommitId. */
+  mutate: (mutations: readonly MutationInput[]) => Promise<string>;
+  readonly isPending: boolean;
+  readonly error: Error | undefined;
+}
+
+export function useMutation(): UseMutationResult {
+  const client = useSyncClient();
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState<Error | undefined>(undefined);
+
+  const mutate = useCallback(
+    async (mutations: readonly MutationInput[]): Promise<string> => {
+      setIsPending(true);
+      setError(undefined);
+      try {
+        const id = await client.mutate(mutations);
+        return id;
+      } catch (err) {
+        const wrapped = err instanceof Error ? err : new Error(String(err));
+        setError(wrapped);
+        throw wrapped;
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [client],
+  );
+
+  return { mutate, isPending, error };
+}

package/src/use-named-query.ts

@@ -0,0 +1,66 @@
+/**
+ * `useNamedQuery` — the live-query hook for the generated NAMED-query tier
+ * (typegen's sqlc/SQLDelight rung). You author a `.sql` file; typegen emits a
+ * typed `NamedQuery` descriptor (`{ sql, tables, bind }`) + its `Row` type.
+ * This hook runs that descriptor live and reuses {@link useSyncQuery}'s
+ * invalidation machinery verbatim — the descriptor's `tables` set is the EXACT
+ * dependency set (typegen resolved it from the query's FROM/JOIN against the
+ * schema IR), so invalidation is precise with zero SQL-text heuristic and the
+ * row type is the query's own projection.
+ *
+ * ```ts
+ * import { listProjectTasksQuery } from './syncular.queries';
+ * const { rows } = useNamedQuery(listProjectTasksQuery, { projectId });
+ * //      ^ ListProjectTasksRow[]
+ * ```
+ *
+ * A param-less query takes no second argument. The descriptor is import-free
+ * (typegen emits its own `NamedQuery` type), so this hook depends only on the
+ * descriptor's structural shape — no generated-file import coupling.
+ */
+import type { SqlValue } from '@syncular/client';
+import {
+  type UseSyncQueryOptions,
+  type UseSyncQueryResult,
+  useSyncQuery,
+} from './use-sync-query';
+
+/** The structural shape typegen's `NamedQuery<Row, Params>` satisfies. */
+export interface NamedQueryDescriptor<Row, Params> {
+  readonly sql: string;
+  readonly tables: readonly string[];
+  readonly bind: (params: Params) => readonly SqlValue[];
+  /** Phantom row carrier (never read at runtime). */
+  readonly __row?: Row;
+}
+
+/** Run a param-less named query live. */
+export function useNamedQuery<Row>(
+  query: NamedQueryDescriptor<Row, undefined>,
+  options?: Omit<UseSyncQueryOptions, 'tables'>,
+): UseSyncQueryResult<Row>;
+/** Run a named query live with its typed params. */
+export function useNamedQuery<Row, Params>(
+  query: NamedQueryDescriptor<Row, Params>,
+  params: Params,
+  options?: Omit<UseSyncQueryOptions, 'tables'>,
+): UseSyncQueryResult<Row>;
+export function useNamedQuery<Row, Params>(
+  query: NamedQueryDescriptor<Row, Params>,
+  paramsOrOptions?: Params | Omit<UseSyncQueryOptions, 'tables'>,
+  maybeOptions?: Omit<UseSyncQueryOptions, 'tables'>,
+): UseSyncQueryResult<Row> {
+  // Overload disambiguation: a param-less query's second arg (if any) is the
+  // options object; a parameterized query's second arg is the params.
+  const hasParams = query.bind.length > 0;
+  const params = (hasParams ? paramsOrOptions : undefined) as Params;
+  const options = (hasParams ? maybeOptions : paramsOrOptions) as
+    | Omit<UseSyncQueryOptions, 'tables'>
+    | undefined;
+
+  const bound = query.bind(params) as readonly SqlValue[];
+  return useSyncQuery<Row>(query.sql, bound, {
+    ...options,
+    tables: query.tables,
+  });
+}

package/src/use-presence.ts

@@ -0,0 +1,40 @@
+/**
+ * `usePresence(scopeKey)` — the ephemeral peers present on a §8.6 scope key
+ * (join/update/leave). Reads the current peer list on mount and re-reads
+ * whenever presence on THIS key changes, via the client's `onPresence`
+ * subscription (the subscribable twin of the config callback). Presence is
+ * lost on disconnect (the server emits leave), so the list reflects only
+ * what the live socket has delivered.
+ */
+
+import type { PresencePeer } from '@syncular/client';
+import { useEffect, useState } from 'react';
+import { useSyncClient } from './use-client';
+
+export function usePresence(scopeKey: string): readonly PresencePeer[] {
+  const client = useSyncClient();
+  const [peers, setPeers] = useState<readonly PresencePeer[]>([]);
+
+  useEffect(() => {
+    let cancelled = false;
+    const read = () => {
+      Promise.resolve(client.presence(scopeKey))
+        .then((list) => {
+          if (!cancelled) setPeers(list);
+        })
+        .catch(() => {
+          /* transient — the next presence event re-reads */
+        });
+    };
+    read();
+    const unsubscribe = client.onPresence((changedKey) => {
+      if (changedKey === scopeKey) read();
+    });
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [client, scopeKey]);
+
+  return peers;
+}