@syncular/react 0.2.0

package/src/use-sync-query.ts

@@ -0,0 +1,223 @@
+/**
+ * `useSyncQuery` — a live local SQL query with fine-grained invalidation
+ * (TODO 3.1 / DESIGN-eviction I1–I4). The query runs once on mount, then
+ * re-runs ONLY when an invalidation event (one per apply batch, from the
+ * web-client choke point) touches a table this query depends on — never
+ * "re-run everything". Unrelated commits leave the result untouched (I4).
+ *
+ * Dependencies default to a conservative scan of the SQL text (FROM/JOIN
+ * identifiers, {@link inferTables}); pass the explicit `tables` option to
+ * override when the text cannot be read (dynamic SQL, views). `scopeKeys`
+ * further narrows re-runs to specific §3.1 scope keys when supplied — but
+ * a matching TABLE always re-runs (the table is the honest floor; a segment
+ * apply carries no per-row scope keys, so table-level is the safe default).
+ */
+
+import type { InvalidationEvent, SqlRow, SqlValue } from '@syncular/client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { inferTables } from './infer-tables';
+import { FrameScheduler, type HashedRows, reconcileRows } from './query-churn';
+import { useSyncClient } from './use-client';
+
+export interface UseSyncQueryOptions {
+  /**
+   * Tables this query depends on. Defaults to a conservative scan of `sql`.
+   * Pass explicitly to override the heuristic (the escape hatch).
+   */
+  readonly tables?: readonly string[];
+  /**
+   * When set, re-run only if the invalidation event's touched table is a
+   * dependency AND (the event has no scope keys — table-level, e.g. a
+   * bootstrap — OR it touches one of these §3.1 `prefix:value` keys). Leave
+   * unset to re-run on any dependency-table touch.
+   */
+  readonly scopeKeys?: readonly string[];
+  /** Skip running the query (e.g. while inputs are not ready). */
+  readonly enabled?: boolean;
+}
+
+export interface UseSyncQueryResult<Row> {
+  readonly rows: readonly Row[];
+  readonly isLoading: boolean;
+  readonly error: Error | undefined;
+  /** Force a re-run (identity-stable). */
+  readonly refresh: () => void;
+}
+
+function paramsKey(params: readonly SqlValue[] | undefined): string {
+  if (params === undefined || params.length === 0) return '';
+  // Stable identity for the params array so a new array with equal contents
+  // does not thrash the effect. Uint8Array is rare in query params; JSON of
+  // its byte view is stable enough for a dependency key.
+  return JSON.stringify(
+    params.map((p) => (p instanceof Uint8Array ? [...p] : p)),
+  );
+}
+
+function eventMatches(
+  event: InvalidationEvent,
+  tables: ReadonlySet<string>,
+  scopeKeys: readonly string[] | undefined,
+): boolean {
+  let tableHit = false;
+  for (const table of event.tables) {
+    if (tables.has(table)) {
+      tableHit = true;
+      break;
+    }
+  }
+  if (!tableHit) return false;
+  // Table matched. If the caller narrowed by scope keys, honor it — but a
+  // table-level event (no scope keys, e.g. a segment bootstrap or reset)
+  // always re-runs, because it carries no key to discriminate on.
+  if (scopeKeys === undefined || scopeKeys.length === 0) return true;
+  if (event.scopeKeys.size === 0) return true;
+  for (const key of scopeKeys) {
+    if (event.scopeKeys.has(key)) return true;
+  }
+  return false;
+}
+
+export function useSyncQuery<Row = SqlRow>(
+  sql: string,
+  params?: readonly SqlValue[],
+  options?: UseSyncQueryOptions,
+): UseSyncQueryResult<Row> {
+  const client = useSyncClient();
+  const enabled = options?.enabled ?? true;
+
+  const [rows, setRows] = useState<readonly Row[]>([]);
+  const [isLoading, setIsLoading] = useState<boolean>(enabled);
+  const [error, setError] = useState<Error | undefined>(undefined);
+
+  // The previous result plus its per-row content hashes, so a re-run can (a)
+  // skip setRows entirely when nothing changed (zero re-render) and (b) reuse
+  // unchanged row objects so memoized row components keep identity. Held in a
+  // ref — it is not render state; it's the reconcile baseline.
+  const prevRef = useRef<HashedRows<Row> | undefined>(undefined);
+
+  // The effects depend on stable PRIMITIVE keys (strings), never on the
+  // array/object identities a caller may recreate each render. Latest
+  // sql/params/scopeKeys/dep-tables are read inside the effects via refs.
+  const explicitTables = options?.tables;
+  const scopeKeys = options?.scopeKeys;
+  const key = `${sql} ${paramsKey(params)}`;
+  const scopeKeysKey = scopeKeys?.join(',') ?? '';
+
+  const sqlRef = useRef(sql);
+  sqlRef.current = sql;
+  const paramsRef = useRef(params);
+  paramsRef.current = params;
+  const scopeKeysRef = useRef(scopeKeys);
+  scopeKeysRef.current = scopeKeys;
+  const depTablesRef = useRef<Set<string>>(new Set());
+  depTablesRef.current =
+    explicitTables !== undefined ? new Set(explicitTables) : inferTables(sql);
+
+  // The single re-run routine, held in a ref so the scheduler and the
+  // subscription can call the LATEST closure without re-subscribing. It queries
+  // once, reconciles the fresh result against the previous, and only sets state
+  // when something actually changed (levers 1a/1b). A `cancelled` guard (reset
+  // per effect commit) makes a re-query from a stale mount a no-op.
+  const runRef = useRef<() => Promise<void>>();
+  const cancelledRef = useRef(false);
+
+  // `key`/`tick` are re-run triggers read via refs, not values used in the
+  // body — the pinned dep list re-runs the query on identity change.
+  const [tick, setTick] = useState(0);
+  const refresh = useCallback(() => setTick((n) => n + 1), []);
+
+  // One scheduler per hook instance, created lazily and re-run through the ref
+  // so a burst of invalidations coalesces to one query per frame (lever 2).
+  const schedulerRef = useRef<FrameScheduler>();
+  if (schedulerRef.current === undefined) {
+    schedulerRef.current = new FrameScheduler(() => runRef.current?.());
+  }
+
+  // Latest committed loading/error, tracked in refs so the run can set state
+  // ONLY on a real transition. React does not reliably bail on a no-op
+  // `setState(sameValue)` when other setters fire in the same batch (it can
+  // still commit a render), so lever 1a — zero re-render on unchanged data —
+  // requires us to guard every setter, not just setRows.
+  const isLoadingValueRef = useRef(isLoading);
+  isLoadingValueRef.current = isLoading;
+  const errorValueRef = useRef(error);
+  errorValueRef.current = error;
+
+  const setLoadingIfChanged = (value: boolean) => {
+    if (isLoadingValueRef.current !== value) {
+      isLoadingValueRef.current = value;
+      setIsLoading(value);
+    }
+  };
+  const setErrorIfChanged = (value: Error | undefined) => {
+    if (errorValueRef.current !== value) {
+      errorValueRef.current = value;
+      setError(value);
+    }
+  };
+
+  // Keep the run closure current every render (it closes over client via ref).
+  runRef.current = async () => {
+    if (cancelledRef.current) return;
+    try {
+      const result = await client.query(sqlRef.current, paramsRef.current);
+      if (cancelledRef.current) return;
+      const fresh = result as readonly unknown[] as readonly Row[];
+      const { next } = reconcileRows(prevRef.current, fresh);
+      if (next !== undefined) {
+        prevRef.current = next;
+        setRows(next.rows);
+      }
+      // next === undefined → whole result unchanged: NO setRows (zero re-render).
+      setErrorIfChanged(undefined);
+      setLoadingIfChanged(false);
+    } catch (err: unknown) {
+      if (cancelledRef.current) return;
+      setErrorIfChanged(err instanceof Error ? err : new Error(String(err)));
+      setLoadingIfChanged(false);
+    }
+  };
+
+  // Mount / query-identity / refresh: run immediately (not frame-coalesced —
+  // the caller changed the query, so it must reflect at once). Invalidations go
+  // through the scheduler instead.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: key/tick are intentional re-run triggers
+  useEffect(() => {
+    cancelledRef.current = false;
+    if (!enabled) {
+      setLoadingIfChanged(false);
+      return;
+    }
+    // A query-identity change invalidates the reconcile baseline (a different
+    // query's rows are not comparable to this one's), so reset it.
+    prevRef.current = undefined;
+    setLoadingIfChanged(true);
+    void runRef.current?.();
+    return () => {
+      cancelledRef.current = true;
+    };
+  }, [client, key, enabled, tick]);
+
+  // Subscribe once per client/enabled/query identity; a matching event asks the
+  // scheduler for a run (coalesced). `key`/`scopeKeysKey` re-key the sub.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: key/scopeKeysKey re-key the subscription intentionally
+  useEffect(() => {
+    if (!enabled) return;
+    const scheduler = schedulerRef.current;
+    const unsubscribe = client.onInvalidate((event) => {
+      if (eventMatches(event, depTablesRef.current, scopeKeysRef.current)) {
+        scheduler?.schedule();
+      }
+    });
+    return unsubscribe;
+  }, [client, enabled, key, scopeKeysKey]);
+
+  // Dispose the scheduler when the hook unmounts (drop any pending frame).
+  useEffect(() => {
+    const scheduler = schedulerRef.current;
+    return () => scheduler?.dispose();
+  }, []);
+
+  return { rows, isLoading, error, refresh };
+}

package/src/use-sync-status.ts

@@ -0,0 +1,87 @@
+/**
+ * `useSyncStatus` — the client's operational status: outbox depth,
+ * upgrading (§7.4.5), leaseState (§7.3.5), schemaFloor (§1.6), and
+ * syncNeeded (§8.4). Status is derived by polling the normalized accessors
+ * after every apply batch (invalidation is the natural "something changed"
+ * signal) plus an initial read; `refresh()` re-reads on demand.
+ *
+ * `online` is not a protocol concept the client exposes directly (§1.3
+ * transport-owned), so it is reported as `undefined` unless a future
+ * accessor lands — the hook surfaces what the core actually knows, never a
+ * guessed value.
+ */
+
+import type { LeaseState, SchemaFloor } from '@syncular/client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useSyncClient } from './use-client';
+
+export interface SyncStatus {
+  /** Pending outbox commits (unpushed local writes). */
+  readonly outbox: number;
+  /** §7.4.5: a schema-bump reset + first re-bootstrap is in flight. */
+  readonly upgrading: boolean;
+  /** §7.3.5: opaque auth-lease state, or undefined. */
+  readonly leaseState: LeaseState | undefined;
+  /** §1.6: server-declared schema floor (syncing stopped), or undefined. */
+  readonly schemaFloor: SchemaFloor | undefined;
+  /** §8.4: the host loop should run a pull soon. */
+  readonly syncNeeded: boolean;
+  /** True until the first status read resolves. */
+  readonly isLoading: boolean;
+  readonly refresh: () => void;
+}
+
+const INITIAL: Omit<SyncStatus, 'refresh'> = {
+  outbox: 0,
+  upgrading: false,
+  leaseState: undefined,
+  schemaFloor: undefined,
+  syncNeeded: false,
+  isLoading: true,
+};
+
+export function useSyncStatus(): SyncStatus {
+  const client = useSyncClient();
+  const [state, setState] = useState(INITIAL);
+  // `refresh` re-reads through a ref set by the effect (identity-stable, no
+  // tick state — biome-clean deps).
+  const readRef = useRef<() => void>(() => {});
+  const refresh = useCallback(() => readRef.current(), []);
+
+  useEffect(() => {
+    let cancelled = false;
+    const read = () => {
+      Promise.all([
+        client.pendingCommits(),
+        client.upgrading(),
+        client.leaseState(),
+        client.schemaFloor(),
+        client.syncNeeded(),
+      ])
+        .then(([pending, upgrading, leaseState, schemaFloor, syncNeeded]) => {
+          if (cancelled) return;
+          setState({
+            outbox: pending.length,
+            upgrading,
+            leaseState,
+            schemaFloor,
+            syncNeeded,
+            isLoading: false,
+          });
+        })
+        .catch(() => {
+          if (!cancelled) setState((s) => ({ ...s, isLoading: false }));
+        });
+    };
+    readRef.current = read;
+    read();
+    // Re-read on every apply batch — the "state changed" edge.
+    const unsubscribe = client.onInvalidate(read);
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [client]);
+
+  return { ...state, refresh };
+}

package/src/use-typed-query.ts

@@ -0,0 +1,67 @@
+/**
+ * `useTypedQuery` — the typed twin of {@link useSyncQuery}. You write a
+ * Kysely query builder; the hook compiles it to SQL, runs it live against the
+ * client, and extracts its `{tables}` dependency set from the compiled query's
+ * AST automatically — so invalidation is exact (no SQL-text heuristic) and
+ * fully typed by the schema's generated `Database` interface.
+ *
+ * ```ts
+ * const { rows } = useTypedQuery<Database, Pick<TodosRow, 'id' | 'title'>>(
+ *   (db) => db.selectFrom('todos').select(['id', 'title']).where('list_id', '=', listId),
+ *   [listId],
+ * );
+ * ```
+ *
+ * It reuses {@link useSyncQuery}'s invalidation machinery verbatim — the only
+ * additions are compilation and AST-based table extraction. Read-only, like
+ * the dialect: a write builder throws at execution (SPEC §7.1 → use
+ * `useMutation`). `@syncular/kysely` and `kysely` are PEER dependencies of
+ * this package (both are `optional`), so apps that only use `useSyncQuery`
+ * never pull Kysely in.
+ */
+
+import type { SqlRow, SqlValue } from '@syncular/client';
+import { createSyncularKysely, extractTables } from '@syncular/kysely';
+import type { Compilable, CompiledQuery, Kysely } from 'kysely';
+import { useMemo } from 'react';
+import { useSyncClient } from './use-client';
+import {
+  type UseSyncQueryOptions,
+  type UseSyncQueryResult,
+  useSyncQuery,
+} from './use-sync-query';
+
+/**
+ * Build a live typed query. `build` receives a `Kysely<Database>` bound to the
+ * context client and returns any compilable query builder. `deps` re-keys the
+ * builder the same way a `useEffect` dep array does (values the query closes
+ * over, e.g. filter inputs). `options.enabled`/`scopeKeys` pass through; the
+ * `{tables}` set is derived from the compiled query, never guessed.
+ */
+export function useTypedQuery<Database, Row = SqlRow>(
+  build: (db: Kysely<Database>) => Compilable<Row>,
+  deps: readonly unknown[] = [],
+  options?: Omit<UseSyncQueryOptions, 'tables'>,
+): UseSyncQueryResult<Row> {
+  const client = useSyncClient();
+
+  // One Kysely instance per client identity — the dialect drives the same
+  // normalized `query` surface the other hooks use, so every host works.
+  const db = useMemo(() => createSyncularKysely<Database>(client), [client]);
+
+  // Compile on the deps the caller declared. The compiled query yields SQL +
+  // parameters (for execution) and its AST (for exact table extraction).
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `deps` is the caller-declared re-key, `build`/`db` are stable-by-design
+  const compiled: CompiledQuery<Row> = useMemo(
+    () => build(db).compile(),
+    [db, ...deps],
+  );
+
+  const tables = useMemo(() => extractTables(compiled), [compiled]);
+
+  return useSyncQuery<Row>(
+    compiled.sql,
+    compiled.parameters as readonly SqlValue[],
+    { ...options, tables },
+  );
+}

package/src/use-window.ts

@@ -0,0 +1,88 @@
+/**
+ * `useWindow(base)` — the windowed-sync surface for a component
+ * (SPEC.md §4.8 / DESIGN-eviction.md W1, I3). It manages the live window
+ * units for a base and exposes the **completeness oracle**: which scope
+ * values are held locally in full, so a consumer can render "this data may
+ * be partial" honestly instead of silently serving a partial replica as
+ * complete.
+ *
+ * - `setWindow(units)` swaps the live set (added units bootstrap via the
+ *   image lane; removed units are evicted, fused with unsubscription).
+ * - `units` is the current windowed-in set (re-read on mount and whenever
+ *   the base's table is invalidated — so a deferred eviction draining, or
+ *   a re-entry bootstrapping, updates the verdict).
+ * - `isComplete(unit)` is the per-value verdict: a live query whose scope
+ *   footprint includes a non-`isComplete` unit is a **window miss** — widen
+ *   or show partial, never claim complete.
+ */
+import type { WindowBase } from '@syncular/client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useSyncClient } from './use-client';
+
+export interface UseWindowResult {
+  /** The scope values currently windowed-in for this base. */
+  readonly units: readonly string[];
+  /** Set the live units (widen/shrink diff, §4.8). */
+  readonly setWindow: (units: readonly string[]) => Promise<void>;
+  /** True iff `unit` is windowed-in (answerable in full locally, I3). */
+  readonly isComplete: (unit: string) => boolean;
+}
+
+export function useWindow(base: WindowBase): UseWindowResult {
+  const client = useSyncClient();
+  const [units, setUnits] = useState<readonly string[]>([]);
+
+  // A stable key so the effects re-run only when the base identity changes,
+  // not on every render's fresh object. The latest `base` is read via a ref
+  // inside the closures (the useSyncQuery pattern), so the dep list stays on
+  // primitive keys.
+  const baseKey = `${base.table} ${base.variable} ${JSON.stringify(
+    base.fixedScopes ?? {},
+  )} ${base.params ?? ''}`;
+  const baseRef = useRef(base);
+  baseRef.current = base;
+
+  // `baseKey` re-keys the effect without being read in the body (biome cannot
+  // see the ref indirection) — the dep list is pinned deliberately.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: baseKey re-keys the effect for a fresh base object
+  useEffect(() => {
+    let cancelled = false;
+    const read = () => {
+      Promise.resolve(client.windowState(baseRef.current))
+        .then((state) => {
+          if (!cancelled) setUnits(state.units);
+        })
+        .catch(() => {
+          /* transient — the next invalidation re-reads */
+        });
+    };
+    read();
+    // Re-read when the base's table changes locally: a deferred eviction
+    // (E1) completing or a re-entry bootstrapping both invalidate it.
+    const unsubscribe = client.onInvalidate((event) => {
+      if (event.tables.has(baseRef.current.table)) read();
+    });
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [client, baseKey]);
+
+  const setWindow = useCallback(
+    (next: readonly string[]) => {
+      const result = Promise.resolve(client.setWindow(baseRef.current, next));
+      // Optimistically reflect the new set; the invalidation-driven re-read
+      // reconciles against the registry (e.g. a pinned unit lingering).
+      setUnits(next);
+      return result;
+    },
+    [client],
+  );
+
+  const isComplete = useCallback(
+    (unit: string) => units.includes(unit),
+    [units],
+  );
+
+  return { units, setWindow, isComplete };
+}