# `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.