# `error-codes`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Owns the stable `GRAPHQL_UI_GRAPHIQL.*` error-code registry consumed by the
GraphiQL UI plugin. Every code in the registry is thrown by a production
path in this package — the `error-codes.spec-conformance.test.ts` walks
the registry against the source tree to prove that no code is unused and
that no production throw site references an unregistered code.

The module also exports `GraphqlUiGraphiqlError`, a concrete
`SuaveplanError` subclass with a `graphiqlCode` mirror property. Callers
can discriminate failures from this package via `instanceof` or by
checking the stable `error.code` field; the mirror property exists so
TypeScript narrows to the narrow union without the consumer importing
the `GraphqlUiGraphiqlCode` alias.

## Features

- Two-code registry — `ASSET_MISSING`, `ENDPOINT_COLLISION`.
- `defineCodes("GRAPHQL_UI_GRAPHIQL", …)` namespace.
- `GraphqlUiGraphiqlError` extends `SuaveplanError` with a public
  constructor (required by the repo's `check-error-subclass-constructors`
  lint).
- Frozen registry — `Object.isFrozen(GRAPHQL_UI_GRAPHIQL_CODES) === true`.

## Usage: Basic

```ts
import {
    GRAPHQL_UI_GRAPHIQL_CODES,
    GraphqlUiGraphiqlError,
} from "@suaveplan/api-graphql-ui-graphiql";

throw new GraphqlUiGraphiqlError(
    GRAPHQL_UI_GRAPHIQL_CODES.ASSET_MISSING,
    "Bundled asset \"missing.js\" is not registered"
);
```

## Usage: Advanced

```ts
import {
    GRAPHQL_UI_GRAPHIQL_CODES,
    GraphqlUiGraphiqlError,
} from "@suaveplan/api-graphql-ui-graphiql";

try {
    mountGraphiqlUi();
} catch (err) {
    if (err instanceof GraphqlUiGraphiqlError) {
        if (err.code === GRAPHQL_UI_GRAPHIQL_CODES.ENDPOINT_COLLISION) {
            // Operator-facing: log the existing plugin from err.context.
            log.error({
                msg: "graphiql collision",
                existing: err.context?.existing,
            });
        }
    }
    throw err;
}
```

## API Reference

- `GRAPHQL_UI_GRAPHIQL_CODES` — frozen `Record<string, string>` of fully
  qualified codes.
- `GraphqlUiGraphiqlCode` — union of every value resolved through the
  registry.
- `class GraphqlUiGraphiqlError extends SuaveplanError<GraphqlUiGraphiqlCode>`
  — public constructor `(code, message, options?)` mirrors
  `SuaveplanError`'s signature.

## Implementation Notes

The class name (`GraphqlUiGraphiqlError`) is intentionally explicit so
stack traces and logs distinguish errors from this package vs the sibling
`api-graphql-ui-altair`. The public constructor is required by the
project-wide `check-error-subclass-constructors` lint added in
`cd454b3924`.