@gleanql/client 0.1.0

package/src/proxy.ts

@@ -0,0 +1,288 @@
+import { argAliasSuffix, canonicalArgs, type ArgMap, type ArgValue, type SchemaModel } from "@gleanql/core";
+import type { GraphRef, FieldValue } from "./cache.js";
+import type { GraphRuntime } from "./runtime.js";
+
+/**
+ * Runtime graph proxies.
+ *
+ * The compiler statically infers what fields a route needs; this layer is what
+ * makes ordinary reads (`product.title`, `product.featuredImage?.url`,
+ * `collection.products({ first: 12 }).nodes`) actually *execute* at runtime.
+ *
+ * A graph value is a Proxy over a cache `GraphRef`. Property access routes
+ * through the Suspense-aware runtime:
+ *  - scalar field  -> `runtime.readField(ref, key)` (sync hit, or throws a promise)
+ *  - object field  -> the stored `GraphRef`, re-wrapped as a child proxy
+ *  - list field    -> an array of child proxies/scalars
+ *  - callable field -> a function `(args) => value` (field arguments)
+ *
+ * The proxy is intentionally transparent: parent components pass it as a normal
+ * prop, child components read fields off it, and nothing in userland sees a ref,
+ * a selection object, or a promise (the promise is thrown to Suspense).
+ */
+
+/** Escape-hatch / brand keys exposed on every graph proxy. */
+export const GRAPH_REF = Symbol.for("graph.ref");
+export const GRAPH_TYPE = Symbol.for("graph.type");
+export const GRAPH_TRAIL = Symbol.for("graph.trail");
+
+/**
+ * Read tracking for fine-grained reactivity. Every field read records the record
+ * key it touched into the active tracker; the tracking hook's `useSyncExternalStore`
+ * snapshot is then a digest of just those records' versions.
+ *
+ * Attribution is primarily PER BINDING: `useGlean` binds the graph with its render's
+ * own `affected` set (see `GraphBinding.tracker`), so reads through that render's
+ * proxies record into that set directly — fiber-local, safe under concurrent/
+ * interleaved rendering. This ambient global is only a fallback for proxies created
+ * without a binding tracker (the server / isomorphic accessor), where no re-render
+ * depends on attribution.
+ */
+let currentTracker: Set<string> | null = null;
+
+/** Install (or clear) the active read tracker. Returns the previous one. */
+export function setReadTracker(tracker: Set<string> | null): Set<string> | null {
+  const prev = currentTracker;
+  currentTracker = tracker;
+  return prev;
+}
+
+/** One object-field hop from a Query root: the field name + the args it was called with. */
+export interface PathStep {
+  readonly name: string;
+  readonly args?: Record<string, unknown>;
+}
+
+/** The hidden selection token (brief: `product.selection`). */
+export interface GraphSelection {
+  readonly ref: GraphRef;
+  readonly type: string;
+}
+
+/** A value is a `GraphRef` if it carries entity identity or a path. */
+export function isGraphRef(value: unknown): value is GraphRef {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const v = value as Record<string, unknown>;
+  return (v.__typename != null && v.id != null) || typeof v.path === "string";
+}
+
+function toArgValue(value: unknown): ArgValue {
+  if (value === null) return { kind: "literal", value: null };
+  if (Array.isArray(value)) return { kind: "list", items: value.map(toArgValue) };
+  if (typeof value === "object") {
+    return { kind: "object", fields: Object.entries(value as object).map(([k, v]) => [k, toArgValue(v)] as const) };
+  }
+  return { kind: "literal", value: value as string | number | boolean };
+}
+
+/** Plain runtime args (`{ first: 12 }`) -> IR `ArgMap`, reusing core's canonicalization. */
+export function toArgMap(args: Record<string, unknown> | undefined): ArgMap {
+  if (!args) return [];
+  return Object.entries(args).map(([k, v]) => [k, toArgValue(v)] as const);
+}
+
+/**
+ * Candidate response keys for a (possibly callable) field, most-specific first.
+ * A callable field that coexisted with a differently-argued sibling was aliased
+ * by the merger (`url_transformMaxWidth300`); a lone callable field keeps its
+ * plain name. The proxy tries the alias key first, then the plain name, which
+ * is correct for both shapes without the proxy having to know about conflicts.
+ */
+export function responseKeyCandidates(name: string, argMap: ArgMap): readonly string[] {
+  if (argMap.length === 0) return [name];
+  const suffix = argAliasSuffix(argMap);
+  return suffix ? [`${name}_${suffix}`, name] : [name];
+}
+
+export interface GraphBinding {
+  readonly schema: SchemaModel;
+  /** Resolve the active runtime lazily (per request on the server). */
+  readonly getRuntime: () => GraphRuntime;
+  /**
+   * Per-binding read tracker. When a `useGlean` render binds the graph with its own
+   * `affected` set, every proxy created from this binding records reads into THAT set
+   * — not the ambient global — so concurrent/interleaved renders can't misattribute.
+   * Absent (server / isomorphic accessor) → reads fall back to the ambient tracker.
+   */
+  readonly tracker?: Set<string>;
+}
+
+interface ProxyState {
+  readonly binding: GraphBinding;
+  readonly ref: GraphRef;
+  readonly type: string;
+  /** Object-field path from a Query root to this value (drives `usePaginated`/`fetchMore`). */
+  readonly trail: readonly PathStep[];
+}
+
+/** Read a field on a ref, resolving the right response key, and wrap object/list results. */
+function readField(state: ProxyState, fieldName: string, args?: Record<string, unknown>): unknown {
+  const { binding, ref, type } = state;
+  const runtime = binding.getRuntime();
+  const fieldDef = binding.schema.getField(type, fieldName);
+  const argMap = toArgMap(args);
+  const candidates = responseKeyCandidates(fieldName, argMap);
+
+  // Prefer an already-cached candidate key; otherwise read the most specific one
+  // (which suspends + enqueues a missing-field fetch under that stable key).
+  let key = candidates[0]!;
+  for (const candidate of candidates) {
+    if (runtime.cache.getField(ref, candidate).status === "ready") {
+      key = candidate;
+      break;
+    }
+  }
+
+  // Record this exact field as read (field-level granularity), so the rendering
+  // component re-renders only when a field IT read changes — not on any write to the
+  // record. Tracked before the read so a currently-missing field still re-renders
+  // when it lands. Guard: refs always carry identity or a path here. Prefer the
+  // binding's own set (fiber-scoped, set by useGlean) over the ambient global.
+  const tracker = binding.tracker ?? currentTracker;
+  if (tracker) {
+    try {
+      tracker.add(runtime.cache.fieldTrackingKey(runtime.cache.recordKey(ref), key));
+    } catch {
+      /* ref without identity/path — not trackable */
+    }
+  }
+
+  const raw = runtime.readField(ref, key);
+  const childTrail = [...state.trail, { name: fieldName, ...(args ? { args } : {}) }];
+  return wrap(binding, raw, fieldDef?.type, childTrail);
+}
+
+/** Wrap a raw cache value as a child proxy (object), array of proxies (list), or scalar. */
+function wrap(binding: GraphBinding, value: FieldValue, declaredType: string | undefined, trail: readonly PathStep[]): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => wrap(binding, item, declaredType, trail));
+  }
+  if (isGraphRef(value)) {
+    // For union/interface fields the concrete type comes from the ref's __typename.
+    const type = (value.__typename as string | undefined) ?? declaredType ?? "Unknown";
+    return createGraphProxy(binding, value, type, trail);
+  }
+  return value;
+}
+
+const handler: ProxyHandler<{ state: ProxyState }> = {
+  get(target, prop) {
+    const { state } = target;
+    if (prop === GRAPH_REF) return state.ref;
+    if (prop === GRAPH_TYPE) return state.type;
+    if (prop === GRAPH_TRAIL) return state.trail;
+    if (prop === "selection") {
+      return { ref: state.ref, type: state.type } satisfies GraphSelection;
+    }
+    if (typeof prop === "symbol") return undefined;
+    if (prop === "__typename") {
+      // Identity field: prefer the ref's own typename, fall back to a cache read.
+      return state.ref.__typename ?? readField(state, "__typename");
+    }
+
+    const fieldName = prop;
+    const fieldDef = state.binding.schema.getField(state.type, fieldName);
+
+    // Callable field (has declared arguments): return a function `(args) => value`.
+    if (fieldDef?.args && fieldDef.args.length > 0) {
+      return (args?: Record<string, unknown>) => readField(state, fieldName, args);
+    }
+    return readField(state, fieldName);
+  },
+  has(target, prop) {
+    if (prop === GRAPH_REF || prop === GRAPH_TYPE || prop === GRAPH_TRAIL || prop === "selection") return true;
+    return typeof prop === "string" && !!target.state.binding.schema.getField(target.state.type, prop);
+  },
+  set() {
+    throw new Error("graph values are read-only");
+  },
+  ownKeys() {
+    // Graph values are not enumerable/spreadable (brief: spreading is a diagnostic).
+    return [];
+  },
+};
+
+export function createGraphProxy(binding: GraphBinding, ref: GraphRef, type: string, trail: readonly PathStep[] = []): unknown {
+  return new Proxy({ state: { binding, ref, type, trail } }, handler);
+}
+
+/** Read the hidden selection token off any graph proxy. */
+export function selectionOf(value: unknown): GraphSelection | undefined {
+  if (value && typeof value === "object" && GRAPH_REF in value) {
+    const v = value as { [GRAPH_REF]: GraphRef; [GRAPH_TYPE]: string };
+    return { ref: v[GRAPH_REF], type: v[GRAPH_TYPE] };
+  }
+  return undefined;
+}
+
+/** Read the root→value path off any graph proxy (for `usePaginated`/`fetchMore`). */
+export function trailOf(value: unknown): readonly PathStep[] | undefined {
+  if (value && typeof value === "object" && GRAPH_TRAIL in value) {
+    return (value as { [GRAPH_TRAIL]: readonly PathStep[] })[GRAPH_TRAIL];
+  }
+  return undefined;
+}
+
+// --- Bound graph ----------------------------------------------------------
+
+/**
+ * The runtime `graph` object: one callable per Query root field, each returning
+ * a graph proxy. Root values resolve to the ref the operation seeded (via the
+ * `roots` map) so reads hit the warm cache; an unseeded root falls back to a
+ * path-identity ref and suspends.
+ */
+export interface BoundGraph {
+  readonly [rootField: string]: (args?: Record<string, unknown>) => unknown;
+}
+
+export interface BindGraphOptions {
+  readonly schema: SchemaModel;
+  readonly getRuntime: () => GraphRuntime;
+  /**
+   * Root field -> seeded ref, from `runRoute`/`seedResult`. A function form is
+   * resolved per call, so the bound graph can follow page-current roots that
+   * change across client navigations (the RSC hydrator updates them per nav).
+   */
+  readonly roots?:
+    | Record<string, FieldValue>
+    | (() => Record<string, FieldValue> | undefined);
+  /**
+   * A read tracker scoping this binding's reads to one render (see `GraphBinding`).
+   * `useGlean` passes its render's `affected` set so attribution is fiber-local;
+   * the server/isomorphic accessor omits it.
+   */
+  readonly tracker?: Set<string>;
+}
+
+export function bindGraph(options: BindGraphOptions): BoundGraph {
+  const binding: GraphBinding = {
+    schema: options.schema,
+    getRuntime: options.getRuntime,
+    ...(options.tracker ? { tracker: options.tracker } : {}),
+  };
+  const queryType = options.schema.queryType;
+  const rootFields = options.schema.getType(queryType)?.fields ?? {};
+
+  const graph: Record<string, (args?: Record<string, unknown>) => unknown> = {};
+  for (const [fieldName, fieldDef] of Object.entries(rootFields)) {
+    graph[fieldName] = (args?: Record<string, unknown>) => {
+      const rootsNow =
+        typeof options.roots === "function" ? options.roots() : options.roots;
+      const seeded = rootsNow?.[fieldName];
+      const trail: PathStep[] = [{ name: fieldName, ...(args ? { args } : {}) }];
+      // A list root (`type Query { todos: [Todo!] }`) seeds an array of refs — wrap
+      // each as a child proxy so `glean.todos().map(...)` works without an object
+      // wrapper. Unseeded (pre-hydration / not yet fetched) -> empty array; the
+      // page-pointer re-render fills it once the operation resolves.
+      if (fieldDef.list) {
+        const items = Array.isArray(seeded) ? seeded : [];
+        return items.map((item) => wrap(binding, item, fieldDef.type, trail));
+      }
+      const ref: GraphRef = isGraphRef(seeded)
+        ? seeded
+        : { path: `${queryType}.${fieldName}(${canonicalArgs(toArgMap(args))})` };
+      return createGraphProxy(binding, ref, fieldDef.type, trail);
+    };
+  }
+  return graph as BoundGraph;
+}

package/src/reactivity.ts

@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import type { GraphCache } from "./cache.js";
+import type { GraphRuntime } from "./runtime.js";
+
+/**
+ * Fine-grained re-render substrate (valtio-style).
+ *
+ * A component tracks the records it read this render; its `useSyncExternalStore`
+ * snapshot is gated by a digest of just those records' versions, so a global cache
+ * notify only re-renders the components whose records actually changed — no per-key
+ * subscription fan-out. The hooks in `glue-client.ts` drive this: `useGlean` installs
+ * an ambient read tracker, `usePaginated` seeds the set with its connection's record.
+ */
+
+/** A stable digest of the tracked keys' versions; changes iff a tracked key changed.
+ * Each key is resolved at its own granularity — a field (`record\0field`, from
+ * `useGlean`) or a whole record (from `usePaginated`) — via {@link GraphCache.trackedVersion}. */
+export function affectedDigest(cache: GraphCache, keys: ReadonlySet<string>): string {
+  if (keys.size === 0) return "";
+  let out = "";
+  for (const key of keys) out += `${key}:${cache.trackedVersion(key)}|`;
+  return out;
+}
+
+/**
+ * Re-render the caller only when one of the records in `affected.current` changes.
+ * The external snapshot is a monotonic counter (stable during render, decoupled from
+ * the live set) so it never spuriously diverges from the render-time value; the
+ * subscriber bumps it only when the digest actually changed, and an effect rebases the
+ * baseline to this render's reads. SSR is a no-op (`getServerSnapshot` → 0).
+ */
+export function useFineGrainedRerender(
+  runtime: GraphRuntime | undefined,
+  affected: { current: Set<string> },
+): void {
+  const tick = useRef(0);
+  const baseline = useRef("");
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (!runtime) return () => {};
+      const cache = runtime.cache;
+      baseline.current = affectedDigest(cache, affected.current); // rebase at (re)subscribe
+      return cache.subscribe(() => {
+        const next = affectedDigest(cache, affected.current);
+        if (next !== baseline.current) {
+          baseline.current = next;
+          tick.current++;
+          onChange();
+        }
+      });
+    },
+    [runtime, affected],
+  );
+  useSyncExternalStore(subscribe, () => tick.current, () => 0);
+  // Post-commit: rebase to THIS render's reads + current versions, so the next notify
+  // compares against the records actually read this pass (they can differ per render).
+  useEffect(() => {
+    if (runtime) baseline.current = affectedDigest(runtime.cache, affected.current);
+  });
+}
+
+/**
+ * Diff this render's tracked keys against the currently-held retentions:
+ * retain newly-read records, release ones no longer read. `held` maps record
+ * key → its release. Pure cache+map logic (the React hook is a thin effect
+ * shell over it), so it's directly unit-testable.
+ */
+export function syncRetention(cache: GraphCache, held: Map<string, () => void>, tracked: ReadonlySet<string>): void {
+  const current = new Set<string>();
+  for (const key of tracked) current.add(cache.trackedRecordKey(key));
+  for (const key of current) {
+    if (!held.has(key)) held.set(key, cache.retain(key));
+  }
+  for (const [key, release] of held) {
+    if (!current.has(key)) {
+      release();
+      held.delete(key);
+    }
+  }
+}
+
+/** Release every held retention (unmount). */
+export function releaseRetention(held: Map<string, () => void>): void {
+  for (const release of held.values()) release();
+  held.clear();
+}
+
+/**
+ * Retain this render's records while mounted (reference-counted, Relay-style):
+ * post-commit, the records the component read are pinned — `cache.gc()` and LRU
+ * eviction skip them — and released when the component stops reading them or
+ * unmounts.
+ */
+function useRetained(runtime: GraphRuntime | undefined, affected: { current: Set<string> }): void {
+  const held = useRef<Map<string, () => void>>(new Map());
+  useEffect(() => {
+    if (runtime) syncRetention(runtime.cache, held.current, affected.current);
+  });
+  useEffect(() => {
+    const map = held.current;
+    return () => releaseRetention(map);
+  }, []);
+}
+
+/**
+ * Translate a render's tracked keys into masked-read violations: field-level
+ * reads on IDENTIFIED records whose `Type.field` pair is outside the
+ * component's compiled read-map. Record-level trackers and path-identity
+ * records carry no typename — skipped, never guessed.
+ */
+export function maskViolations(
+  cache: GraphCache,
+  allowed: ReadonlySet<string>,
+  tracked: ReadonlySet<string>,
+): string[] {
+  const out: string[] = [];
+  for (const key of tracked) {
+    const record = cache.trackedRecordKey(key);
+    if (record === key) continue; // record-level tracker — not a field read
+    if (record.startsWith("path:")) continue; // id-less record — typename unknown
+    const pair = `${record.slice(0, record.indexOf(":"))}.${key.slice(record.length + 1)}`;
+    if (!allowed.has(pair)) out.push(pair);
+  }
+  return out;
+}
+
+/**
+ * The shared shape of the tracking hooks: hold a per-render "affected records" set,
+ * let the caller `populate` it (install an ambient tracker, or seed a known record),
+ * and wire fine-grained re-rendering over it. `populate` runs synchronously in the
+ * hook body, so reads that follow in the component attribute to this render's set.
+ * While mounted, the records read are retained (see {@link useRetained});
+ * `onCommit` (if given) sees the final set post-commit — the masking check.
+ */
+export function useTracked(
+  runtime: GraphRuntime | undefined,
+  populate: (affected: Set<string>) => void,
+  onCommit?: (tracked: ReadonlySet<string>) => void,
+): void {
+  const affected = useRef<Set<string>>(new Set());
+  const tracking = new Set<string>();
+  populate(tracking);
+  affected.current = tracking;
+  useFineGrainedRerender(runtime, affected);
+  useRetained(runtime, affected);
+  useEffect(() => {
+    onCommit?.(affected.current);
+  });
+}

package/src/route.ts

@@ -0,0 +1,84 @@
+import type { SelectionSet } from "@gleanql/core";
+import type { GraphClientAdapter, GraphRequestContext } from "./adapter.js";
+import type { GraphRuntime } from "./runtime.js";
+import type { FieldValue } from "./cache.js";
+import { persistRootLinks, resolveFromCache } from "./cache-resolve.js";
+
+/**
+ * Framework-integration seam. A compiled operation (the artifact the compiler
+ * emits) plus a client adapter and a request context is enough to drive a
+ * route: compute variables, execute, seed the cache. A framework adapter
+ * (RWSDK first) answers "which operation for this entrypoint?" and "how do I
+ * build the request context?".
+ */
+export interface CompiledOperation<RouteContext = unknown, TVariables = Record<string, unknown>> {
+  readonly name: string;
+  readonly kind: "query" | "mutation" | "subscription";
+  readonly document: string;
+  readonly hash?: string;
+  readonly variables: (ctx: RouteContext) => TVariables;
+  readonly readMap?: Record<string, readonly string[]>;
+  /** Merged selection tree; enables cache-first resolution when present. */
+  readonly selection?: SelectionSet;
+}
+
+export interface RunRouteOptions {
+  /**
+   * Cache-first: if the cache already satisfies the operation's full selection,
+   * skip the network. Defaults to true; pass false to always fetch (e.g. an
+   * explicit refresh that must hit the server).
+   */
+  readonly cacheFirst?: boolean;
+}
+
+export interface RunRouteResult<TVariables> {
+  readonly variables: TVariables;
+  readonly roots: Record<string, FieldValue>;
+  readonly errors?: ReadonlyArray<{ message: string }>;
+}
+
+/** Execute a compiled operation and seed the runtime cache (steps 2–5 of the route flow). */
+export async function runRoute<RouteContext, TVariables extends Record<string, unknown>>(args: {
+  operation: CompiledOperation<RouteContext, TVariables>;
+  routeContext: RouteContext;
+  adapter: GraphClientAdapter;
+  context: GraphRequestContext;
+  runtime: GraphRuntime;
+  options?: RunRouteOptions;
+}): Promise<RunRouteResult<TVariables>> {
+  const variables = args.operation.variables(args.routeContext);
+  const selection = args.operation.selection;
+  const cacheFirst = args.options?.cacheFirst ?? true;
+
+  // Cache-first: serve from the normalized cache when it already covers the op.
+  if (cacheFirst && selection) {
+    const hit = resolveFromCache(args.runtime.cache, selection, variables);
+    if (hit.covered) return { variables, roots: hit.roots };
+  }
+
+  const result = await args.adapter.execute(
+    { name: args.operation.name, kind: args.operation.kind, document: args.operation.document },
+    variables,
+    args.context,
+  );
+  const roots = result.data ? args.runtime.seedResult(result.data as Record<string, unknown>) : {};
+  // Persist root links so a later run can resolve this operation from cache.
+  if (selection && result.data) persistRootLinks(args.runtime.cache, selection, variables, roots);
+  return { variables, roots, errors: result.errors };
+}
+
+/**
+ * Re-run an operation against the network, bypassing cache-first, and re-seed.
+ * The re-seed writes through the cache, bumping its version and notifying
+ * subscribers — so a `useSyncExternalStore` (`cache.subscribe`) re-renders the
+ * UI with the fresh data. Use for an explicit "Refresh" / post-mutation refetch.
+ */
+export function refetch<RouteContext, TVariables extends Record<string, unknown>>(args: {
+  operation: CompiledOperation<RouteContext, TVariables>;
+  routeContext: RouteContext;
+  adapter: GraphClientAdapter;
+  context: GraphRequestContext;
+  runtime: GraphRuntime;
+}): Promise<RunRouteResult<TVariables>> {
+  return runRoute({ ...args, options: { cacheFirst: false } });
+}