# `error-codes`

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

## Purpose

Stable error-code registry for `@suaveplan/api-graphql`. Every public failure
path raises a `GraphqlError` carrying one of these namespaced `GRAPHQL.*`
codes; the host's `ErrorEnvelope` writer maps them directly to the JSON wire
shape declared by `@suaveplan/api-types/errors`.

Centralising the registry here lets engine adapters (`api-graphql-yoga`,
`api-graphql-apollo`) inherit the seven base codes and add engine-specific
codes under a longer namespace (`GRAPHQL.YOGA.*`) without colliding with the
contract layer.

## Features

- Seven frozen codes covering schema federation, resolver wiring, loader
  registration, directive lookup, subscription transport availability, and
  strict-mode namespace enforcement.
- Typed `GraphqlError` subclass — `instanceof` narrows the `code` field to
  `GraphqlErrorCode`.
- Constructor widened to `public` so callers may instantiate directly.
- Side-effect import from the package barrel surfaces the registry at
  load time (matches `api-plugin`'s pattern).

## Usage: Basic

```ts
import { GRAPHQL_CODES, GraphqlError } from "@suaveplan/api-graphql/error-codes";

throw new GraphqlError(
    GRAPHQL_CODES.SCHEMA_COLLISION,
    "two plugins declare Query.users"
);
```

## Usage: Advanced

Attach structured detail for the wire envelope:

```ts
throw new GraphqlError(
    "GRAPHQL.SCHEMA_COLLISION",
    "schema collision on Query.users between plugins Billing and Identity",
    {
        details: {
            path: "Query.users",
            plugins: ["Billing", "Identity"],
        },
    }
);
```

The host's error-envelope writer pipes `details` straight into the JSON
response without modification.

## API Reference

- `GRAPHQL_CODES` — frozen record `{ SCHEMA_COLLISION, RESOLVER_MISSING,
  LOADER_DUPLICATE_NAME, LOADER_NOT_REGISTERED, DIRECTIVE_UNKNOWN,
  SUBSCRIPTION_TRANSPORT_UNAVAILABLE, NAMESPACE_REQUIRED }`. Values are the
  fully-qualified `GRAPHQL.<NAME>` strings.
- `GraphqlErrorCode` — string union derived from `GRAPHQL_CODES`.
- `GraphqlError extends SuaveplanError<GraphqlErrorCode>` — adds a
  read-only `graphqlCode` mirror for ergonomic branching.

## Implementation Notes

`defineCodes` returns a `Object.freeze`d record so the union literal is
preserved at the type level (TypeScript widens otherwise). Callers may
branch on the string literal (`"GRAPHQL.SCHEMA_COLLISION"`) or the typed
constant (`GRAPHQL_CODES.SCHEMA_COLLISION`) — both produce the same value.

Concrete engines that raise additional codes do so via their own
`defineCodes("GRAPHQL.YOGA", [...])` registry; this package owns only the
contract-layer codes that map to engine-agnostic failure modes.