@soda-gql/colocation-tools 0.2.0

package/README.md

@@ -0,0 +1,213 @@
+# @soda-gql/colocation-tools
+
+Utilities for colocating GraphQL fragments with components in soda-gql. This package provides tools for fragment composition and data masking patterns.
+
+## Features
+
+- **Fragment colocation** - Keep GraphQL fragments close to components that use them
+- **Data projection** - Create typed projections from fragment data
+- **Type safety** - Full TypeScript support for fragment composition
+
+## Installation
+
+```bash
+npm install @soda-gql/colocation-tools
+# or
+bun add @soda-gql/colocation-tools
+```
+
+## Usage
+
+### Fragment Colocation Pattern
+
+```typescript
+import { createProjection, createExecutionResultParser } from "@soda-gql/colocation-tools";
+import { userFragment } from "./graphql-system";
+
+// Create a projection with paths and handle function
+const userProjection = createProjection(userFragment, {
+  paths: ["$.user.id", "$.user.name"],
+  handle: (result) => {
+    if (result.isError()) return { error: result.error, user: null };
+    if (result.isEmpty()) return { error: null, user: null };
+    const data = result.unwrap();
+    return { error: null, user: data };
+  },
+});
+
+// Use with execution result parser
+const parser = createExecutionResultParser({
+  user: userProjection,
+});
+```
+
+### Embedding Fragments
+
+Fragments can be embedded in operations:
+
+```typescript
+import { gql } from "./graphql-system";
+import { userFragment } from "./UserCard";
+
+export const getUserQuery = gql.default(({ query }) =>
+  query.operation({ name: "GetUser" }, ({ f }) => [
+    f.user({ id: "1" })(userFragment.embed()),
+  ]),
+);
+```
+
+### Using with $colocate
+
+When composing multiple fragments in a single operation, use `$colocate` to prefix field selections with labels. The `createExecutionResultParser` will use these same labels to extract the corresponding data.
+
+#### Complete Workflow
+
+**Step 1: Define component fragments**
+
+```typescript
+// UserCard.tsx
+export const userCardFragment = gql.default(({ fragment }, { $var }) =>
+  fragment.Query({ variables: [$var("userId").scalar("ID:!")] }, ({ f, $ }) => [
+    f.user({ id: $.userId })(({ f }) => [f.id(), f.name(), f.email()]),
+  ]),
+);
+
+export const userCardProjection = createProjection(userCardFragment, {
+  paths: ["$.user"],
+  handle: (result) => {
+    if (result.isError()) return { error: result.error, user: null };
+    if (result.isEmpty()) return { error: null, user: null };
+    return { error: null, user: result.unwrap().user };
+  },
+});
+```
+
+**Step 2: Compose operation with $colocate**
+
+```typescript
+// UserPage.tsx
+import { userCardFragment, userCardProjection } from "./UserCard";
+import { postListFragment, postListProjection } from "./PostList";
+
+export const userPageQuery = gql.default(({ query }, { $var, $colocate }) =>
+  query.operation(
+    { name: "UserPage", variables: [$var("userId").scalar("ID:!")] },
+    ({ $ }) => [
+      $colocate({
+        userCard: userCardFragment.embed({ userId: $.userId }),
+        postList: postListFragment.embed({ userId: $.userId }),
+      }),
+    ],
+  ),
+);
+```
+
+**Step 3: Create parser with matching labels**
+
+```typescript
+const parseUserPageResult = createExecutionResultParser({
+  userCard: userCardProjection,
+  postList: postListProjection,
+});
+```
+
+**Step 4: Parse execution result**
+
+```typescript
+const result = await executeQuery(userPageQuery);
+const { userCard, postList } = parseUserPageResult(result);
+// userCard and postList contain the projected data
+```
+
+The labels in `$colocate` (`userCard`, `postList`) must match the labels in `createExecutionResultParser` for proper data routing.
+
+## API
+
+### createProjection
+
+Creates a typed projection from a fragment definition with specified paths and handler.
+
+```typescript
+import { createProjection } from "@soda-gql/colocation-tools";
+
+const projection = createProjection(fragment, {
+  // Field paths to extract (must start with "$.")
+  paths: ["$.user.id", "$.user.name"],
+  // Handler to transform the sliced result
+  handle: (result) => {
+    if (result.isError()) return { error: result.error, data: null };
+    if (result.isEmpty()) return { error: null, data: null };
+    return { error: null, data: result.unwrap() };
+  },
+});
+```
+
+### createProjectionAttachment
+
+Combines fragment definition and projection into a single export using `attach()`. This eliminates the need for separate projection definitions.
+
+```typescript
+import { createProjectionAttachment } from "@soda-gql/colocation-tools";
+import { gql } from "./graphql-system";
+
+export const postListFragment = gql
+  .default(({ fragment }, { $var }) =>
+    fragment.Query({ variables: [$var("userId").scalar("ID:!")] }, ({ f, $ }) => [
+      f.user({ id: $.userId })(({ f }) => [f.posts({})(({ f }) => [f.id(), f.title()])]),
+    ]),
+  )
+  .attach(
+    createProjectionAttachment({
+      paths: ["$.user.posts"],
+      handle: (result) => {
+        if (result.isError()) return { error: result.error, posts: null };
+        if (result.isEmpty()) return { error: null, posts: null };
+        return { error: null, posts: result.unwrap().user?.posts ?? [] };
+      },
+    }),
+  );
+
+// The fragment now has a .projection property
+postListFragment.projection;
+```
+
+**Benefits**:
+- Single export for both fragment and projection
+- Fragment can be passed directly to `createExecutionResultParser`
+- Reduces boilerplate when projection logic is simple
+
+**Using with createExecutionResultParser**:
+
+```typescript
+const parseResult = createExecutionResultParser({
+  userCard: { projection: userCardProjection }, // Explicit projection
+  postList: postListFragment,                    // Fragment with attached projection
+});
+```
+
+Both patterns work with the parser - it automatically detects fragments with attached projections.
+
+### createExecutionResultParser
+
+Creates a parser from labeled projections to process GraphQL execution results.
+
+```typescript
+import { createExecutionResultParser } from "@soda-gql/colocation-tools";
+
+const parser = createExecutionResultParser({
+  userData: userProjection,
+  postsData: postsProjection,
+});
+
+const results = parser(executionResult);
+// results.userData, results.postsData
+```
+
+## Related Packages
+
+- [@soda-gql/core](../core) - Core types and fragment definitions
+- [@soda-gql/runtime](../runtime) - Runtime operation handling
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,313 @@
+
+//#region packages/colocation-tools/src/projection.ts
+/**
+* Nominal type representing any slice selection regardless of schema specifics.
+* Encodes how individual slices map a concrete field path to a projection
+* function. Multiple selections allow slices to expose several derived values.
+*/
+var Projection = class {
+	constructor(paths, projector) {
+		this.projector = projector;
+		this.paths = paths.map((path) => createProjectionPath(path));
+		Object.defineProperty(this, "$infer", { get() {
+			throw new Error("This property is only for type meta. Do not access this property directly.");
+		} });
+	}
+	paths;
+};
+function createProjectionPath(path) {
+	const segments = path.split(".");
+	if (path === "$" || segments.length <= 1) throw new Error("Field path must not be only $ or empty");
+	return {
+		full: path,
+		segments: segments.slice(1)
+	};
+}
+
+//#endregion
+//#region packages/colocation-tools/src/create-projection.ts
+/**
+* Creates a type-safe projection from a Fragment.
+*
+* The projection extracts and transforms data from GraphQL execution results,
+* with full type inference from the Fragment's output type.
+*
+* Note: The Fragment parameter is used only for type inference.
+* The actual paths must be specified explicitly.
+*
+* @param _fragment - The Fragment to infer types from (used for type inference only)
+* @param options - Projection options including paths and handle function
+* @returns A Projection that can be used with createExecutionResultParser
+*
+* @example
+* ```typescript
+* const userFragment = gql(({ fragment }) =>
+*   fragment.Query({ variables: [...] }, ({ f, $ }) => [
+*     f.user({ id: $.userId })(({ f }) => [f.id(), f.name()]),
+*   ])
+* );
+*
+* const userProjection = createProjection(userFragment, {
+*   paths: ["$.user"],
+*   handle: (result) => {
+*     if (result.isError()) return { error: result.error, user: null };
+*     if (result.isEmpty()) return { error: null, user: null };
+*     const data = result.unwrap();
+*     return { error: null, user: data.user };
+*   },
+* });
+* ```
+*/
+const createProjection = (_fragment, options) => {
+	return new Projection(options.paths, options.handle);
+};
+const createProjectionAttachment = (options) => {
+	return {
+		name: "projection",
+		createValue: (fragment) => createProjection(fragment, options)
+	};
+};
+
+//#endregion
+//#region packages/colocation-tools/src/utils/map-values.ts
+function mapValues(obj, fn) {
+	return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, fn(value, key)]));
+}
+
+//#endregion
+//#region packages/colocation-tools/src/projection-path-graph.ts
+function createPathGraph(paths) {
+	const intermediate = paths.reduce((acc, { label, raw, segments: [segment, ...segments] }) => {
+		if (segment) (acc[segment] || (acc[segment] = [])).push({
+			label,
+			raw,
+			segments
+		});
+		return acc;
+	}, {});
+	return {
+		matches: paths.map(({ label, raw, segments }) => ({
+			label,
+			path: raw,
+			exact: segments.length === 0
+		})),
+		children: mapValues(intermediate, (paths$1) => createPathGraph(paths$1))
+	};
+}
+/**
+* Creates a projection path graph from slice entries with field prefixing.
+* Each slice's paths are prefixed with the slice label for disambiguation.
+*/
+function createPathGraphFromSliceEntries(fragments) {
+	return createPathGraph(Object.entries(fragments).flatMap(([label, slice]) => Array.from(new Map(slice.projection.paths.map(({ full: raw, segments }) => {
+		const [first, ...rest] = segments;
+		return [raw, {
+			label,
+			raw,
+			segments: [`${label}_${first}`, ...rest]
+		}];
+	})).values())));
+}
+
+//#endregion
+//#region packages/colocation-tools/src/sliced-execution-result.ts
+/** Runtime guard interface shared by all slice result variants. */
+var SlicedExecutionResultGuards = class {
+	isSuccess() {
+		return this.type === "success";
+	}
+	isError() {
+		return this.type === "error";
+	}
+	isEmpty() {
+		return this.type === "empty";
+	}
+	constructor(type) {
+		this.type = type;
+	}
+};
+/** Variant representing an empty payload (no data, no error). */
+var SlicedExecutionResultEmpty = class extends SlicedExecutionResultGuards {
+	constructor() {
+		super("empty");
+	}
+	unwrap() {
+		return null;
+	}
+	safeUnwrap() {
+		return {
+			data: void 0,
+			error: void 0
+		};
+	}
+};
+/** Variant representing a successful payload. */
+var SlicedExecutionResultSuccess = class extends SlicedExecutionResultGuards {
+	constructor(data, extensions) {
+		super("success");
+		this.data = data;
+		this.extensions = extensions;
+	}
+	unwrap() {
+		return this.data;
+	}
+	safeUnwrap(transform) {
+		return {
+			data: transform(this.data),
+			error: void 0
+		};
+	}
+};
+/** Variant representing an error payload. */
+var SlicedExecutionResultError = class extends SlicedExecutionResultGuards {
+	constructor(error, extensions) {
+		super("error");
+		this.error = error;
+		this.extensions = extensions;
+	}
+	unwrap() {
+		throw this.error;
+	}
+	safeUnwrap() {
+		return {
+			data: void 0,
+			error: this.error
+		};
+	}
+};
+
+//#endregion
+//#region packages/colocation-tools/src/parse-execution-result.ts
+const createPathGraphFromSlices = createPathGraphFromSliceEntries;
+function* generateErrorMapEntries(errors, projectionPathGraph) {
+	for (const error of errors) {
+		const errorPath = error.path ?? [];
+		let stack = projectionPathGraph;
+		for (let i = 0; i <= errorPath.length; i++) {
+			const segment = errorPath[i];
+			if (segment == null || typeof segment === "number") {
+				yield* stack.matches.map(({ label, path }) => ({
+					label,
+					path,
+					error
+				}));
+				break;
+			}
+			yield* stack.matches.filter(({ exact }) => exact).map(({ label, path }) => ({
+				label,
+				path,
+				error
+			}));
+			const next = stack.children[segment];
+			if (!next) break;
+			stack = next;
+		}
+	}
+}
+const createErrorMaps = (errors, projectionPathGraph) => {
+	const errorMaps = {};
+	for (const { label, path, error } of generateErrorMapEntries(errors ?? [], projectionPathGraph)) {
+		const mapPerLabel = errorMaps[label] || (errorMaps[label] = {});
+		(mapPerLabel[path] || (mapPerLabel[path] = [])).push({ error });
+	}
+	return errorMaps;
+};
+const accessDataByPathSegments = (data, pathSegments) => {
+	let current = data;
+	for (const segment of pathSegments) {
+		if (current == null) return { error: /* @__PURE__ */ new Error("No data") };
+		if (typeof current !== "object") return { error: /* @__PURE__ */ new Error("Incorrect data type") };
+		if (Array.isArray(current)) return { error: /* @__PURE__ */ new Error("Incorrect data type") };
+		current = current[segment];
+	}
+	return { data: current };
+};
+/**
+* Creates an execution result parser for composed operations.
+* The parser maps GraphQL errors and data to their corresponding slices
+* based on the projection path graph.
+*
+* @param slices - Object mapping labels to projections
+* @returns A parser function that takes a NormalizedExecutionResult and returns parsed slices
+*
+* @example
+* ```typescript
+* const parser = createExecutionResultParser({
+*   userCard: userCardProjection,
+*   posts: postsProjection,
+* });
+*
+* const results = parser({
+*   type: "graphql",
+*   body: { data, errors },
+* });
+* ```
+*/
+const createExecutionResultParser = (slices) => {
+	const projectionPathGraph = createPathGraphFromSlices(slices);
+	const fragments = slices;
+	const prepare = (result) => {
+		if (result.type === "graphql") {
+			const errorMaps = createErrorMaps(result.body.errors, projectionPathGraph);
+			return {
+				...result,
+				errorMaps
+			};
+		}
+		if (result.type === "non-graphql-error") return {
+			...result,
+			error: new SlicedExecutionResultError({
+				type: "non-graphql-error",
+				error: result.error
+			})
+		};
+		if (result.type === "empty") return {
+			...result,
+			error: new SlicedExecutionResultEmpty()
+		};
+		throw new Error("Invalid result type", { cause: result });
+	};
+	return (result) => {
+		const prepared = prepare(result);
+		const entries = Object.entries(fragments).map(([label, fragment]) => {
+			const { projection } = fragment;
+			if (prepared.type === "graphql") {
+				const matchedErrors = projection.paths.flatMap(({ full: raw }) => prepared.errorMaps[label]?.[raw] ?? []);
+				const uniqueErrors = Array.from(new Set(matchedErrors.map(({ error }) => error)).values());
+				if (uniqueErrors.length > 0) return [label, projection.projector(new SlicedExecutionResultError({
+					type: "graphql-error",
+					errors: uniqueErrors
+				}))];
+				const dataResults = projection.paths.map(({ segments }) => {
+					const [first, ...rest] = segments;
+					const prefixedSegments = [`${label}_${first}`, ...rest];
+					return prepared.body.data ? accessDataByPathSegments(prepared.body.data, prefixedSegments) : { error: /* @__PURE__ */ new Error("No data") };
+				});
+				if (dataResults.some(({ error }) => error)) {
+					const errors = dataResults.flatMap(({ error }) => error ? [error] : []);
+					return [label, projection.projector(new SlicedExecutionResultError({
+						type: "parse-error",
+						errors
+					}))];
+				}
+				const dataList = dataResults.map(({ data }) => data);
+				return [label, projection.projector(new SlicedExecutionResultSuccess(dataList))];
+			}
+			if (prepared.type === "non-graphql-error") return [label, projection.projector(prepared.error)];
+			if (prepared.type === "empty") return [label, projection.projector(prepared.error)];
+			throw new Error("Invalid result type", { cause: prepared });
+		});
+		return Object.fromEntries(entries);
+	};
+};
+
+//#endregion
+exports.Projection = Projection;
+exports.SlicedExecutionResultEmpty = SlicedExecutionResultEmpty;
+exports.SlicedExecutionResultError = SlicedExecutionResultError;
+exports.SlicedExecutionResultSuccess = SlicedExecutionResultSuccess;
+exports.createExecutionResultParser = createExecutionResultParser;
+exports.createPathGraphFromSliceEntries = createPathGraphFromSliceEntries;
+exports.createProjection = createProjection;
+exports.createProjectionAttachment = createProjectionAttachment;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["projector: (result: AnySlicedExecutionResult) => TProjected","paths","type: \"success\" | \"error\" | \"empty\"","data: TData","extensions?: unknown","error: NormalizedError","errorMaps: { [label: string]: { [path: string]: { error: GraphQLFormattedError }[] } }","current: unknown"],"sources":["../src/projection.ts","../src/create-projection.ts","../src/utils/map-values.ts","../src/projection-path-graph.ts","../src/sliced-execution-result.ts","../src/parse-execution-result.ts"],"sourcesContent":["import type { AnySlicedExecutionResult } from \"./sliced-execution-result\";\nimport type { Tuple } from \"./utils/type-utils\";\n\n/** Shape of a single selection slice projection. */\n// biome-ignore lint/suspicious/noExplicitAny: Type alias for any Projection regardless of projected type\nexport type AnyProjection = Projection<any>;\n\ndeclare const __PROJECTION_BRAND__: unique symbol;\n/**\n * Nominal type representing any slice selection regardless of schema specifics.\n * Encodes how individual slices map a concrete field path to a projection\n * function. Multiple selections allow slices to expose several derived values.\n */\nexport class Projection<TProjected> {\n  declare readonly [__PROJECTION_BRAND__]: void;\n\n  declare readonly $infer: { readonly output: TProjected };\n\n  constructor(\n    paths: Tuple<string>,\n    public readonly projector: (result: AnySlicedExecutionResult) => TProjected,\n  ) {\n    this.paths = paths.map((path) => createProjectionPath(path));\n\n    Object.defineProperty(this, \"$infer\", {\n      get() {\n        throw new Error(\"This property is only for type meta. Do not access this property directly.\");\n      },\n    });\n  }\n\n  public readonly paths: ProjectionPath[];\n}\n\nexport type ProjectionPath = {\n  full: string;\n  segments: Tuple<string>;\n};\n\nfunction createProjectionPath(path: string): ProjectionPath {\n  const segments = path.split(\".\");\n  if (path === \"$\" || segments.length <= 1) {\n    throw new Error(\"Field path must not be only $ or empty\");\n  }\n\n  return {\n    full: path,\n    segments: segments.slice(1) as Tuple<string>,\n  };\n}\n\nexport type InferExecutionResultProjection<TProjection extends AnyProjection> = ReturnType<TProjection[\"projector\"]>;\n","import type { Fragment, GqlElementAttachment } from \"@soda-gql/core\";\nimport { Projection } from \"./projection\";\nimport type { SlicedExecutionResult } from \"./sliced-execution-result\";\nimport type { Tuple } from \"./utils/type-utils\";\n\n// biome-ignore lint/suspicious/noExplicitAny: Type alias for any Fragment regardless of type parameters\ntype AnyFragment = Fragment<string, any, any, any>;\n\n/**\n * Options for creating a projection from a Fragment.\n */\nexport type CreateProjectionOptions<TOutput extends object, TProjected> = {\n  /**\n   * Field paths to extract from the execution result.\n   * Each path starts with \"$.\" and follows the field selection structure.\n   *\n   * @example\n   * ```typescript\n   * paths: [\"$.user.id\", \"$.user.name\"]\n   * ```\n   */\n  paths: Tuple<string>;\n\n  /**\n   * Handler function to transform the sliced execution result.\n   * Receives a SlicedExecutionResult with the Fragment's output type.\n   * Handles all cases: success, error, and empty.\n   *\n   * @example\n   * ```typescript\n   * handle: (result) => {\n   *   if (result.isError()) return { error: result.error, data: null };\n   *   if (result.isEmpty()) return { error: null, data: null };\n   *   const data = result.unwrap();\n   *   return { error: null, data: { userId: data.user.id } };\n   * }\n   * ```\n   */\n  handle: (result: SlicedExecutionResult<TOutput>) => TProjected;\n};\n\n/**\n * Creates a type-safe projection from a Fragment.\n *\n * The projection extracts and transforms data from GraphQL execution results,\n * with full type inference from the Fragment's output type.\n *\n * Note: The Fragment parameter is used only for type inference.\n * The actual paths must be specified explicitly.\n *\n * @param _fragment - The Fragment to infer types from (used for type inference only)\n * @param options - Projection options including paths and handle function\n * @returns A Projection that can be used with createExecutionResultParser\n *\n * @example\n * ```typescript\n * const userFragment = gql(({ fragment }) =>\n *   fragment.Query({ variables: [...] }, ({ f, $ }) => [\n *     f.user({ id: $.userId })(({ f }) => [f.id(), f.name()]),\n *   ])\n * );\n *\n * const userProjection = createProjection(userFragment, {\n *   paths: [\"$.user\"],\n *   handle: (result) => {\n *     if (result.isError()) return { error: result.error, user: null };\n *     if (result.isEmpty()) return { error: null, user: null };\n *     const data = result.unwrap();\n *     return { error: null, user: data.user };\n *   },\n * });\n * ```\n */\nexport const createProjection = <TFragment extends AnyFragment, TProjected>(\n  _fragment: TFragment,\n  options: CreateProjectionOptions<TFragment[\"$infer\"][\"output\"], TProjected>,\n): Projection<TProjected> => {\n  return new Projection(options.paths, options.handle);\n};\n\nexport const createProjectionAttachment = <TFragment extends AnyFragment, TProjected>(\n  options: CreateProjectionOptions<NoInfer<TFragment>[\"$infer\"][\"output\"], TProjected>,\n): GqlElementAttachment<TFragment, \"projection\", Projection<TProjected>> => {\n  return {\n    name: \"projection\",\n    createValue: (fragment) => createProjection(fragment, options),\n  };\n};\n","type ArgEntries<T extends object> = { [K in keyof T]-?: [value: T[K], key: K] }[keyof T];\ntype Entries<T extends object> = { [K in keyof T]: [key: K, value: T[K]] }[keyof T];\n\nexport function mapValues<TObject extends object, TMappedValue>(\n  obj: TObject,\n  fn: (...args: ArgEntries<TObject>) => TMappedValue,\n): {\n  [K in keyof TObject]: TMappedValue;\n} {\n  return Object.fromEntries((Object.entries(obj) as Entries<TObject>[]).map(([key, value]) => [key, fn(value, key)])) as {\n    [K in keyof TObject]: TMappedValue;\n  };\n}\n","import type { AnyProjection } from \"./projection\";\nimport { mapValues } from \"./utils/map-values\";\n\n/**\n * Node in the projection path graph tree.\n * Used for mapping GraphQL errors and data to their corresponding slices.\n */\nexport type ProjectionPathGraphNode = {\n  readonly matches: { label: string; path: string; exact: boolean }[];\n  readonly children: { readonly [segment: string]: ProjectionPathGraphNode };\n};\n\n/**\n * Payload from a slice that contains projection.\n */\nexport type AnySlicePayload = {\n  readonly projection: AnyProjection;\n};\n\nexport type AnySlicePayloads = Record<string, AnySlicePayload>;\n\ntype ExecutionResultProjectionPathGraphIntermediate = {\n  [segment: string]: { label: string; raw: string; segments: string[] }[];\n};\n\nfunction createPathGraph(paths: ExecutionResultProjectionPathGraphIntermediate[string]): ProjectionPathGraphNode {\n  const intermediate = paths.reduce(\n    (acc: ExecutionResultProjectionPathGraphIntermediate, { label, raw, segments: [segment, ...segments] }) => {\n      if (segment) {\n        (acc[segment] || (acc[segment] = [])).push({ label, raw, segments });\n      }\n      return acc;\n    },\n    {},\n  );\n\n  return {\n    matches: paths.map(({ label, raw, segments }) => ({ label, path: raw, exact: segments.length === 0 })),\n    children: mapValues(intermediate, (paths) => createPathGraph(paths)),\n  } satisfies ProjectionPathGraphNode;\n}\n\n/**\n * Creates a projection path graph from slice entries with field prefixing.\n * Each slice's paths are prefixed with the slice label for disambiguation.\n */\nexport function createPathGraphFromSliceEntries(fragments: AnySlicePayloads) {\n  const paths = Object.entries(fragments).flatMap(([label, slice]) =>\n    Array.from(\n      new Map(\n        slice.projection.paths.map(({ full: raw, segments }) => {\n          const [first, ...rest] = segments;\n          return [raw, { label, raw, segments: [`${label}_${first}`, ...rest] }];\n        }),\n      ).values(),\n    ),\n  );\n\n  return createPathGraph(paths);\n}\n","/** Result-like wrapper types returned from slice projections. */\n\nimport type { NormalizedError } from \"./types\";\n\n// biome-ignore lint/suspicious/noExplicitAny: Type alias for any SlicedExecutionResult regardless of data type\nexport type AnySlicedExecutionResult = SlicedExecutionResult<any>;\n\n/**\n * Internal discriminated union describing the Result-like wrapper exposed to\n * slice selection callbacks.\n */\nexport type AnySlicedExecutionResultRecord = {\n  [path: string]: AnySlicedExecutionResult;\n};\n\nexport type SafeUnwrapResult<TTransformed, TError> =\n  | {\n      data?: never;\n      error?: never;\n    }\n  | {\n      data: TTransformed;\n      error?: never;\n    }\n  | {\n      data?: never;\n      error: TError;\n    };\n\n/** Utility signature returned by the safe unwrap helper. */\ntype SlicedExecutionResultCommon<TData, TError> = {\n  safeUnwrap<TTransformed>(transform: (data: TData) => TTransformed): SafeUnwrapResult<TTransformed, TError>;\n};\n\n/** Public union used by selection callbacks to inspect data, empty, or error states. */\nexport type SlicedExecutionResult<TData> =\n  | SlicedExecutionResultEmpty<TData>\n  | SlicedExecutionResultSuccess<TData>\n  | SlicedExecutionResultError<TData>;\n\n/** Runtime guard interface shared by all slice result variants. */\nclass SlicedExecutionResultGuards<TData> {\n  isSuccess(): this is SlicedExecutionResultSuccess<TData> {\n    return this.type === \"success\";\n  }\n  isError(): this is SlicedExecutionResultError<TData> {\n    return this.type === \"error\";\n  }\n  isEmpty(): this is SlicedExecutionResultEmpty<TData> {\n    return this.type === \"empty\";\n  }\n\n  constructor(private readonly type: \"success\" | \"error\" | \"empty\") {}\n}\n\n/** Variant representing an empty payload (no data, no error). */\nexport class SlicedExecutionResultEmpty<TData>\n  extends SlicedExecutionResultGuards<TData>\n  implements SlicedExecutionResultCommon<TData, NormalizedError>\n{\n  constructor() {\n    super(\"empty\");\n  }\n\n  unwrap(): null {\n    return null;\n  }\n\n  safeUnwrap() {\n    return {\n      data: undefined,\n      error: undefined,\n    };\n  }\n}\n\n/** Variant representing a successful payload. */\nexport class SlicedExecutionResultSuccess<TData>\n  extends SlicedExecutionResultGuards<TData>\n  implements SlicedExecutionResultCommon<TData, NormalizedError>\n{\n  constructor(\n    public readonly data: TData,\n    public readonly extensions?: unknown,\n  ) {\n    super(\"success\");\n  }\n\n  unwrap(): TData {\n    return this.data;\n  }\n\n  safeUnwrap<TTransformed>(transform: (data: TData) => TTransformed) {\n    return {\n      data: transform(this.data),\n      error: undefined,\n    };\n  }\n}\n\n/** Variant representing an error payload. */\nexport class SlicedExecutionResultError<TData>\n  extends SlicedExecutionResultGuards<TData>\n  implements SlicedExecutionResultCommon<TData, NormalizedError>\n{\n  constructor(\n    public readonly error: NormalizedError,\n    public readonly extensions?: unknown,\n  ) {\n    super(\"error\");\n  }\n\n  unwrap(): never {\n    throw this.error;\n  }\n\n  safeUnwrap() {\n    return {\n      data: undefined,\n      error: this.error,\n    };\n  }\n}\n","import type { GraphQLFormattedError } from \"graphql\";\nimport { type AnySlicePayloads, createPathGraphFromSliceEntries, type ProjectionPathGraphNode } from \"./projection-path-graph\";\nimport { SlicedExecutionResultEmpty, SlicedExecutionResultError, SlicedExecutionResultSuccess } from \"./sliced-execution-result\";\nimport type { NormalizedExecutionResult } from \"./types\";\n\n// Internal function to build path graph from slices\nconst createPathGraphFromSlices = createPathGraphFromSliceEntries;\n\nfunction* generateErrorMapEntries(errors: readonly GraphQLFormattedError[], projectionPathGraph: ProjectionPathGraphNode) {\n  for (const error of errors) {\n    const errorPath = error.path ?? [];\n    let stack = projectionPathGraph;\n\n    for (\n      let i = 0;\n      // i <= errorPath.length to handle the case where the error path is empty\n      i <= errorPath.length;\n      i++\n    ) {\n      const segment = errorPath[i];\n\n      if (\n        // the end of the path\n        segment == null ||\n        // FieldPath does not support index access. We treat it as the end of the path.\n        typeof segment === \"number\"\n      ) {\n        yield* stack.matches.map(({ label, path }) => ({ label, path, error }));\n        break;\n      }\n\n      yield* stack.matches.filter(({ exact }) => exact).map(({ label, path }) => ({ label, path, error }));\n\n      const next = stack.children[segment];\n      if (!next) {\n        break;\n      }\n\n      stack = next;\n    }\n  }\n}\n\nconst createErrorMaps = (errors: readonly GraphQLFormattedError[] | undefined, projectionPathGraph: ProjectionPathGraphNode) => {\n  const errorMaps: { [label: string]: { [path: string]: { error: GraphQLFormattedError }[] } } = {};\n  for (const { label, path, error } of generateErrorMapEntries(errors ?? [], projectionPathGraph)) {\n    const mapPerLabel = errorMaps[label] || (errorMaps[label] = {});\n    const mapPerPath = mapPerLabel[path] || (mapPerLabel[path] = []);\n    mapPerPath.push({ error });\n  }\n  return errorMaps;\n};\n\nconst accessDataByPathSegments = (data: object, pathSegments: string[]) => {\n  let current: unknown = data;\n\n  for (const segment of pathSegments) {\n    if (current == null) {\n      return { error: new Error(\"No data\") };\n    }\n\n    if (typeof current !== \"object\") {\n      return { error: new Error(\"Incorrect data type\") };\n    }\n\n    if (Array.isArray(current)) {\n      return { error: new Error(\"Incorrect data type\") };\n    }\n\n    current = (current as Record<string, unknown>)[segment];\n  }\n\n  return { data: current };\n};\n\n/**\n * Creates an execution result parser for composed operations.\n * The parser maps GraphQL errors and data to their corresponding slices\n * based on the projection path graph.\n *\n * @param slices - Object mapping labels to projections\n * @returns A parser function that takes a NormalizedExecutionResult and returns parsed slices\n *\n * @example\n * ```typescript\n * const parser = createExecutionResultParser({\n *   userCard: userCardProjection,\n *   posts: postsProjection,\n * });\n *\n * const results = parser({\n *   type: \"graphql\",\n *   body: { data, errors },\n * });\n * ```\n */\nexport const createExecutionResultParser = <TSlices extends AnySlicePayloads>(slices: TSlices) => {\n  // Build path graph from slices\n  const projectionPathGraph = createPathGraphFromSlices(slices);\n  const fragments = slices;\n  const prepare = (result: NormalizedExecutionResult<object, object>) => {\n    if (result.type === \"graphql\") {\n      const errorMaps = createErrorMaps(result.body.errors, projectionPathGraph);\n\n      return { ...result, errorMaps };\n    }\n\n    if (result.type === \"non-graphql-error\") {\n      return { ...result, error: new SlicedExecutionResultError({ type: \"non-graphql-error\", error: result.error }) };\n    }\n\n    if (result.type === \"empty\") {\n      return { ...result, error: new SlicedExecutionResultEmpty() };\n    }\n\n    throw new Error(\"Invalid result type\", { cause: result satisfies never });\n  };\n\n  return (result: NormalizedExecutionResult<object, object>) => {\n    const prepared = prepare(result);\n\n    const entries = Object.entries(fragments).map(([label, fragment]) => {\n      const { projection } = fragment;\n\n      if (prepared.type === \"graphql\") {\n        const matchedErrors = projection.paths.flatMap(({ full: raw }) => prepared.errorMaps[label]?.[raw] ?? []);\n        const uniqueErrors = Array.from(new Set(matchedErrors.map(({ error }) => error)).values());\n\n        if (uniqueErrors.length > 0) {\n          return [label, projection.projector(new SlicedExecutionResultError({ type: \"graphql-error\", errors: uniqueErrors }))];\n        }\n\n        // Apply label prefix to first segment for data access (matching $colocate prefix pattern)\n        const dataResults = projection.paths.map(({ segments }) => {\n          const [first, ...rest] = segments;\n          const prefixedSegments = [`${label}_${first}`, ...rest];\n          return prepared.body.data\n            ? accessDataByPathSegments(prepared.body.data, prefixedSegments)\n            : { error: new Error(\"No data\") };\n        });\n        if (dataResults.some(({ error }) => error)) {\n          const errors = dataResults.flatMap(({ error }) => (error ? [error] : []));\n          return [label, projection.projector(new SlicedExecutionResultError({ type: \"parse-error\", errors }))];\n        }\n\n        const dataList = dataResults.map(({ data }) => data);\n        return [label, projection.projector(new SlicedExecutionResultSuccess(dataList))];\n      }\n\n      if (prepared.type === \"non-graphql-error\") {\n        return [label, projection.projector(prepared.error)];\n      }\n\n      if (prepared.type === \"empty\") {\n        return [label, projection.projector(prepared.error)];\n      }\n\n      throw new Error(\"Invalid result type\", { cause: prepared satisfies never });\n    });\n\n    return Object.fromEntries(entries);\n  };\n};\n"],"mappings":"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"}