@gleanql/client 0.1.0

package/src/runtime.ts

@@ -0,0 +1,212 @@
+import { GraphCache, type GraphRef, type FieldValue } from "./cache.js";
+import { normalizeValue, seedResult, type KeyOf } from "./normalize.js";
+
+/**
+ * Suspense-aware graph runtime.
+ *
+ * A field read is synchronous on a cache hit. On a miss it enqueues the missing
+ * (ref, field), creates exactly one cached promise for it, and throws that
+ * promise (the Suspense contract). Multiple misses in the same tick batch into
+ * a single `fetchMissing` call. Re-reading a pending field throws the same
+ * promise — no duplicate request, stable across React render retries.
+ */
+export interface MissingFieldRead {
+  readonly ref: GraphRef;
+  readonly fieldKey: string;
+}
+
+export interface MissingFieldResult {
+  readonly ref: GraphRef;
+  readonly fieldKey: string;
+  readonly value: FieldValue;
+}
+
+export type MissingFieldMode = "allow" | "warn" | "error";
+
+export interface GraphRuntimeOptions {
+  /** Batched fetcher for fields not present in the seeded operation. */
+  readonly fetchMissing: (misses: readonly MissingFieldRead[]) => Promise<readonly MissingFieldResult[]>;
+  readonly cache?: GraphCache;
+  /** How to identify entities during normalization (defaults to the `id` field). */
+  readonly keyOf?: KeyOf;
+  /** Behavior when a field absent from the compiled operation is read. */
+  readonly unexpectedMissingField?: MissingFieldMode;
+  /** dev-only: warn with component/field context. */
+  readonly onWarn?: (message: string) => void;
+  /** Microtask scheduler (overridable in tests). */
+  readonly schedule?: (cb: () => void) => void;
+  /** Optional LRU cap for the cache (least-recently-used records evicted past it). */
+  readonly maxCacheRecords?: number;
+}
+
+interface PendingEntry {
+  readonly promise: Promise<void>;
+  resolve(): void;
+  reject(error: unknown): void;
+}
+
+export class GraphRuntime {
+  readonly cache: GraphCache;
+  private readonly pending = new Map<string, PendingEntry>();
+  private queue: MissingFieldRead[] = [];
+  private flushScheduled = false;
+
+  constructor(private readonly options: GraphRuntimeOptions) {
+    this.cache = options.cache ?? new GraphCache(options.maxCacheRecords);
+  }
+
+  /** Synchronous on hit; throws a (cached) promise on miss. */
+  readField(ref: GraphRef, fieldKey: string, debug?: { component?: string }): FieldValue {
+    const got = this.cache.getField(ref, fieldKey);
+    if (got.status === "ready") return got.value;
+
+    this.reportMiss(ref, fieldKey, debug);
+
+    const pkey = this.pendingKey(ref, fieldKey);
+    const existing = this.pending.get(pkey);
+    if (existing) throw existing.promise;
+
+    const entry = this.makeDeferred();
+    this.pending.set(pkey, entry);
+    this.queue.push({ ref, fieldKey });
+    this.scheduleFlush();
+    throw entry.promise;
+  }
+
+  /** Seed a record's fields (e.g. from the compiled operation result). */
+  seed(ref: GraphRef, fields: Readonly<Record<string, FieldValue>>): void {
+    this.cache.merge(ref, fields);
+  }
+
+  /** Normalize a full operation result into the cache; returns root refs. */
+  seedResult(data: Readonly<Record<string, unknown>>, options?: { rootPath?: string }): Record<string, FieldValue> {
+    return seedResult(this.cache, data, { keyOf: this.options.keyOf, ...options });
+  }
+
+  /**
+   * Low-level pagination primitive: append a freshly-fetched page onto a cached
+   * connection. Normalizes the page's `nodes` and concats them after the existing
+   * ones, and (if present) replaces `pageInfo`. Every reader of the connection
+   * re-renders with the longer `nodes` array. This makes no assumptions about HOW
+   * the page was fetched or which cursor convention the schema uses — the app fetches
+   * the next page however it likes (the connection's ref is available via
+   * `selectionOf(value)`), then hands the page object here to merge it in.
+   */
+  appendConnection(
+    connectionRef: GraphRef,
+    page: Record<string, unknown>,
+    mergeRefs?: (existing: readonly FieldValue[], incoming: readonly FieldValue[]) => readonly FieldValue[],
+  ): void {
+    const keyOf = this.options.keyOf;
+    const anchor = this.cache.recordKey(connectionRef);
+    const existing = this.cache.getField(connectionRef, "nodes");
+    const prior = existing.status === "ready" && Array.isArray(existing.value) ? existing.value : [];
+
+    if (Array.isArray(page.nodes)) {
+      const fresh = page.nodes.map((n, i) =>
+        normalizeValue(this.cache, n, anchor, `nodes.${prior.length + i}`, keyOf),
+      );
+      const merged = mergeRefs ? mergeRefs(prior, fresh) : [...prior, ...fresh];
+      this.cache.setField(connectionRef, "nodes", [...merged]);
+    }
+    if (page.pageInfo != null) {
+      this.cache.setField(connectionRef, "pageInfo", normalizeValue(this.cache, page.pageInfo, anchor, "pageInfo", keyOf));
+    }
+  }
+
+  /** Invalidate a record (e.g. after a mutation) and clear its pending reads. */
+  invalidate(ref: GraphRef): void {
+    const prefix = `${this.cache.recordKey(ref)}.`;
+    this.cache.invalidate(ref);
+    for (const key of [...this.pending.keys()]) {
+      if (key.startsWith(prefix)) this.pending.delete(key);
+    }
+  }
+
+  /** Serialize the cache for hydration across the server/client boundary. */
+  snapshot(): Record<string, Record<string, FieldValue>> {
+    return this.cache.snapshot();
+  }
+
+  /**
+   * Fold a snapshot into the live cache (write only, no notify); returns whether
+   * anything changed. Use for a per-navigation merge where the notify is deferred
+   * to a commit-phase effect (see `serialize.ts#absorbHydrationPayload`).
+   */
+  absorbRecords(snapshot: Record<string, Record<string, FieldValue>>): boolean {
+    return this.cache.absorbRecords(snapshot);
+  }
+
+  /** Notify subscribers after one or more `absorbRecords` calls. */
+  notify(): void {
+    this.cache.notify();
+  }
+
+  /** Convenience: absorb a snapshot and notify if it changed (non-React callers). */
+  absorb(snapshot: Record<string, Record<string, FieldValue>>): boolean {
+    const changed = this.cache.absorbRecords(snapshot);
+    if (changed) this.cache.notify();
+    return changed;
+  }
+
+  static hydrate(
+    snapshot: Record<string, Record<string, FieldValue>>,
+    options: Omit<GraphRuntimeOptions, "cache">,
+  ): GraphRuntime {
+    return new GraphRuntime({ ...options, cache: GraphCache.fromSnapshot(snapshot, options.maxCacheRecords) });
+  }
+
+  private reportMiss(ref: GraphRef, fieldKey: string, debug?: { component?: string }): void {
+    const mode = this.options.unexpectedMissingField ?? "allow";
+    if (mode === "allow") return;
+    const where = debug?.component ? ` (read by ${debug.component})` : "";
+    const message = `Runtime graph field miss: ${this.cache.recordKey(ref)}.${fieldKey}${where} was not in the compiled operation.`;
+    if (mode === "error") throw new Error(message);
+    (this.options.onWarn ?? ((m) => console.warn(m)))(message);
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushScheduled) return;
+    this.flushScheduled = true;
+    const schedule = this.options.schedule ?? queueMicrotask;
+    schedule(() => void this.flush());
+  }
+
+  private async flush(): Promise<void> {
+    this.flushScheduled = false;
+    const misses = this.queue;
+    this.queue = [];
+    if (misses.length === 0) return;
+
+    try {
+      const results = await this.options.fetchMissing(misses);
+      for (const r of results) this.cache.setField(r.ref, r.fieldKey, r.value);
+      for (const miss of misses) {
+        const pkey = this.pendingKey(miss.ref, miss.fieldKey);
+        this.pending.get(pkey)?.resolve();
+        this.pending.delete(pkey);
+      }
+    } catch (error) {
+      for (const miss of misses) {
+        const pkey = this.pendingKey(miss.ref, miss.fieldKey);
+        this.pending.get(pkey)?.reject(error);
+        this.pending.delete(pkey);
+      }
+    }
+  }
+
+  /** Stable key for a pending (ref, field) read — also the `invalidate` prefix base. */
+  private pendingKey(ref: GraphRef, fieldKey: string): string {
+    return `${this.cache.recordKey(ref)}.${fieldKey}`;
+  }
+
+  private makeDeferred(): PendingEntry {
+    let resolve!: () => void;
+    let reject!: (e: unknown) => void;
+    const promise = new Promise<void>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    return { promise, resolve, reject };
+  }
+}

package/src/scope.ts

@@ -0,0 +1,97 @@
+import type { GraphRuntime } from "./runtime.js";
+import type { BoundGraph } from "./proxy.js";
+
+/**
+ * Request-scoped runtime resolution.
+ *
+ * A module-level `import { graph } from "~/graph"` must resolve to *the runtime
+ * for the current request* on the server (concurrent requests must not share a
+ * cache) and to a single client runtime in the browser. `GraphScope` is the tiny
+ * seam that makes that possible without threading a runtime through every prop.
+ *
+ * On the server, a framework adapter (RWSDK) wraps request handling in
+ * `scope.run(active, fn)`. If the host exposes AsyncLocalStorage, concurrent
+ * requests are isolated automatically; otherwise the adapter should resolve the
+ * runtime from its own per-request context (`getGraph(requestInfo)`), which never
+ * relies on a shared mutable global. On the client, `scope.set(active)` installs
+ * the singleton after hydration.
+ */
+export interface ActiveGraph {
+  readonly runtime: GraphRuntime;
+  readonly graph: BoundGraph;
+}
+
+interface AsyncLocalStorageLike<T> {
+  getStore(): T | undefined;
+  run<R>(store: T, fn: () => R): R;
+}
+
+export class GraphScope {
+  private singleton: ActiveGraph | undefined;
+  private als: AsyncLocalStorageLike<ActiveGraph> | undefined;
+
+  constructor(als?: AsyncLocalStorageLike<ActiveGraph>) {
+    this.als = als;
+  }
+
+  /**
+   * Attach an AsyncLocalStorage after construction — for isomorphic frameworks
+   * (e.g. React Router) where the *same* `graph` accessor module loads in both
+   * bundles: construct `new GraphScope()` in a universal, client-safe module (no
+   * `node:async_hooks`), then a server-only module calls `attachAls(...)` to
+   * upgrade it to per-request ALS isolation. `run`/`current` read `als`
+   * dynamically, so the upgrade takes effect immediately; the client keeps using
+   * the singleton set by `set()`.
+   */
+  attachAls(als: AsyncLocalStorageLike<ActiveGraph>): void {
+    this.als = als;
+  }
+
+  /** The active graph, or throw a clear error if read outside any scope. */
+  current(): ActiveGraph {
+    const active = this.als?.getStore() ?? this.singleton;
+    if (!active) {
+      throw new Error(
+        "No active graph runtime. On the server wrap rendering in scope.run(active, fn); on the client call scope.set(active) after hydration.",
+      );
+    }
+    return active;
+  }
+
+  /** Run `fn` with `active` as the request-scoped runtime (server). */
+  run<R>(active: ActiveGraph, fn: () => R): R {
+    if (this.als) return this.als.run(active, fn);
+    const prev = this.singleton;
+    this.singleton = active;
+    try {
+      return fn();
+    } finally {
+      this.singleton = prev;
+    }
+  }
+
+  /** Install the active graph as a singleton (client, post-hydration). */
+  set(active: ActiveGraph): void {
+    this.singleton = active;
+  }
+}
+
+/**
+ * Pair a {@link GraphScope} with a zero-arg resolver — the framework-agnostic
+ * binding for the generated accessor. An app exports `activeGraph` and points
+ * `@gleanql/vite`'s `requestScope: { import: "activeGraph", from: "..." }` at it,
+ * then wraps server rendering in `scope.run(active, fn)` (or
+ * `integration.runInScope`). Pass an `AsyncLocalStorage` to isolate concurrent
+ * server requests; omit it for the client singleton.
+ *
+ * ```ts
+ * import { AsyncLocalStorage } from "node:async_hooks";
+ * export const { scope, activeGraph } = bindScope(new AsyncLocalStorage());
+ * ```
+ */
+export function bindScope(
+  als?: AsyncLocalStorageLike<ActiveGraph>,
+): { scope: GraphScope; activeGraph: () => ActiveGraph } {
+  const scope = new GraphScope(als);
+  return { scope, activeGraph: () => scope.current() };
+}

package/src/serialize.ts

@@ -0,0 +1,175 @@
+import {
+  GraphRuntime,
+  bindGraph,
+  type BoundGraph,
+  type FieldValue,
+  type GraphClientAdapter,
+  type GraphRequestContext,
+  type GraphScope,
+  type MissingFieldMode,
+  type MissingFieldRead,
+  type MissingFieldResult,
+} from "./index.js";
+import type { SchemaModel } from "@gleanql/core";
+import type { ActiveRequestGraph } from "./integration.js";
+
+/**
+ * Server -> client serialization.
+ *
+ * Graph values are proxies, not JSON, so we don't serialize them. We serialize
+ * the *cache* (normalized records + path records) plus the root refs and the
+ * operation identity. On the client we rebuild a runtime from that snapshot and
+ * re-bind the graph, so client components read the same fields with cache hits;
+ * fields absent from the snapshot fetch through the client adapter.
+ *
+ * Secrets stay server-side: only `clientSafeContext` keys are serialized.
+ */
+export interface GraphHydrationPayload {
+  readonly operationName: string;
+  readonly variables: Record<string, unknown>;
+  readonly snapshot: Record<string, Record<string, FieldValue>>;
+  readonly roots: Record<string, FieldValue>;
+  /** Allow-listed, client-safe slice of the request context. */
+  readonly context: Record<string, unknown>;
+}
+
+export interface SerializeGraphOptions {
+  /** Keys of the request context that are safe to ship to the client. */
+  readonly clientSafeContext?: readonly string[];
+}
+
+/** Build the JSON-safe hydration payload from an active request. */
+export function serializeGraph(
+  active: ActiveRequestGraph,
+  options: SerializeGraphOptions = {},
+): GraphHydrationPayload {
+  const allow = new Set(options.clientSafeContext ?? []);
+  const context: Record<string, unknown> = {};
+  for (const key of allow) {
+    if (key in active.requestContext) context[key] = active.requestContext[key];
+  }
+  return {
+    operationName: active.operation.name,
+    variables: active.variables,
+    snapshot: active.runtime.snapshot(),
+    roots: active.roots,
+    context,
+  };
+}
+
+const DEFAULT_GLOBAL = "__GRAPH_STATE__";
+
+/**
+ * Render a `<script>` that publishes the payload on `window[globalKey]` for
+ * client hydration. JSON is escaped so it cannot break out of the script element
+ * or be interpreted as HTML (`<`, `>`, `&`, U+2028/U+2029).
+ */
+export function renderGraphHydrationScript(
+  payload: GraphHydrationPayload,
+  options: { globalKey?: string; nonce?: string } = {},
+): string {
+  const nonceAttr = options.nonce ? ` nonce="${options.nonce}"` : "";
+  return `<script${nonceAttr}>${graphHydrationScriptContent(payload, options.globalKey)}</script>`;
+}
+
+/**
+ * Just the inner JS of the hydration script (no `<script>` wrapper), for JSX
+ * hosts that inject via `dangerouslySetInnerHTML` and set the nonce themselves.
+ * JSON is escaped so it can't break out of the script element or be parsed as HTML.
+ */
+export function graphHydrationScriptContent(payload: GraphHydrationPayload, globalKey = DEFAULT_GLOBAL): string {
+  const json = JSON.stringify(payload)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+  return `window[${JSON.stringify(globalKey)}]=${json}`;
+}
+
+/** Read the hydration payload published by `renderGraphHydrationScript` (client). */
+export function readGraphHydrationPayload(globalKey = DEFAULT_GLOBAL): GraphHydrationPayload | undefined {
+  const g = globalThis as Record<string, unknown>;
+  return g[globalKey] as GraphHydrationPayload | undefined;
+}
+
+export interface HydrateGraphOptions {
+  readonly schema: SchemaModel;
+  readonly adapter: GraphClientAdapter;
+  /** Fetch fields absent from the hydrated snapshot (lazy/dynamic reads). */
+  readonly fetchMissing?: (
+    misses: readonly MissingFieldRead[],
+    context: GraphRequestContext,
+  ) => Promise<readonly MissingFieldResult[]>;
+  readonly unexpectedMissingField?: MissingFieldMode;
+  readonly onWarn?: (message: string) => void;
+  /** Install the hydrated runtime on this scope as the client singleton. */
+  readonly scope?: GraphScope;
+}
+
+export interface HydratedGraph {
+  readonly runtime: GraphRuntime;
+  readonly graph: BoundGraph;
+  readonly roots: Record<string, FieldValue>;
+  readonly context: Record<string, unknown>;
+}
+
+/**
+ * Rebuild the runtime + bound graph on the client from a hydration payload.
+ * Reads present in the snapshot resolve synchronously; missing fields suspend and
+ * fetch through the client adapter.
+ */
+export function hydrateGraph(payload: GraphHydrationPayload, options: HydrateGraphOptions): HydratedGraph {
+  const runtime = GraphRuntime.hydrate(payload.snapshot, {
+    keyOf: (typename, obj) => options.schema.identityOf(typename, obj),
+    unexpectedMissingField: options.unexpectedMissingField,
+    onWarn: options.onWarn,
+    fetchMissing: async (misses) =>
+      options.fetchMissing ? options.fetchMissing(misses, payload.context) : misses.map((m) => ({ ref: m.ref, fieldKey: m.fieldKey, value: undefined })),
+  });
+  const graph = bindGraph({ schema: options.schema, getRuntime: () => runtime, roots: payload.roots });
+  const active: HydratedGraph = { runtime, graph, roots: payload.roots, context: payload.context };
+  options.scope?.set({ runtime, graph });
+  return active;
+}
+
+/**
+ * RSC-native hydration (vs. the `<script>`/`window` model above).
+ *
+ * Under React Server Components the `Document` shell is rendered once, but each
+ * client navigation re-streams only the page subtree. So a one-shot global can't
+ * keep client islands warm across navigation. Instead the payload rides the RSC
+ * flight stream as a prop of a client component (it is plain JSON by
+ * construction), and on every (re)render that component folds it into a single
+ * long-lived client runtime — the cache accumulates across navigations.
+ */
+
+/** The page-current pointer islands read for `refresh()` (which operation + vars). */
+export interface GraphPagePointer {
+  readonly operationName: string;
+  readonly variables: Record<string, unknown>;
+  readonly context: Record<string, unknown>;
+  readonly roots: Record<string, FieldValue>;
+}
+
+/**
+ * Render-phase merge: fold a payload's snapshot into a live runtime, write-only
+ * (no subscriber notify — the caller bumps in a commit-phase effect). Idempotent.
+ * Returns whether anything changed.
+ */
+export function absorbHydrationPayload(
+  runtime: GraphRuntime,
+  payload: GraphHydrationPayload,
+): boolean {
+  return runtime.absorbRecords(payload.snapshot);
+}
+
+/** Derive the current-page pointer from a payload (drives `refresh()`). */
+export function pagePointer(payload: GraphHydrationPayload): GraphPagePointer {
+  return {
+    operationName: payload.operationName,
+    variables: payload.variables,
+    context: payload.context,
+    roots: payload.roots,
+  };
+}