@gleanql/client 0.1.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@gleanql/client",
+  "version": "0.1.0",
+  "description": "Glean's runtime: normalized cache, fine-grained reactivity, mutations, subscriptions and React hooks",
+  "license": "MIT",
+  "author": "Alexander Liljengard",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gleanql/gleanql.git",
+    "directory": "packages/client"
+  },
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@gleanql/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.6",
+    "react-dom": "19.2.6"
+  },
+  "homepage": "https://gleanql.com",
+  "bugs": "https://github.com/gleanql/gleanql/issues",
+  "keywords": [
+    "graphql",
+    "graphql-client",
+    "react",
+    "normalized-cache",
+    "suspense",
+    "optimistic-updates"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts.eager"
+  }
+}

package/src/adapter-shared.ts

@@ -0,0 +1,76 @@
+import type { GraphResult } from "./adapter.js";
+
+/**
+ * Shared helpers for client adapters.
+ *
+ * Every adapter implements the same `GraphClientAdapter.execute` contract; the
+ * runtime owns cache identity and Suspense, so an adapter is *only* transport.
+ * These helpers keep error/response mapping consistent across clients.
+ */
+
+export interface GraphQLError {
+  readonly message: string;
+}
+
+/** Build a `GraphResult`, omitting empty `data`/`errors` keys. */
+export function result<TData>(data: TData | null | undefined, errors?: readonly GraphQLError[]): GraphResult<TData> {
+  return {
+    ...(data != null ? { data } : {}),
+    ...(errors && errors.length > 0 ? { errors } : {}),
+  };
+}
+
+/** A push→pull async iterator: the transport pushes, the consumer pulls. */
+export interface PushPullIterator<T> extends AsyncIterator<T> {
+  /** Deliver the next value to the consumer (ignored once finished). */
+  push(value: T): void;
+  /** End the stream; the consumer's next pull resolves `{ done: true }`. */
+  finish(): void;
+}
+
+/**
+ * Bridge a push-based transport (SSE `onmessage`, a graphql-ws sink) into the
+ * pull-based `AsyncIterator` the runtime consumes. The transport wires its callbacks
+ * to `push`/`finish`; the consumer's `return()` (cleanup) calls `onReturn` to tear the
+ * transport down. Values pushed with no pending pull queue up and drain in order.
+ */
+export function pushPullIterator<T>(onReturn?: () => void): PushPullIterator<T> {
+  const queue: T[] = [];
+  let waiting: ((r: IteratorResult<T>) => void) | null = null;
+  let done = false;
+  const ended = (): IteratorResult<T> => ({ value: undefined, done: true });
+
+  const finish = (): void => {
+    if (done) return;
+    done = true;
+    if (waiting) {
+      waiting(ended());
+      waiting = null;
+    }
+  };
+
+  return {
+    push(value: T): void {
+      if (done) return;
+      if (waiting) {
+        waiting({ value, done: false });
+        waiting = null;
+      } else {
+        queue.push(value);
+      }
+    },
+    finish,
+    next(): Promise<IteratorResult<T>> {
+      if (queue.length > 0) return Promise.resolve({ value: queue.shift()!, done: false });
+      if (done) return Promise.resolve(ended());
+      return new Promise((resolve) => {
+        waiting = resolve;
+      });
+    },
+    return(): Promise<IteratorResult<T>> {
+      onReturn?.();
+      finish();
+      return Promise.resolve(ended());
+    },
+  };
+}

package/src/adapter-ws.ts

@@ -0,0 +1,134 @@
+import type {
+  GraphClientAdapter,
+  GraphOperation,
+  GraphRequestContext,
+  GraphResult,
+} from "./adapter.js";
+import { pushPullIterator } from "./adapter-shared.js";
+
+/**
+ * A `graphql-ws` transport for the same `GraphClientAdapter` seam the fetch
+ * adapter implements. WebSockets carry every operation kind — a query/mutation is
+ * a single-result stream that completes, a subscription is a long-lived one — so
+ * this adapter drives both `execute` and `subscribe` off one `graphql-ws` client.
+ *
+ * We do NOT bundle `graphql-ws`: the app installs it, calls its `createClient({ url })`,
+ * and passes the result here. The client is typed structurally (the subset we use)
+ * so the dependency stays optional and the adapter is trivially testable with a fake.
+ *
+ *   import { createClient } from "graphql-ws";
+ *   const adapter = createGraphWsAdapter({ client: createClient({ url: "wss://…/graphql" }) });
+ */
+
+/** Sink graphql-ws pushes results into — mirrors its `Sink`. */
+export interface GraphWsSink<T = unknown> {
+  next: (value: T) => void;
+  error: (error: unknown) => void;
+  complete: () => void;
+}
+
+/** Operation payload graphql-ws subscribes with — mirrors its `SubscribePayload`. */
+export interface GraphWsPayload {
+  readonly query: string;
+  readonly variables?: Record<string, unknown> | null;
+  readonly operationName?: string | null;
+  readonly extensions?: Record<string, unknown>;
+}
+
+/** Structural subset of graphql-ws's `Client` we depend on. */
+export interface GraphWsClient {
+  subscribe<T = GraphResult<unknown>>(payload: GraphWsPayload, sink: GraphWsSink<T>): () => void;
+  dispose?: () => void | Promise<void>;
+}
+
+export interface GraphWsAdapterOptions {
+  /** A graphql-ws client, e.g. `createClient({ url })`. */
+  readonly client: GraphWsClient;
+  /**
+   * Per-request `extensions` from context (auth token, shop domain, locale). The
+   * connection-level params belong on the client; this rides each operation.
+   */
+  readonly extensions?: (context: GraphRequestContext) => Record<string, unknown>;
+}
+
+function toErrors(error: unknown): ReadonlyArray<{ message: string }> {
+  if (Array.isArray(error)) {
+    return error.map((e) => ({ message: String((e as { message?: unknown })?.message ?? e) }));
+  }
+  if (error instanceof Error) return [{ message: error.message }];
+  if (error && typeof error === "object" && "reason" in error) {
+    // A WebSocket CloseEvent.
+    return [{ message: String((error as { reason?: unknown }).reason) || "subscription socket closed" }];
+  }
+  return [{ message: String(error) }];
+}
+
+export function createGraphWsAdapter(options: GraphWsAdapterOptions): GraphClientAdapter {
+  const { client } = options;
+
+  const payloadFor = <TVariables>(
+    operation: GraphOperation<unknown, TVariables>,
+    variables: TVariables,
+    context: GraphRequestContext,
+  ): GraphWsPayload => {
+    const extensions = options.extensions?.(context);
+    return {
+      query: operation.document,
+      variables: (variables ?? {}) as Record<string, unknown>,
+      operationName: operation.name,
+      ...(extensions && Object.keys(extensions).length > 0 ? { extensions } : {}),
+    };
+  };
+
+  return {
+    // Query / mutation: take the single result, settle on the first `next` (or on
+    // `complete`/`error` if the server completes empty). Dispose immediately after.
+    execute<TData, TVariables>(
+      operation: GraphOperation<TData, TVariables>,
+      variables: TVariables,
+      context: GraphRequestContext,
+    ): Promise<GraphResult<TData>> {
+      return new Promise<GraphResult<TData>>((resolve) => {
+        let settled = false;
+        let dispose: (() => void) | undefined;
+        const settle = (r: GraphResult<TData>): void => {
+          if (settled) return;
+          settled = true;
+          resolve(r);
+          dispose?.();
+        };
+        dispose = client.subscribe(payloadFor(operation, variables, context), {
+          next: (value) => settle(value as GraphResult<TData>),
+          error: (error) => settle({ errors: toErrors(error) }),
+          complete: () => settle({}),
+        });
+        // `subscribe` may have settled synchronously before `dispose` was assigned.
+        if (settled) dispose?.();
+      });
+    },
+
+    // Subscription: bridge the push-based sink into a pull-based AsyncIterable, the
+    // shape the runtime consumes. `return()` disposes the graphql-ws subscription.
+    subscribe<TData, TVariables>(
+      operation: GraphOperation<TData, TVariables>,
+      variables: TVariables,
+      context: GraphRequestContext,
+    ): AsyncIterable<GraphResult<TData>> {
+      return {
+        [Symbol.asyncIterator](): AsyncIterator<GraphResult<TData>> {
+          let dispose: (() => void) | undefined;
+          const it = pushPullIterator<GraphResult<TData>>(() => dispose?.());
+          dispose = client.subscribe(payloadFor(operation, variables, context), {
+            next: (value) => it.push(value as GraphResult<TData>),
+            error: (error) => {
+              it.push({ errors: toErrors(error) });
+              it.finish();
+            },
+            complete: () => it.finish(),
+          });
+          return it;
+        },
+      };
+    },
+  };
+}

package/src/adapter.ts

@@ -0,0 +1,152 @@
+/**
+ * Client adapter interface. The graph runtime owns cache identity, Suspense,
+ * batching and normalization; an adapter owns transport (HTTP, auth, retries).
+ * Ships a plain fetch adapter; any transport (graphql-ws for subscriptions, or a
+ * urql/Apollo client if an app already runs one) slots in behind this interface.
+ */
+import { pushPullIterator } from "./adapter-shared.js";
+
+export interface GraphOperation<_TData = unknown, _TVariables = unknown> {
+  readonly name: string;
+  readonly kind: "query" | "mutation" | "subscription";
+  readonly document: string;
+  /** SHA-256 hex of `document` — the persisted-operation ID (present on compiled operations). */
+  readonly hash?: string;
+}
+
+export interface GraphRequestContext {
+  readonly [key: string]: unknown;
+}
+
+export interface GraphResult<TData> {
+  readonly data?: TData;
+  readonly errors?: ReadonlyArray<{ message: string }>;
+}
+
+export interface GraphClientAdapter {
+  execute<TData, TVariables>(
+    operation: GraphOperation<TData, TVariables>,
+    variables: TVariables,
+    context: GraphRequestContext,
+  ): Promise<GraphResult<TData>>;
+
+  subscribe?<TData, TVariables>(
+    operation: GraphOperation<TData, TVariables>,
+    variables: TVariables,
+    context: GraphRequestContext,
+  ): AsyncIterable<GraphResult<TData>>;
+}
+
+export interface FetchAdapterOptions {
+  readonly endpoint: string;
+  readonly fetch?: typeof fetch;
+  /** Build request headers from context (auth, shop domain, locale, ...). */
+  readonly headers?: (context: GraphRequestContext) => Record<string, string>;
+  /**
+   * Endpoint for subscriptions, consumed as a Server-Sent Events stream via the
+   * browser's `EventSource`. Defaults to `${endpoint}/stream`. A production app
+   * that prefers WebSockets can drop a `graphql-ws` adapter into the same
+   * `subscribe` seam instead.
+   */
+  readonly subscriptionEndpoint?: string;
+  /**
+   * Send operations BY HASH instead of by document (`extensions.persistedQuery.
+   * sha256Hash` — the Apollo APQ wire shape, which `createPersistedResolver`
+   * understands server-side). The document never rides the request, so the
+   * server can enforce a build-produced allowlist. If the server answers
+   * `PersistedQueryNotFound` (e.g. an APQ cache that hasn't seen the hash), the
+   * request retries ONCE with the full document so the server can register it.
+   * Operations without a `hash` fall back to sending the document.
+   */
+  readonly persisted?: boolean;
+  /** Observability hook: a persisted hash was unknown to the server and the document was re-sent (APQ register). */
+  readonly onPersistedRetry?: (operationName: string) => void;
+}
+
+/** Minimal fetch transport. Context is used only to build headers; it is never serialized into the body. */
+export function createFetchAdapter(options: FetchAdapterOptions): GraphClientAdapter {
+  const doFetch = options.fetch ?? fetch;
+  return {
+    async execute<TData, TVariables>(
+      operation: GraphOperation<TData, TVariables>,
+      variables: TVariables,
+      context: GraphRequestContext,
+    ): Promise<GraphResult<TData>> {
+      const post = async (body: Record<string, unknown>): Promise<GraphResult<TData>> => {
+        const res = await doFetch(options.endpoint, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...(options.headers ? options.headers(context) : {}),
+          },
+          body: JSON.stringify(body),
+        });
+        // A GraphQL response (even an error one) is JSON; anything else (proxy 502
+        // HTML, empty body) becomes a clear transport error instead of a parse error.
+        const parsed = (await res.json().catch(() => undefined)) as GraphResult<TData> | undefined;
+        if (parsed === undefined) {
+          throw new Error(`graph fetch: non-JSON response (${res.status} ${res.statusText}) from ${options.endpoint}`);
+        }
+        return parsed;
+      };
+
+      if (options.persisted && operation.hash) {
+        const extensions = { persistedQuery: { version: 1, sha256Hash: operation.hash } };
+        const first = await post({ operationName: operation.name, variables, extensions });
+        // APQ negotiation: an allowlist server never answers this (the build seeded
+        // it); a cache-style server asks for the document once.
+        if (first.errors?.some((e) => e.message === "PersistedQueryNotFound")) {
+          options.onPersistedRetry?.(operation.name);
+          return post({ query: operation.document, operationName: operation.name, variables, extensions });
+        }
+        return first;
+      }
+
+      return post({ query: operation.document, variables, operationName: operation.name });
+    },
+
+    // Subscriptions ride an SSE stream (GET + EventSource) — client-only. The
+    // operation rides the query string; each `data:` frame is a GraphResult JSON.
+    subscribe<TData, TVariables>(
+      operation: GraphOperation<TData, TVariables>,
+      variables: TVariables,
+    ): AsyncIterable<GraphResult<TData>> {
+      const base = options.subscriptionEndpoint ?? `${options.endpoint}/stream`;
+      return sseIterable(base, operation.document, variables, operation.name) as AsyncIterable<GraphResult<TData>>;
+    },
+  };
+}
+
+/** Bridge a Server-Sent Events stream into an `AsyncIterable<GraphResult>`. */
+function sseIterable(
+  url: string,
+  document: string,
+  variables: unknown,
+  operationName: string,
+): AsyncIterable<GraphResult<unknown>> {
+  return {
+    [Symbol.asyncIterator](): AsyncIterator<GraphResult<unknown>> {
+      // No EventSource (server / non-browser): an empty, immediately-done stream.
+      if (typeof EventSource === "undefined") {
+        return { next: () => Promise.resolve({ value: undefined, done: true }) };
+      }
+      const qs =
+        `query=${encodeURIComponent(document)}` +
+        `&operationName=${encodeURIComponent(operationName)}` +
+        `&variables=${encodeURIComponent(JSON.stringify(variables ?? {}))}`;
+      const es = new EventSource(`${url}?${qs}`);
+      const it = pushPullIterator<GraphResult<unknown>>(() => es.close());
+
+      es.onmessage = (e: MessageEvent) => {
+        try {
+          it.push(JSON.parse(e.data) as GraphResult<unknown>);
+        } catch {
+          /* ignore malformed frame */
+        }
+      };
+      // SSE auto-reconnects, so surface the error as a frame but keep the stream open.
+      es.onerror = () => it.push({ errors: [{ message: "subscription stream error" }] });
+      return it;
+    },
+  };
+}

package/src/cache-resolve.ts

@@ -0,0 +1,98 @@
+import { canonicalArgs, responseKey, type ArgMap, type ArgValue, type SelectionSet, type FieldSelection } from "@gleanql/core";
+import type { GraphCache, GraphRef, FieldValue } from "./cache.js";
+import { isGraphRef } from "./proxy.js";
+
+/**
+ * Cache-first resolution.
+ *
+ * Before executing an operation over the network, check whether the normalized
+ * cache already satisfies its entire selection. The link from a root call to its
+ * entity (`product(handle:"x") -> Product:123`) is persisted under the root
+ * record, so a re-run, a back-navigation, or data another writer already filled
+ * (mutation, subscription, sibling query) resolves with zero requests. Coverage
+ * is all-or-nothing here; partial gaps fall back to a full fetch (a future
+ * `node(id:)` patch could fetch only the missing fields).
+ */
+const ROOT = "Query";
+
+function resolveArg(v: ArgValue, vars: Record<string, unknown>): ArgValue {
+  // Substitute the operation variable; canonicalArgValue JSON-stringifies the value.
+  if (v.kind === "var") return { kind: "literal", value: (vars[v.name] ?? null) as string | number | boolean | null };
+  if (v.kind === "list") return { kind: "list", items: v.items.map((i) => resolveArg(i, vars)) };
+  if (v.kind === "object") return { kind: "object", fields: v.fields.map(([k, fv]) => [k, resolveArg(fv, vars)] as const) };
+  return v;
+}
+
+/** Stable per-root-call key (`product(handle:"x")`), with operation variables substituted. */
+function rootLinkKey(field: FieldSelection, vars: Record<string, unknown>): string {
+  const resolved: ArgMap = (field.args ?? []).map(([k, v]) => [k, resolveArg(v, vars)] as const);
+  return `${field.name}(${canonicalArgs(resolved)})`;
+}
+
+/** Record each root field's resolved ref so a later run finds the entity without a fetch. */
+export function persistRootLinks(
+  cache: GraphCache,
+  selection: SelectionSet,
+  vars: Record<string, unknown>,
+  roots: Record<string, FieldValue>,
+  rootPath: string = ROOT,
+): void {
+  const rec: GraphRef = { path: rootPath };
+  for (const field of selection.fields) {
+    const key = responseKey(field);
+    if (key in roots) cache.setField(rec, rootLinkKey(field, vars), roots[key] as FieldValue);
+  }
+}
+
+/** Does `ref`'s record cover every field in `selection` (recursively)? */
+function covers(cache: GraphCache, ref: GraphRef, selection: SelectionSet): boolean {
+  for (const field of selection.fields) {
+    const got = cache.getField(ref, responseKey(field));
+    if (got.status !== "ready") return false;
+    if (field.selection && !coversValue(cache, got.value, field.selection)) return false;
+  }
+  for (const frag of selection.inlineFragments ?? []) {
+    if (ref.__typename === frag.onType && !covers(cache, ref, frag.selection)) return false;
+  }
+  return true;
+}
+
+function coversValue(cache: GraphCache, value: FieldValue, selection: SelectionSet): boolean {
+  if (value == null) return true; // nullable object — nothing deeper to require
+  if (Array.isArray(value)) return value.every((v) => coversValue(cache, v, selection));
+  if (isGraphRef(value)) return covers(cache, value, selection);
+  return true; // scalar where an object was expected — tolerate, don't block
+}
+
+export interface CacheResolution {
+  readonly covered: boolean;
+  readonly roots: Record<string, FieldValue>;
+}
+
+/**
+ * Try to satisfy an operation entirely from cache. `covered` is true only when
+ * every root link exists and every selected field beneath it is present.
+ */
+export function resolveFromCache(
+  cache: GraphCache,
+  selection: SelectionSet,
+  vars: Record<string, unknown>,
+  rootPath: string = ROOT,
+): CacheResolution {
+  const rec: GraphRef = { path: rootPath };
+  const roots: Record<string, FieldValue> = {};
+  for (const field of selection.fields) {
+    const link = cache.getField(rec, rootLinkKey(field, vars));
+    if (link.status !== "ready") return { covered: false, roots: {} };
+    const ref = link.value;
+    if (ref == null) {
+      roots[responseKey(field)] = null;
+      continue;
+    }
+    if (field.selection && (!isGraphRef(ref) || !covers(cache, ref, field.selection))) {
+      return { covered: false, roots: {} };
+    }
+    roots[responseKey(field)] = ref;
+  }
+  return { covered: true, roots };
+}