`error-codes`

(no submodules)

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

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

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.

2.6 KiB Raw Blame History

error-codes