@gleanql/client 0.1.14 → 0.1.15

package/dist/index.d.mts

@@ -283,6 +283,14 @@ declare class GraphRuntime {
    * `reportMiss` (they aren't "unexpected" misses).
    */
   resolveRoot(key: string, exec: () => Promise<Record<string, FieldValue>>): Record<string, FieldValue>;
+  /**
+   * Async twin of {@link resolveRoot} for non-React callers (server handlers,
+   * proxy): run `exec` once per `key` and RESOLVE to the seeded root refs instead
+   * of throwing a Suspense promise. Shares the `resolvedRoots` cache and the
+   * `pending` map with `resolveRoot`, so an `await` and a concurrent sync (thrown)
+   * read of the same root+args dedupe to a single in-flight fetch.
+   */
+  resolveRootAsync(key: string, exec: () => Promise<Record<string, FieldValue>>): Promise<Record<string, FieldValue>>;
   /** Seed a record's fields (e.g. from the compiled operation result). */
   seed(ref: GraphRef, fields: Readonly<Record<string, FieldValue>>): void;
   /** Normalize a full operation result into the cache; returns root refs. */
@@ -498,6 +506,12 @@ interface BindGraphOptions {
    * the integration over `runtime.resolveRoot` + `resolveDeferredRoot`.
    */
   readonly resolveDeferredRoot?: (rootField: string, args: Record<string, unknown> | undefined) => FieldValue;
+  /**
+   * Async twin of {@link resolveDeferredRoot}: resolve the seeded value without
+   * throwing, so a deferred root can be `await`ed in a non-React server handler
+   * (`const o = await glean.order({ id })`). Wired over `runtime.resolveRootAsync`.
+   */
+  readonly resolveDeferredRootAsync?: (rootField: string, args: Record<string, unknown> | undefined) => Promise<FieldValue>;
 }
 declare function bindGraph(options: BindGraphOptions): BoundGraph;
 //#endregion

package/dist/index.mjs

@@ -510,6 +510,37 @@ var GraphRuntime = class GraphRuntime {
 		});
 		throw entry.promise;
 	}
+	/**
+	* Async twin of {@link resolveRoot} for non-React callers (server handlers,
+	* proxy): run `exec` once per `key` and RESOLVE to the seeded root refs instead
+	* of throwing a Suspense promise. Shares the `resolvedRoots` cache and the
+	* `pending` map with `resolveRoot`, so an `await` and a concurrent sync (thrown)
+	* read of the same root+args dedupe to a single in-flight fetch.
+	*/
+	async resolveRootAsync(key, exec) {
+		const done = this.resolvedRoots.get(key);
+		if (done) return done;
+		const pkey = `@root:${key}`;
+		const existing = this.pending.get(pkey);
+		if (existing) {
+			await existing.promise;
+			return this.resolvedRoots.get(key) ?? {};
+		}
+		const entry = this.makeDeferred();
+		entry.promise.catch(() => {});
+		this.pending.set(pkey, entry);
+		try {
+			const roots = await exec();
+			this.resolvedRoots.set(key, roots);
+			this.pending.delete(pkey);
+			entry.resolve();
+			return roots;
+		} catch (error) {
+			this.pending.delete(pkey);
+			entry.reject(error);
+			throw error;
+		}
+	}
 	/** Seed a record's fields (e.g. from the compiled operation result). */
 	seed(ref, fields) {
 		this.cache.merge(ref, fields);
@@ -750,6 +781,7 @@ const handler = {
 			type: state.type
 		};
 		if (typeof prop === "symbol") return void 0;
+		if (prop === "then") return void 0;
 		if (prop === "__typename") return state.ref.__typename ?? readField(state, "__typename");
 		const fieldName = prop;
 		const fieldDef = state.binding.schema.getField(state.type, fieldName);
@@ -804,9 +836,8 @@ function bindGraph(options) {
 			...args ? { args } : {}
 		}];
 		if (options.deferredRoots?.has(fieldName) && options.resolveDeferredRoot) {
-			const seededDeferred = options.resolveDeferredRoot(fieldName, args);
-			if (fieldDef.list) return (Array.isArray(seededDeferred) ? seededDeferred : []).map((item) => wrap(binding, item, fieldDef.type, trail));
-			return wrap(binding, seededDeferred, fieldDef.type, trail);
+			const materialize = (seeded) => fieldDef.list ? (Array.isArray(seeded) ? seeded : []).map((item) => wrap(binding, item, fieldDef.type, trail)) : wrap(binding, seeded, fieldDef.type, trail);
+			return makeDeferredRootValue(fieldName, args, fieldDef.list ?? false, materialize, options.resolveDeferredRoot, options.resolveDeferredRootAsync);
 		}
 		const seeded = (typeof options.roots === "function" ? options.roots() : options.roots)?.[fieldName];
 		if (fieldDef.list) return (Array.isArray(seeded) ? seeded : []).map((item) => wrap(binding, item, fieldDef.type, trail));
@@ -814,6 +845,40 @@ function bindGraph(options) {
 	};
 	return graph;
 }
+/**
+* A deferred ("two-sweep") root read is BOTH awaitable and directly readable, so
+* the same call works in a React render and a plain server handler:
+*  - `await glean.order({ id })`  → async-resolve, no Suspense (server handlers)
+*  - `glean.order({ id }).name`   → sync-resolve, suspends until seeded (React)
+*
+* It's a proxy over an EMPTY array (list root) or object (singular root): `.then`
+* drives the async executor (kept in the get-trap only, never an own property, so
+* it is awaitable without leaking into enumeration/spread/JSON), and every other
+* access sync-resolves (throwing a Suspense promise until the fetch+seed completes)
+* then delegates to the materialized value. The array target keeps `Array.isArray`
+* true for a list root, matching a non-deferred list read; the materialized value
+* is memoized so repeated sync reads on the same returned value keep stable element
+* identity. When no async executor is wired `.then` is absent, so the value is a
+* plain (non-thenable) sync read — unchanged React behavior.
+*/
+function makeDeferredRootValue(rootField, args, isList, materialize, syncResolve, asyncResolve) {
+	const then = asyncResolve ? (onFulfilled, onRejected) => asyncResolve(rootField, args).then((seeded) => materialize(seeded)).then(onFulfilled, onRejected) : void 0;
+	let ready = false;
+	let value;
+	const syncValue = () => {
+		if (!ready) {
+			value = materialize(syncResolve(rootField, args));
+			ready = true;
+		}
+		return value;
+	};
+	return new Proxy(isList ? [] : {}, { get(_t, prop) {
+		if (prop === "then") return then;
+		const v = syncValue();
+		const got = v[prop];
+		return typeof got === "function" ? got.bind(v) : got;
+	} });
+}
 //#endregion
 //#region src/cache-resolve.ts
 /**
@@ -1463,22 +1528,22 @@ function createGraphIntegration(options) {
 			});
 			({variables, roots, errors} = r);
 		}
-		const resolveDeferred = operation.deferred ? (rootField, args) => {
-			const key = `${rootField}(${canonicalArgs(toArgMap(args ?? {}))})`;
-			return runtime.resolveRoot(key, async () => {
-				const res = await resolveDeferredRoot({
-					op: operation,
-					rootField,
-					args: args ?? {},
-					schema: options.schema,
-					adapter: options.adapter,
-					runtime,
-					context: requestContext
-				});
-				if (!res.ok && res.error) throw new Error(res.error);
-				return res.roots ?? {};
-			})[rootField];
-		} : void 0;
+		const deferredKey = (rootField, args) => `${rootField}(${canonicalArgs(toArgMap(args ?? {}))})`;
+		const deferredExec = (rootField, args) => async () => {
+			const res = await resolveDeferredRoot({
+				op: operation,
+				rootField,
+				args: args ?? {},
+				schema: options.schema,
+				adapter: options.adapter,
+				runtime,
+				context: requestContext
+			});
+			if (!res.ok && res.error) throw new Error(res.error);
+			return res.roots ?? {};
+		};
+		const resolveDeferred = operation.deferred ? (rootField, args) => runtime.resolveRoot(deferredKey(rootField, args), deferredExec(rootField, args))[rootField] : void 0;
+		const resolveDeferredAsync = operation.deferred ? async (rootField, args) => (await runtime.resolveRootAsync(deferredKey(rootField, args), deferredExec(rootField, args)))[rootField] : void 0;
 		const active = {
 			runtime,
 			graph: bindGraph({
@@ -1486,7 +1551,8 @@ function createGraphIntegration(options) {
 				getRuntime: () => runtime,
 				roots,
 				...deferredRoots ? { deferredRoots } : {},
-				...resolveDeferred ? { resolveDeferredRoot: resolveDeferred } : {}
+				...resolveDeferred ? { resolveDeferredRoot: resolveDeferred } : {},
+				...resolveDeferredAsync ? { resolveDeferredRootAsync: resolveDeferredAsync } : {}
 			}),
 			mutate: createMutator({
 				operations: options.operations,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleanql/client",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Glean's runtime: normalized cache, fine-grained reactivity, mutations, subscriptions and React hooks",
   "license": "MIT",
   "author": "Alexander Liljengard",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@gleanql/core": "0.1.14"
+    "@gleanql/core": "0.1.15"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/integration.ts

@@ -166,25 +166,35 @@ export function createGraphIntegration<Ctx extends Record<string, unknown> = Rec
     }
 
     // The deferred-root executor: fetch a render-time root with its call-site
-    // args (suspends via runtime.resolveRoot, seeds, then resolves to the ref(s)).
+    // args, seed the cache, and resolve to the seeded ref(s). `runDeferredRoot` is
+    // the shared async fetch; the SYNC form (`resolveRoot`) throws a Suspense
+    // promise for React renders, the ASYNC form (`resolveRootAsync`) resolves for
+    // non-React callers (`await glean.order({ id })` in a server handler). Both
+    // dedupe on the same root+args key.
+    const deferredKey = (rootField: string, args: Record<string, unknown> | undefined) =>
+      `${rootField}(${canonicalArgs(toArgMap(args ?? {}))})`;
+    const deferredExec =
+      (rootField: string, args: Record<string, unknown> | undefined) => async (): Promise<Record<string, FieldValue>> => {
+        const res = await runDeferredRoot({
+          op: operation,
+          rootField,
+          args: args ?? {},
+          schema: options.schema,
+          adapter: options.adapter,
+          runtime,
+          context: requestContext,
+        });
+        if (!res.ok && res.error) throw new Error(res.error);
+        return res.roots ?? {};
+      };
+
     const resolveDeferred = operation.deferred
-      ? (rootField: string, args: Record<string, unknown> | undefined): FieldValue => {
-          const key = `${rootField}(${canonicalArgs(toArgMap(args ?? {}))})`;
-          const seededRoots = runtime.resolveRoot(key, async () => {
-            const res = await runDeferredRoot({
-              op: operation,
-              rootField,
-              args: args ?? {},
-              schema: options.schema,
-              adapter: options.adapter,
-              runtime,
-              context: requestContext,
-            });
-            if (!res.ok && res.error) throw new Error(res.error);
-            return res.roots ?? {};
-          });
-          return seededRoots[rootField];
-        }
+      ? (rootField: string, args: Record<string, unknown> | undefined): FieldValue =>
+          runtime.resolveRoot(deferredKey(rootField, args), deferredExec(rootField, args))[rootField]
+      : undefined;
+    const resolveDeferredAsync = operation.deferred
+      ? async (rootField: string, args: Record<string, unknown> | undefined): Promise<FieldValue> =>
+          (await runtime.resolveRootAsync(deferredKey(rootField, args), deferredExec(rootField, args)))[rootField]
       : undefined;
 
     const graph = bindGraph({
@@ -193,6 +203,7 @@ export function createGraphIntegration<Ctx extends Record<string, unknown> = Rec
       roots,
       ...(deferredRoots ? { deferredRoots } : {}),
       ...(resolveDeferred ? { resolveDeferredRoot: resolveDeferred } : {}),
+      ...(resolveDeferredAsync ? { resolveDeferredRootAsync: resolveDeferredAsync } : {}),
     });
     const mutate = createMutator({ operations: options.operations, adapter: options.adapter, runtime, context: requestContext });
 

package/src/proxy.ts

@@ -175,6 +175,11 @@ const handler: ProxyHandler<{ state: ProxyState }> = {
       return { ref: state.ref, type: state.type } satisfies GraphSelection;
     }
     if (typeof prop === "symbol") return undefined;
+    // Never look like a thenable: a graph proxy can be the resolved value of
+    // `await glean.order({ id })`, and Promise resolution probes `.then` — reading
+    // it as a (missing) field would suspend/throw mid-resolution. GraphQL has no
+    // `then` field in practice, so returning undefined is safe.
+    if (prop === "then") 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");
@@ -265,6 +270,15 @@ export interface BindGraphOptions {
    * the integration over `runtime.resolveRoot` + `resolveDeferredRoot`.
    */
   readonly resolveDeferredRoot?: (rootField: string, args: Record<string, unknown> | undefined) => FieldValue;
+  /**
+   * Async twin of {@link resolveDeferredRoot}: resolve the seeded value without
+   * throwing, so a deferred root can be `await`ed in a non-React server handler
+   * (`const o = await glean.order({ id })`). Wired over `runtime.resolveRootAsync`.
+   */
+  readonly resolveDeferredRootAsync?: (
+    rootField: string,
+    args: Record<string, unknown> | undefined,
+  ) => Promise<FieldValue>;
 }
 
 export function bindGraph(options: BindGraphOptions): BoundGraph {
@@ -282,16 +296,24 @@ export function bindGraph(options: BindGraphOptions): BoundGraph {
       const trail: PathStep[] = [{ name: fieldName, ...(args ? { args } : {}) }];
 
       // Deferred ("two-sweep") root: args are only known at the render call-site,
-      // so execute on demand (suspends until fetched + seeded) instead of reading
-      // a preloaded root. This replaces the silent empty-array fallback below for
-      // deferred list roots — `glean.nodes({ ids }).map(...)` fetches, not yields [].
+      // so execute on demand instead of reading a preloaded root. The returned
+      // value is ISOMORPHIC — `await glean.nodes({ ids })` resolves it (server
+      // handlers), while `glean.nodes({ ids }).map(...)` reads it synchronously via
+      // Suspense (React). This also replaces the silent empty-array fallback below:
+      // a deferred list root fetches, it does not yield [].
       if (options.deferredRoots?.has(fieldName) && options.resolveDeferredRoot) {
-        const seededDeferred = options.resolveDeferredRoot(fieldName, args);
-        if (fieldDef.list) {
-          const items = Array.isArray(seededDeferred) ? seededDeferred : [];
-          return items.map((item) => wrap(binding, item, fieldDef.type, trail));
-        }
-        return wrap(binding, seededDeferred, fieldDef.type, trail);
+        const materialize = (seeded: FieldValue): unknown =>
+          fieldDef.list
+            ? (Array.isArray(seeded) ? seeded : []).map((item) => wrap(binding, item, fieldDef.type, trail))
+            : wrap(binding, seeded, fieldDef.type, trail);
+        return makeDeferredRootValue(
+          fieldName,
+          args,
+          fieldDef.list ?? false,
+          materialize,
+          options.resolveDeferredRoot,
+          options.resolveDeferredRootAsync,
+        );
       }
 
       const rootsNow =
@@ -313,3 +335,63 @@ export function bindGraph(options: BindGraphOptions): BoundGraph {
   }
   return graph as BoundGraph;
 }
+
+/**
+ * A deferred ("two-sweep") root read is BOTH awaitable and directly readable, so
+ * the same call works in a React render and a plain server handler:
+ *  - `await glean.order({ id })`  → async-resolve, no Suspense (server handlers)
+ *  - `glean.order({ id }).name`   → sync-resolve, suspends until seeded (React)
+ *
+ * It's a proxy over an EMPTY array (list root) or object (singular root): `.then`
+ * drives the async executor (kept in the get-trap only, never an own property, so
+ * it is awaitable without leaking into enumeration/spread/JSON), and every other
+ * access sync-resolves (throwing a Suspense promise until the fetch+seed completes)
+ * then delegates to the materialized value. The array target keeps `Array.isArray`
+ * true for a list root, matching a non-deferred list read; the materialized value
+ * is memoized so repeated sync reads on the same returned value keep stable element
+ * identity. When no async executor is wired `.then` is absent, so the value is a
+ * plain (non-thenable) sync read — unchanged React behavior.
+ */
+function makeDeferredRootValue(
+  rootField: string,
+  args: Record<string, unknown> | undefined,
+  isList: boolean,
+  materialize: (seeded: FieldValue) => unknown,
+  syncResolve: (rootField: string, args: Record<string, unknown> | undefined) => FieldValue,
+  asyncResolve?: (rootField: string, args: Record<string, unknown> | undefined) => Promise<FieldValue>,
+): unknown {
+  const then = asyncResolve
+    ? (onFulfilled?: (v: unknown) => unknown, onRejected?: (e: unknown) => unknown) =>
+        asyncResolve(rootField, args).then((seeded) => materialize(seeded)).then(onFulfilled, onRejected)
+    : undefined;
+
+  // Materialize once per resolved value: `syncResolve` throws the Suspense promise
+  // until seeded, so nothing is cached until it succeeds; afterwards repeated reads
+  // return the same array/proxies (stable identity, matching a plain array/object).
+  let ready = false;
+  let value: unknown;
+  const syncValue = (): Record<PropertyKey, unknown> => {
+    if (!ready) {
+      value = materialize(syncResolve(rootField, args));
+      ready = true;
+    }
+    return value as Record<PropertyKey, unknown>;
+  };
+
+  // A real array target for list roots (so `Array.isArray` is true and index/length
+  // reads behave like the array they materialize to); a plain object otherwise. Both
+  // are empty and carry no own keys, so enumeration/spread never leak internals.
+  const target: object = isList ? [] : {};
+
+  return new Proxy(target, {
+    get(_t, prop) {
+      if (prop === "then") return then;
+      // Any other read sync-resolves (Suspense) then delegates to the materialized
+      // value/array. Bind functions (Array.prototype.* / callable graph fields) to
+      // that value so `this` is correct.
+      const v = syncValue();
+      const got = v[prop];
+      return typeof got === "function" ? (got as (...a: unknown[]) => unknown).bind(v) : got;
+    },
+  });
+}

package/src/runtime.ts

@@ -107,6 +107,46 @@ export class GraphRuntime {
     throw entry.promise;
   }
 
+  /**
+   * Async twin of {@link resolveRoot} for non-React callers (server handlers,
+   * proxy): run `exec` once per `key` and RESOLVE to the seeded root refs instead
+   * of throwing a Suspense promise. Shares the `resolvedRoots` cache and the
+   * `pending` map with `resolveRoot`, so an `await` and a concurrent sync (thrown)
+   * read of the same root+args dedupe to a single in-flight fetch.
+   */
+  async resolveRootAsync(key: string, exec: () => Promise<Record<string, FieldValue>>): Promise<Record<string, FieldValue>> {
+    const done = this.resolvedRoots.get(key);
+    if (done) return done;
+
+    const pkey = `@root:${key}`;
+    const existing = this.pending.get(pkey);
+    if (existing) {
+      // A sync read already kicked off this fetch — await it, then read the cache.
+      await existing.promise;
+      return this.resolvedRoots.get(key) ?? {};
+    }
+
+    const entry = this.makeDeferred();
+    // The barrier promise only exists to signal concurrent readers (a sync reader
+    // `throw`s it, an async reader `await`s it). On the solo path nothing attaches
+    // to it, so observe its rejection here — the error still propagates to THIS
+    // caller via the `throw` below; without this a failing `await glean.x()` would
+    // surface an unhandled rejection (noisy / isolate-fatal in a Worker).
+    entry.promise.catch(() => {});
+    this.pending.set(pkey, entry);
+    try {
+      const roots = await exec();
+      this.resolvedRoots.set(key, roots);
+      this.pending.delete(pkey);
+      entry.resolve();
+      return roots;
+    } catch (error) {
+      this.pending.delete(pkey);
+      entry.reject(error);
+      throw error;
+    }
+  }
+
   /** 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);