@syncular/react 0.4.1 → 0.5.0

package/src/use-mutation.ts

@@ -1,47 +1,148 @@
-/**
- * `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 `useRawSql` 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 { useCallback, useRef, useState } from 'react';
 import { useSyncClient } from './use-client';
 
+export interface SyncTableDescriptor<Row, Insert, Update, Id> {
+  readonly name: string;
+  readonly primaryKey: keyof Row & string;
+  readonly physicalPrimaryKey: string;
+  readonly __row?: Row;
+  readonly __insert?: Insert;
+  readonly __update?: Update;
+  readonly __id?: Id;
+}
+
+export interface UseMutationOptions {
+  readonly onSuccess?: (clientCommitId: string) => void;
+  readonly onError?: (error: Error) => void;
+}
+
 export interface UseMutationResult {
-  /** Submit mutations; resolves to the clientCommitId. */
   mutate: (mutations: readonly MutationInput[]) => Promise<string>;
+  readonly pendingCount: number;
   readonly isPending: boolean;
   readonly error: Error | undefined;
+  readonly resetError: () => void;
 }
 
-export function useMutation(): UseMutationResult {
+export interface UseTableMutationResult<Insert, Update, Id>
+  extends UseMutationResult {
+  readonly upsert: (values: Insert, baseVersion?: number) => Promise<string>;
+  readonly patch: (
+    id: Id,
+    partial: Partial<Update>,
+    baseVersion?: number,
+  ) => Promise<string>;
+  readonly remove: (id: Id, baseVersion?: number) => Promise<string>;
+}
+
+export function useMutation(options?: UseMutationOptions): UseMutationResult;
+export function useMutation<Row, Insert, Update, Id>(
+  table: SyncTableDescriptor<Row, Insert, Update, Id>,
+  options?: UseMutationOptions,
+): UseTableMutationResult<Insert, Update, Id>;
+export function useMutation<Row, Insert, Update, Id>(
+  tableOrOptions?:
+    | SyncTableDescriptor<Row, Insert, Update, Id>
+    | UseMutationOptions,
+  maybeOptions?: UseMutationOptions,
+): UseMutationResult | UseTableMutationResult<Insert, Update, Id> {
   const client = useSyncClient();
-  const [isPending, setIsPending] = useState(false);
+  const table =
+    tableOrOptions !== undefined && 'name' in tableOrOptions
+      ? tableOrOptions
+      : undefined;
+  const options =
+    table === undefined
+      ? (tableOrOptions as UseMutationOptions | undefined)
+      : maybeOptions;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const [pendingCount, setPendingCount] = useState(0);
   const [error, setError] = useState<Error | undefined>(undefined);
+  const resetError = useCallback(() => setError(undefined), []);
 
-  const mutate = useCallback(
-    async (mutations: readonly MutationInput[]): Promise<string> => {
-      setIsPending(true);
+  const run = useCallback(
+    async (operation: () => Promise<string>): Promise<string> => {
+      setPendingCount((count) => count + 1);
       setError(undefined);
       try {
-        const id = await client.mutate(mutations);
+        const id = await operation();
+        optionsRef.current?.onSuccess?.(id);
         return id;
-      } catch (err) {
-        const wrapped = err instanceof Error ? err : new Error(String(err));
+      } catch (caught) {
+        const wrapped =
+          caught instanceof Error ? caught : new Error(String(caught));
         setError(wrapped);
+        optionsRef.current?.onError?.(wrapped);
         throw wrapped;
       } finally {
-        setIsPending(false);
+        setPendingCount((count) => Math.max(0, count - 1));
       }
     },
-    [client],
+    [],
   );
-
-  return { mutate, isPending, error };
+  const mutate = useCallback(
+    (mutations: readonly MutationInput[]) =>
+      run(() => client.mutate(mutations)),
+    [client, run],
+  );
+  const base: UseMutationResult = {
+    mutate,
+    pendingCount,
+    isPending: pendingCount > 0,
+    error,
+    resetError,
+  };
+  const upsert = useCallback(
+    (values: Insert, baseVersion?: number): Promise<string> => {
+      if (table === undefined)
+        throw new Error('table mutation descriptor missing');
+      return mutate([
+        {
+          table: table.name,
+          op: 'upsert',
+          values: values as Readonly<Record<string, unknown>>,
+          ...(baseVersion !== undefined ? { baseVersion } : {}),
+        },
+      ]);
+    },
+    [mutate, table],
+  );
+  const patch = useCallback(
+    (
+      id: Id,
+      partial: Partial<Update>,
+      baseVersion?: number,
+    ): Promise<string> => {
+      if (table === undefined)
+        throw new Error('table mutation descriptor missing');
+      return run(() =>
+        client.patch(
+          table.name,
+          String(id),
+          partial as Readonly<Record<string, unknown>>,
+          baseVersion !== undefined ? { baseVersion } : undefined,
+        ),
+      );
+    },
+    [client, run, table],
+  );
+  const remove = useCallback(
+    (id: Id, baseVersion?: number): Promise<string> => {
+      if (table === undefined)
+        throw new Error('table mutation descriptor missing');
+      return mutate([
+        {
+          table: table.name,
+          op: 'delete',
+          rowId: String(id),
+          ...(baseVersion !== undefined ? { baseVersion } : {}),
+        },
+      ]);
+    },
+    [mutate, table],
+  );
+  if (table === undefined) return base;
+  return { ...base, upsert, patch, remove };
 }

package/src/use-query.ts

@@ -18,7 +18,11 @@
  * (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 {
+  QueryDependency,
+  SqlValue,
+  WindowCoverage,
+} from '@syncular/client';
 import {
   type UseRawSqlOptions,
   type UseRawSqlResult,
@@ -27,6 +31,8 @@ import {
 
 /** The structural shape typegen's `NamedQuery<Row, Params>` satisfies. */
 export interface NamedQueryDescriptor<Row, Params> {
+  readonly id: string;
+  readonly hasParams: boolean;
   readonly sql: string;
   readonly tables: readonly string[];
   readonly bind: (params: Params) => readonly SqlValue[];
@@ -34,38 +40,51 @@ export interface NamedQueryDescriptor<Row, Params> {
    * generate-time-checked allowlist (identifiers never come from runtime
    * input). Absent on knob-less queries — `sql` is the whole statement. */
   readonly sqlFor?: (params: Params) => string;
+  readonly dependencies: (params: Params) => readonly QueryDependency[];
+  readonly coverage: (params: Params) => readonly WindowCoverage[];
+  readonly rowKey?: (row: Row) => readonly SqlValue[];
   /** Phantom row carrier (never read at runtime). */
   readonly __row?: Row;
 }
 
+type NamedQueryOptions<Row> = Omit<
+  UseRawSqlOptions<Row>,
+  'tables' | 'scopeKeys' | 'dependencies' | 'coverage' | 'rowKey' | 'id'
+>;
+
 /** Run a param-less named query live. */
 export function useQuery<Row>(
   query: NamedQueryDescriptor<Row, undefined>,
-  options?: Omit<UseRawSqlOptions, 'tables'>,
+  options?: NamedQueryOptions<Row>,
 ): UseRawSqlResult<Row>;
 /** Run a named query live with its typed params. */
 export function useQuery<Row, Params>(
   query: NamedQueryDescriptor<Row, Params>,
   params: Params,
-  options?: Omit<UseRawSqlOptions, 'tables'>,
+  options?: NamedQueryOptions<Row>,
 ): UseRawSqlResult<Row>;
 export function useQuery<Row, Params>(
   query: NamedQueryDescriptor<Row, Params>,
-  paramsOrOptions?: Params | Omit<UseRawSqlOptions, 'tables'>,
-  maybeOptions?: Omit<UseRawSqlOptions, 'tables'>,
+  paramsOrOptions?: Params | NamedQueryOptions<Row>,
+  maybeOptions?: NamedQueryOptions<Row>,
 ): UseRawSqlResult<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 hasParams = query.hasParams;
   const params = (hasParams ? paramsOrOptions : undefined) as Params;
   const options = (hasParams ? maybeOptions : paramsOrOptions) as
-    | Omit<UseRawSqlOptions, 'tables'>
+    | NamedQueryOptions<Row>
     | undefined;
 
   const bound = query.bind(params) as readonly SqlValue[];
   const sql = query.sqlFor === undefined ? query.sql : query.sqlFor(params);
+  const dependencies = query.dependencies(params);
+  const coverage = query.coverage(params);
   return useRawSql<Row>(sql, bound, {
     ...options,
-    tables: query.tables,
+    id: query.id,
+    dependencies,
+    coverage,
+    ...(query.rowKey !== undefined ? { rowKey: query.rowKey } : {}),
   });
 }

package/src/use-raw-sql.ts

@@ -1,235 +1,106 @@
-/**
- * `useRawSql` — 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 {
+  canonicalValue,
+  type LiveQueryPhase,
+  type QueryDependency,
+  type SqlRow,
+  type SqlValue,
+  type WindowCoverage,
+} from '@syncular/client';
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
 import { inferTables } from './infer-tables';
-import { FrameScheduler, type HashedRows, reconcileRows } from './query-churn';
-import { useSyncClient } from './use-client';
+import { useReactiveStore } from './use-client';
 
-export interface UseRawSqlOptions {
-  /**
-   * Tables this query depends on. Defaults to a conservative scan of `sql`.
-   * Pass explicitly to override the heuristic (the escape hatch).
-   */
+export interface UseRawSqlOptions<Row = SqlRow> {
+  /** Legacy table list; prefer table-associated `dependencies`. */
   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.
-   */
+  /** Legacy narrowing applied to every table in `tables`. */
   readonly scopeKeys?: readonly string[];
-  /** Skip running the query (e.g. while inputs are not ready). */
+  readonly dependencies?: readonly QueryDependency[];
+  readonly coverage?: readonly WindowCoverage[];
+  readonly rowKey?: (row: Row) => readonly SqlValue[];
+  /** Generated coverage claims its windows by default. */
+  readonly claimCoverage?: boolean;
   readonly enabled?: boolean;
+  /** Stable identity override for a raw query cache entry. */
+  readonly id?: string;
 }
 
 export interface UseRawSqlResult<Row> {
   readonly rows: readonly Row[];
+  readonly phase: LiveQueryPhase;
+  readonly revision: bigint | undefined;
   readonly isLoading: boolean;
+  readonly isRefreshing: 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)),
-  );
-}
+const DISABLED = {
+  rows: [],
+  phase: 'ready',
+  revision: undefined,
+  error: undefined,
+  isRefreshing: false,
+} as const;
 
-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;
-}
+const noSubscribe = (): (() => void) => () => {};
 
 export function useRawSql<Row = SqlRow>(
   sql: string,
   params?: readonly SqlValue[],
-  options?: UseRawSqlOptions,
+  options?: UseRawSqlOptions<Row>,
 ): UseRawSqlResult<Row> {
-  const client = useSyncClient();
+  const store = useReactiveStore();
   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);
-    }
+  const inferred = options?.tables ?? [...inferTables(sql)];
+  const dependencies =
+    options?.dependencies ??
+    inferred.map((table) => ({
+      table,
+      ...(options?.scopeKeys !== undefined
+        ? { scopeKeys: options.scopeKeys }
+        : {}),
+    }));
+  const coverage = options?.coverage ?? [];
+  const identity = canonicalValue({
+    sql,
+    params: params ?? [],
+    dependencies,
+    coverage,
+    ...(options?.id !== undefined ? { id: options.id } : {}),
+  });
+  // `identity` canonically contains every value-shaped input. Depending on
+  // the caller's array/object references would defeat value-stable query
+  // identity; executable rowKey intentionally follows function identity.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: canonical value identity is the dependency
+  const entry = useMemo(
+    () =>
+      store.query<Row>({
+        id: options?.id ?? `raw:${identity}`,
+        sql,
+        ...(params !== undefined ? { params } : {}),
+        dependencies,
+        ...(coverage.length > 0 ? { coverage } : {}),
+        ...(options?.rowKey !== undefined ? { rowKey: options.rowKey } : {}),
+        claimCoverage: options?.claimCoverage ?? true,
+      }),
+    [store, identity, options?.rowKey],
+  );
+  const snapshot = useSyncExternalStore(
+    enabled ? entry.subscribe : noSubscribe,
+    enabled ? entry.getSnapshot : () => DISABLED,
+    enabled ? entry.getSnapshot : () => DISABLED,
+  );
+  const refresh = useCallback(() => {
+    if (enabled) entry.refresh();
+  }, [enabled, entry]);
+  return {
+    rows: snapshot.rows as readonly Row[],
+    phase: snapshot.phase,
+    revision: snapshot.revision,
+    isLoading: snapshot.phase === 'loading',
+    isRefreshing: snapshot.isRefreshing,
+    error: snapshot.error,
+    refresh,
   };
-
-  // 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. The
-  // scheduler is read from the ref AT EVENT TIME (never captured at effect
-  // setup): the lifecycle effect below may replace it on a remount, and a
-  // captured disposed instance would swallow every schedule() silently.
-  // biome-ignore lint/correctness/useExhaustiveDependencies: key/scopeKeysKey re-key the subscription intentionally
-  useEffect(() => {
-    if (!enabled) return;
-    const unsubscribe = client.onInvalidate((event) => {
-      if (eventMatches(event, depTablesRef.current, scopeKeysRef.current)) {
-        schedulerRef.current?.schedule();
-      }
-    });
-    return unsubscribe;
-  }, [client, enabled, key, scopeKeysKey]);
-
-  // Scheduler lifecycle. Under StrictMode (and any future fiber remount)
-  // React runs mount → cleanup → mount on the SAME hook instance: the cleanup
-  // disposes the scheduler, so the setup must RE-CREATE it — the render-time
-  // lazy init above never runs again (the ref is non-undefined), and a
-  // disposed scheduler turns every later invalidation into a silent no-op
-  // that freezes the live query forever.
-  useEffect(() => {
-    if (schedulerRef.current === undefined) {
-      schedulerRef.current = new FrameScheduler(() => runRef.current?.());
-    }
-    return () => {
-      schedulerRef.current?.dispose();
-      schedulerRef.current = undefined;
-    };
-  }, []);
-
-  return { rows, isLoading, error, refresh };
 }