`error-codes` — `AUTH_CODES` registry

(no submodules)

Purpose

Defines the stable, namespaced error-code registry for the @suaveplan/api-auth package and the concrete AuthError class. Every code is reachable from a production throw site somewhere in the package (chain construction, chain execution, adapter registration, or principal-shape validation). The registry is frozen via defineCodes("AUTH", […]) so accidental drift between thrown codes and the documented set is impossible.

Consumers — including downstream concrete resolvers in Stages 4/6/8 such as api-auth-jwt, api-auth-anonymous, and api-auth-bearer-static — branch on the string literal ("AUTH.RESOLVER_THREW" etc.) or compare to the constant (AUTH_CODES.RESOLVER_THREW). The literal form is preferred at the API boundary; the constant is preferred inside the package itself so the linter flags typos as type errors.

Features

Frozen string-literal union of all four codes.
AuthError extends SuaveplanError<AuthErrorCode> so instanceof AuthError narrows code correctly.
Cause-chain propagation: the optional options.cause field is forwarded to the base class.
Public constructor (the base class is protected).

Usage: Basic

import { AUTH_CODES, AuthError } from "@suaveplan/api-auth/error-codes";

if (chain.length === 0) {
    throw new AuthError(AUTH_CODES.CHAIN_EMPTY, "at least one resolver required");
}

Usage: Advanced

Re-throw a resolver error with a cause chain and inspect it downstream:

import { AUTH_CODES, AuthError } from "@suaveplan/api-auth/error-codes";

try {
    await resolver.resolve(req);
} catch (cause) {
    throw new AuthError(AUTH_CODES.RESOLVER_THREW, "resolver A threw", {
        cause,
        context: { resolverIndex: 0 },
    });
}

import { AuthError } from "@suaveplan/api-auth/error-codes";

if (err instanceof AuthError && err.code === "AUTH.RESOLVER_THREW") {
    logger.warn("upstream session resolver failed", { cause: err.cause });
}

API Reference

Symbol	Kind	Description
`AUTH_CODES`	const	Frozen lookup `{ RESOLVER_THREW, CHAIN_EMPTY, … }`.
`AuthErrorCode`	type	Literal union of the four code strings.
`AuthError`	class	Concrete `SuaveplanError` subclass narrowed to `AuthErrorCode`.

Implementation Notes

defineCodes("AUTH", [...] as const) produces an object literal with string-literal value types, which is what gives AuthErrorCode its narrow union. Removing as const would widen the type to string.
The class field authCode mirrors code for ergonomic narrowing on pre-instantiated error objects (some test runners obscure the inherited code field via Proxy wrappers).
Code values follow the AUTH.<UPPER_SNAKE> template enforced by @suaveplan/api-types' ErrorCode template literal type.

3.1 KiB Raw Blame History

error-codes — AUTH_CODES registry