`error-codes` — `GRAPHQL_UI_ALTAIR.*` registry

(no submodules)

Purpose

error-codes is the package's single source of truth for the two stable error codes the Altair UI plugin emits. Centralising the codes here lets the factory, the asset map, and any downstream observability tooling import the literal strings from one location — no string-typos, no divergence between the wire format and the registry. The registry is frozen at module init and validated against the umbrella defineCodes contract from @suaveplan/error so accidental drift is caught at type check time, not at runtime.

Features

Two codes: GRAPHQL_UI_ALTAIR.ASSET_MISSING, GRAPHQL_UI_ALTAIR.ENDPOINT_COLLISION.
Concrete GraphqlUiAltairError class extending SuaveplanError.
altairCode narrows to GraphqlUiAltairErrorCode for exhaustive switch statements.
Compatible with the umbrella redaction + i18n + OTel span-event adapters shipped by @suaveplan/error.

Usage: Basic

import {
    GRAPHQL_UI_ALTAIR_CODES,
    GraphqlUiAltairError,
} from "@suaveplan/api-graphql-ui-altair/error-codes";

throw new GraphqlUiAltairError(
    GRAPHQL_UI_ALTAIR_CODES.ASSET_MISSING,
    "Asset not present in bundled map",
    { context: { path: "/graphql/ui/assets/missing.js" } }
);

Usage: Advanced

import {
    GRAPHQL_UI_ALTAIR_CODES,
    GraphqlUiAltairError,
} from "@suaveplan/api-graphql-ui-altair/error-codes";

function handle(err: unknown): number {
    if (err instanceof GraphqlUiAltairError) {
        switch (err.altairCode) {
            case GRAPHQL_UI_ALTAIR_CODES.ASSET_MISSING:
                return 404;
            case GRAPHQL_UI_ALTAIR_CODES.ENDPOINT_COLLISION:
                return 409;
        }
    }
    return 500;
}

API Reference

GRAPHQL_UI_ALTAIR_CODES — frozen record { ASSET_MISSING, ENDPOINT_COLLISION }.
GraphqlUiAltairErrorCode — discriminated union of the two literal strings.
class GraphqlUiAltairError extends SuaveplanError<GraphqlUiAltairErrorCode> — owns the altairCode accessor.

Implementation Notes

defineCodes("GRAPHQL_UI_ALTAIR", ...) produces the prefixed literal strings — agents must not hand-build the strings to avoid prefix drift. The error class delegates entirely to SuaveplanError for context serialisation, cause chains, and the wire-format adapter; the only local responsibility is preserving altairCode for instanceof narrowing in operator-facing error handlers. The two-code surface is intentionally minimal: the asset path is the only failure mode at HTTP boundary, and endpoint collision is the only failure mode at mount boundary. Adding a code requires an OpenSpec change so the registry shape never drifts silently between the spec and the runtime.

2.8 KiB Raw Blame History

error-codes — GRAPHQL_UI_ALTAIR.* registry