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

(no submodules)

Purpose

error-codes defines the stable GRAPHQL_APOLLO.* namespace plus the GraphqlApolloError class consumed by every other module in the @suaveplan/api-graphql-apollo package. It sits in the same shape as the sibling @suaveplan/api-graphql registry so callers can write a single instanceof SuaveplanError discriminator and narrow further on error.code.

The registry covers ten codes — request-document parse and validation failures, depth and complexity guard rejections, schema-build failures inside Apollo, the missing-transport case for subscriptions, request timeouts, introspection-denied responses, persisted-query lookup misses, and the resolver-attach catch-all. Every code is thrown by a production path; the conformance harness enforces that empirically.

Features

Frozen defineCodes("GRAPHQL_APOLLO", […]) registry — no untyped string ever escapes the package.
GraphqlApolloError exposes the code via both the inherited error.code and a narrowed graphqlApolloCode field; either narrows downstream code to the union of ten possible values.
Constructor preserves cause and context per the SuaveplanError contract — wrappers can attach the raw cause: Error for crash dumps.
The class sets this.name = "GraphqlApolloError" so logs surface the concrete subclass.

Usage: Basic

import {
    GRAPHQL_APOLLO_CODES,
    GraphqlApolloError,
} from "@suaveplan/api-graphql-apollo/error-codes";

throw new GraphqlApolloError(
    GRAPHQL_APOLLO_CODES.PARSE_FAILED,
    "request document failed to parse"
);

Usage: Advanced

Attach a cause and a context payload that the OTel span recorder will attach as event attributes:

import { GraphqlApolloError } from "@suaveplan/api-graphql-apollo/error-codes";

try {
    JSON.parse(maybeJson);
} catch (cause) {
    throw new GraphqlApolloError(
        "GRAPHQL_APOLLO.PARSE_FAILED",
        "persisted-query manifest is not valid JSON",
        { cause: cause as Error, context: { path: "./pq.json" } }
    );
}

API Reference

GRAPHQL_APOLLO_CODES — frozen object mapping each short name to its fully-qualified code string.
GraphqlApolloErrorCode — union of every code value resolved through GRAPHQL_APOLLO_CODES.
class GraphqlApolloError extends SuaveplanError<GraphqlApolloErrorCode>.
- constructor(code, message, options?)
- graphqlApolloCode — convenience accessor pre-narrowed to the GraphqlApolloErrorCode union.

Implementation Notes

The codes intentionally mirror the design-doc §10.5 list. Adding a new code requires (a) appending it to the defineCodes array, (b) wiring at least one production throw site, and (c) extending the conformance checklist. The name field is set so structured logs see GraphqlApolloError rather than the generic SuaveplanError. The class extends the abstract SuaveplanError directly — no intermediate base.

3.0 KiB Raw Permalink Blame History

error-codes — GRAPHQL_APOLLO.* registry