`error-codes`

(no submodules)

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

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:

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.freezed 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.

2.7 KiB Raw Blame History

error-codes