Initial Commit

packages/api-stack/api/api-graphql-yoga/src/error-codes/error-codes.md

@@ -0,0 +1,71 @@
+# `error-codes.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the frozen `GRAPHQL_YOGA.*` error-code registry and the
+`GraphqlYogaError` subclass of `SuaveplanError` used throughout the
+`@suaveplan/api-graphql-yoga` engine adapter. The registry is intentionally
+disjoint from the abstract `GRAPHQL.*` codes owned by
+`@suaveplan/api-graphql`: faults that any engine could surface (schema
+collision, missing resolver, unknown directive) live on the abstract
+namespace, while the ten codes here cover failures specific to Yoga's
+execution pipeline — document parsing, validation, depth/complexity guards,
+schema build, subscription transport, server-side timeout, introspection
+toggle, persisted-query registry, and uncaught resolver throws.
+
+## Features
+
+- 10 stable codes wired through `defineCodes("GRAPHQL_YOGA", ...)`.
+- Public `GraphqlYogaError` constructor (lint-rule compliant — see
+  `scripts/lint/check-error-subclass-constructors.ts`).
+- `instanceof GraphqlYogaError` narrows `code` to `GraphqlYogaErrorCode`.
+- `yogaCode` accessor for callers that already discriminated.
+
+## Usage: Basic
+
+```ts
+import {
+    GRAPHQL_YOGA_CODES,
+    GraphqlYogaError,
+} from "@suaveplan/api-graphql-yoga/error-codes";
+
+throw new GraphqlYogaError(
+    GRAPHQL_YOGA_CODES.PARSE_FAILED,
+    "GraphQL document parse failed",
+    { context: { query: "{ malformed" } }
+);
+```
+
+## Usage: Advanced
+
+```ts
+import { GraphqlYogaError } from "@suaveplan/api-graphql-yoga/error-codes";
+
+function handle(error: unknown): Response {
+    if (
+        error instanceof GraphqlYogaError &&
+        error.yogaCode === "GRAPHQL_YOGA.DEPTH_EXCEEDED"
+    ) {
+        return new Response("query too deep", { status: 400 });
+    }
+    throw error;
+}
+```
+
+## API Reference
+
+- `GRAPHQL_YOGA_CODES` — frozen record of every code constant.
+- `GraphqlYogaErrorCode` — union of every `GRAPHQL_YOGA.<NAME>` literal.
+- `class GraphqlYogaError extends SuaveplanError<GraphqlYogaErrorCode>` —
+  public constructor `(code, message, options?)`.
+
+## Implementation Notes
+
+Schema collisions across plugin contributions are raised with the abstract
+`GRAPHQL.SCHEMA_COLLISION` code from `@suaveplan/api-graphql`, NOT
+`GRAPHQL_YOGA.*` — this lets a host that switches between Apollo and Yoga
+preserve identical fault behaviour at the federation boundary.