@gleanql/client 0.1.8 → 0.1.9

package/dist/index.d.mts

@@ -601,6 +601,22 @@ interface RunMutationOptions<TData = unknown> {
  * for logical failures — inspect `ok`/`userErrors`/`errors`.
  */
 declare function runMutation<TData = Record<string, unknown>>(options: RunMutationOptions<TData>): Promise<MutationResult<TData>>;
+/**
+ * Server-side mutation execution: run a compiled mutation through the adapter and
+ * surface `userErrors`, WITHOUT a client cache/runtime. This is the core of the
+ * server `mutate()` primitive — server actions, webhooks, jobs, and proxy handlers
+ * mutate Shopify without a hydrated read graph. Never rejects for logical failures;
+ * inspect `ok`/`userErrors`/`errors`.
+ */
+declare function runServerMutation<TData = Record<string, unknown>>(params: {
+  readonly operation: {
+    readonly name: string;
+    readonly document: string;
+  };
+  readonly variables: Record<string, unknown>;
+  readonly adapter: GraphClientAdapter;
+  readonly context: GraphRequestContext;
+}): Promise<MutationResult<TData>>;
 /** Invalidate a record by graph value (proxy) or raw ref — next read re-fetches. */
 declare function invalidateValue(runtime: GraphRuntime, value: GraphRef | unknown): void;
 /** One rule for stringifying unknown errors, shared across hooks and transports. */
@@ -735,6 +751,13 @@ interface GraphIntegration<Ctx extends Record<string, unknown>> {
   getGraph(requestInfo: RequestInfo<Ctx>): BoundGraph;
   /** The `graph.mutate.*` namespace for this request (throws if not preloaded). */
   getMutator(requestInfo: RequestInfo<Ctx>): BoundMutations;
+  /**
+   * Run a compiled mutation by name, server-side, WITHOUT a preloaded read graph —
+   * the executor behind the server `mutate()` primitive (server actions, webhooks,
+   * jobs). Resolves the op, maps `vars` via its factory, runs it through the
+   * adapter, and surfaces `userErrors`. Never rejects; inspect `ok`/`userErrors`.
+   */
+  mutate<TData = unknown>(opName: string, vars: unknown, context?: GraphRequestContext): Promise<MutationResult<TData>>;
   /** Invalidate a graph value / ref in this request's cache (refetch on next read). */
   invalidate(requestInfo: RequestInfo<Ctx>, value: GraphRef | unknown): void;
   /** Read the full active request state (runtime, roots, variables, ...). */
@@ -951,4 +974,4 @@ interface PersistedResolverOptions {
 }
 declare function createPersistedResolver(operations: Readonly<Record<string, PersistedLookupOperation>>, options?: PersistedResolverOptions): (body: PersistedRequestBody) => PersistedResolution;
 //#endregion
-export { ActiveGraph, ActiveRequestGraph, BindGraphOptions, BoundGraph, BoundMutations, BuildRouteContextOptions, CacheResolution, CompiledOperation, CreateMutatorOptions, FetchAdapterOptions, FieldLookup, FieldValue, GRAPH_REF, GRAPH_TRAIL, GRAPH_TYPE, GraphBinding, GraphCache, GraphClientAdapter, GraphHydrationPayload, GraphIntegration, GraphIntegrationOptions, GraphOperation, GraphPagePointer, GraphQLError, GraphRef, GraphRequestContext, GraphResult, GraphRouteContext, GraphRuntime, GraphRuntimeOptions, GraphScope, GraphSelection, GraphWsAdapterOptions, GraphWsClient, GraphWsPayload, GraphWsSink, HydrateGraphOptions, HydratedGraph, KeyOf, MissingFieldMode, MissingFieldRead, MissingFieldResult, MutateFn, MutationOperationLike, MutationResult, MutationTransaction, PathStep, PersistedLookupOperation, PersistedRequestBody, PersistedResolution, PersistedResolverOptions, PushPullIterator, RequestInfo, RunMutationOptions, RunRouteOptions, RunRouteResult, SerializeGraphOptions, UserError, absorbHydrationPayload, bindGraph, bindScope, buildRouteContext, createFetchAdapter, createGraphIntegration, createGraphProxy, createGraphWsAdapter, createMutator, createPersistedResolver, errorMessage, graphHydrationScriptContent, hydrateGraph, invalidateValue, isGraphRef, normalizeValue, pagePointer, persistRootLinks, pushPullIterator, readGraphHydrationPayload, refetch, renderGraphHydrationScript, resolveFromCache, responseKeyCandidates, result, runMutation, runRoute, seedResult, selectionOf, serializeGraph, setReadTracker, toArgMap, trailOf };
+export { ActiveGraph, ActiveRequestGraph, BindGraphOptions, BoundGraph, BoundMutations, BuildRouteContextOptions, CacheResolution, CompiledOperation, CreateMutatorOptions, FetchAdapterOptions, FieldLookup, FieldValue, GRAPH_REF, GRAPH_TRAIL, GRAPH_TYPE, GraphBinding, GraphCache, GraphClientAdapter, GraphHydrationPayload, GraphIntegration, GraphIntegrationOptions, GraphOperation, GraphPagePointer, GraphQLError, GraphRef, GraphRequestContext, GraphResult, GraphRouteContext, GraphRuntime, GraphRuntimeOptions, GraphScope, GraphSelection, GraphWsAdapterOptions, GraphWsClient, GraphWsPayload, GraphWsSink, HydrateGraphOptions, HydratedGraph, KeyOf, MissingFieldMode, MissingFieldRead, MissingFieldResult, MutateFn, MutationOperationLike, MutationResult, MutationTransaction, PathStep, PersistedLookupOperation, PersistedRequestBody, PersistedResolution, PersistedResolverOptions, PushPullIterator, RequestInfo, RunMutationOptions, RunRouteOptions, RunRouteResult, SerializeGraphOptions, UserError, absorbHydrationPayload, bindGraph, bindScope, buildRouteContext, createFetchAdapter, createGraphIntegration, createGraphProxy, createGraphWsAdapter, createMutator, createPersistedResolver, errorMessage, graphHydrationScriptContent, hydrateGraph, invalidateValue, isGraphRef, normalizeValue, pagePointer, persistRootLinks, pushPullIterator, readGraphHydrationPayload, refetch, renderGraphHydrationScript, resolveFromCache, responseKeyCandidates, result, runMutation, runRoute, runServerMutation, seedResult, selectionOf, serializeGraph, setReadTracker, toArgMap, trailOf };

package/dist/index.mjs

@@ -1050,6 +1050,46 @@ async function runMutation(options) {
 		ok: true
 	};
 }
+/**
+* Server-side mutation execution: run a compiled mutation through the adapter and
+* surface `userErrors`, WITHOUT a client cache/runtime. This is the core of the
+* server `mutate()` primitive — server actions, webhooks, jobs, and proxy handlers
+* mutate Shopify without a hydrated read graph. Never rejects for logical failures;
+* inspect `ok`/`userErrors`/`errors`.
+*/
+async function runServerMutation(params) {
+	let result;
+	try {
+		result = await params.adapter.execute({
+			name: params.operation.name,
+			kind: "mutation",
+			document: params.operation.document
+		}, params.variables, params.context);
+	} catch (error) {
+		return {
+			userErrors: [],
+			errors: [{ message: errorMessage(error) }],
+			ok: false
+		};
+	}
+	if (result.errors && result.errors.length > 0) return {
+		userErrors: [],
+		errors: result.errors,
+		ok: false
+	};
+	const data = result.data;
+	const userErrors = data ? extractUserErrors(data) : [];
+	if (userErrors.length > 0) return {
+		data,
+		userErrors,
+		ok: false
+	};
+	return {
+		data,
+		userErrors: [],
+		ok: true
+	};
+}
 /** Invalidate a record by graph value (proxy) or raw ref — next read re-fetches. */
 function invalidateValue(runtime, value) {
 	const ref = toRef(value);
@@ -1218,6 +1258,25 @@ function createGraphIntegration(options) {
 			graph: active.graph
 		}, fn);
 	}
+	async function mutate(opName, vars, context) {
+		const op = options.operations[opName];
+		if (!op || op.kind !== "mutation") return {
+			ok: false,
+			userErrors: [],
+			errors: [{ message: `unknown mutation operation: ${opName}` }]
+		};
+		const toVariables = op.variables;
+		const variables = toVariables(vars) ?? {};
+		return runServerMutation({
+			operation: {
+				name: op.name,
+				document: op.document
+			},
+			variables,
+			adapter: options.adapter,
+			context: context ?? {}
+		});
+	}
 	return {
 		preload,
 		getGraph,
@@ -1225,7 +1284,8 @@ function createGraphIntegration(options) {
 		invalidate,
 		getActive,
 		refetch,
-		runInScope
+		runInScope,
+		mutate
 	};
 }
 /** Default missing-field resolution: leave each miss undefined (hybrid allow/warn). */
@@ -1409,4 +1469,4 @@ function createPersistedResolver(operations, options = {}) {
 	};
 }
 //#endregion
-export { GRAPH_REF, GRAPH_TRAIL, GRAPH_TYPE, GraphCache, GraphRuntime, GraphScope, MutationTransaction, absorbHydrationPayload, bindGraph, bindScope, buildRouteContext, createFetchAdapter, createGraphIntegration, createGraphProxy, createGraphWsAdapter, createMutator, createPersistedResolver, errorMessage, graphHydrationScriptContent, hydrateGraph, invalidateValue, isGraphRef, normalizeValue, pagePointer, persistRootLinks, pushPullIterator, readGraphHydrationPayload, refetch, renderGraphHydrationScript, resolveFromCache, responseKeyCandidates, result, runMutation, runRoute, seedResult, selectionOf, serializeGraph, setReadTracker, toArgMap, trailOf };
+export { GRAPH_REF, GRAPH_TRAIL, GRAPH_TYPE, GraphCache, GraphRuntime, GraphScope, MutationTransaction, absorbHydrationPayload, bindGraph, bindScope, buildRouteContext, createFetchAdapter, createGraphIntegration, createGraphProxy, createGraphWsAdapter, createMutator, createPersistedResolver, errorMessage, graphHydrationScriptContent, hydrateGraph, invalidateValue, isGraphRef, normalizeValue, pagePointer, persistRootLinks, pushPullIterator, readGraphHydrationPayload, refetch, renderGraphHydrationScript, resolveFromCache, responseKeyCandidates, result, runMutation, runRoute, runServerMutation, seedResult, selectionOf, serializeGraph, setReadTracker, toArgMap, trailOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gleanql/client",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "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.8"
+    "@gleanql/core": "0.1.9"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/integration.ts

@@ -4,6 +4,8 @@ import {
   createMutator,
   invalidateValue,
   runRoute,
+  runServerMutation,
+  type MutationResult,
   type BoundGraph,
   type BoundMutations,
   type CompiledOperation,
@@ -83,6 +85,17 @@ export interface GraphIntegration<Ctx extends Record<string, unknown>> {
   getGraph(requestInfo: RequestInfo<Ctx>): BoundGraph;
   /** The `graph.mutate.*` namespace for this request (throws if not preloaded). */
   getMutator(requestInfo: RequestInfo<Ctx>): BoundMutations;
+  /**
+   * Run a compiled mutation by name, server-side, WITHOUT a preloaded read graph —
+   * the executor behind the server `mutate()` primitive (server actions, webhooks,
+   * jobs). Resolves the op, maps `vars` via its factory, runs it through the
+   * adapter, and surfaces `userErrors`. Never rejects; inspect `ok`/`userErrors`.
+   */
+  mutate<TData = unknown>(
+    opName: string,
+    vars: unknown,
+    context?: GraphRequestContext,
+  ): Promise<MutationResult<TData>>;
   /** Invalidate a graph value / ref in this request's cache (refetch on next read). */
   invalidate(requestInfo: RequestInfo<Ctx>, value: GraphRef | unknown): void;
   /** Read the full active request state (runtime, roots, variables, ...). */
@@ -192,7 +205,28 @@ export function createGraphIntegration<Ctx extends Record<string, unknown> = Rec
     return options.scope.run({ runtime: active.runtime, graph: active.graph }, fn);
   }
 
-  return { preload, getGraph, getMutator, invalidate, getActive, refetch, runInScope };
+  async function mutate<TData = unknown>(
+    opName: string,
+    vars: unknown,
+    context?: GraphRequestContext,
+  ): Promise<MutationResult<TData>> {
+    const op = options.operations[opName];
+    if (!op || op.kind !== "mutation") {
+      return { ok: false, userErrors: [], errors: [{ message: `unknown mutation operation: ${opName}` }] };
+    }
+    // A mutation op's `variables` factory maps the selector `vars` (not the route
+    // context the read-typed signature expects) — same cast `resolveBoundOp` uses.
+    const toVariables = op.variables as (vars: unknown) => Record<string, unknown> | undefined;
+    const variables = (toVariables(vars) ?? {}) as Record<string, unknown>;
+    return runServerMutation<TData>({
+      operation: { name: op.name, document: op.document },
+      variables,
+      adapter: options.adapter,
+      context: context ?? ({} as GraphRequestContext),
+    });
+  }
+
+  return { preload, getGraph, getMutator, invalidate, getActive, refetch, runInScope, mutate };
 }
 
 /** Default missing-field resolution: leave each miss undefined (hybrid allow/warn). */

package/src/mutation.ts

@@ -133,6 +133,40 @@ export async function runMutation<TData = Record<string, unknown>>(
   return { data, userErrors: [], ok: true };
 }
 
+/**
+ * Server-side mutation execution: run a compiled mutation through the adapter and
+ * surface `userErrors`, WITHOUT a client cache/runtime. This is the core of the
+ * server `mutate()` primitive — server actions, webhooks, jobs, and proxy handlers
+ * mutate Shopify without a hydrated read graph. Never rejects for logical failures;
+ * inspect `ok`/`userErrors`/`errors`.
+ */
+export async function runServerMutation<TData = Record<string, unknown>>(params: {
+  readonly operation: { readonly name: string; readonly document: string };
+  readonly variables: Record<string, unknown>;
+  readonly adapter: GraphClientAdapter;
+  readonly context: GraphRequestContext;
+}): Promise<MutationResult<TData>> {
+  let result;
+  try {
+    result = await params.adapter.execute(
+      { name: params.operation.name, kind: "mutation", document: params.operation.document },
+      params.variables,
+      params.context,
+    );
+  } catch (error) {
+    return { userErrors: [], errors: [{ message: errorMessage(error) }], ok: false };
+  }
+
+  if (result.errors && result.errors.length > 0) {
+    return { userErrors: [], errors: result.errors, ok: false };
+  }
+
+  const data = result.data as TData | undefined;
+  const userErrors = data ? extractUserErrors(data as Record<string, unknown>) : [];
+  if (userErrors.length > 0) return { data, userErrors, ok: false };
+  return { data, userErrors: [], ok: true };
+}
+
 /** Invalidate a record by graph value (proxy) or raw ref — next read re-fetches. */
 export function invalidateValue(runtime: GraphRuntime, value: GraphRef | unknown): void {
   const ref = toRef(value);