`error-codes` — stable code registry for the static-principal adapter

(no submodules)

Purpose

Defines the AUTH_STATIC_PRINCIPAL.* error-code namespace and the AuthStaticPrincipalError concrete subclass of @suaveplan/error/SuaveplanError. This module is the single source of truth for every failure code the package can surface to a caller — wiring this registry into the host's error envelope is how a malformed test-time Principal configuration reaches the developer rather than silently producing a broken auth chain.

Codes are produced via defineCodes("AUTH_STATIC_PRINCIPAL", [...]) so the full literal value is e.g. "AUTH_STATIC_PRINCIPAL.INVALID_OPTIONS". The class augments the base error with authStaticPrincipalCode, providing a narrowed code property when consumers have already discriminated by instanceof.

Features

Stable, frozen AUTH_STATIC_PRINCIPAL_CODES map built via defineCodes so the prefix can't drift.
Discriminated-union friendly: AuthStaticPrincipalErrorCode is a literal union over the registry entries.
Carries arbitrary context (Zod issues, the offending field path) via the base SuaveplanError options bag.

Usage: Basic

import {
    AUTH_STATIC_PRINCIPAL_CODES,
    AuthStaticPrincipalError,
} from "@suaveplan/api-auth-static-principal/error-codes";

throw new AuthStaticPrincipalError(
    AUTH_STATIC_PRINCIPAL_CODES.INVALID_OPTIONS,
    "createStaticPrincipalResolver: options failed schema validation"
);

Usage: Advanced

Attach Zod issues so the caller can pinpoint the bad field without re-running validation:

import {
    AUTH_STATIC_PRINCIPAL_CODES,
    AuthStaticPrincipalError,
} from "@suaveplan/api-auth-static-principal/error-codes";
import z from "zod";

const parsed = OptionsSchema.safeParse(input);
if (!parsed.success) {
    throw new AuthStaticPrincipalError(
        AUTH_STATIC_PRINCIPAL_CODES.INVALID_PRINCIPAL,
        "principal failed schema validation",
        { context: { issues: parsed.error.issues } }
    );
}

API Reference

Symbol	Kind	Description
`AUTH_STATIC_PRINCIPAL_CODES`	constant	Frozen map of code constants. Keys are the short names; values are full.
`AuthStaticPrincipalErrorCode`	type	Literal union over the registry values.
`AuthStaticPrincipalError`	class	`SuaveplanError` subclass typed against the code registry.

Implementation Notes

defineCodes joins the prefix with each suffix using a single . so the resulting strings match the host's structured-log code field. The class stores the code twice — once in the inherited code slot and once in the narrower authStaticPrincipalCode slot — so callers that already narrowed by instanceof get a precisely-typed code field without a follow-up as.

The package's static-principal resolver never throws at request time; both codes are construction-time only. This is deliberate — every per-request failure for fixed-principal tests should manifest in the test assertion, not in the auth pipeline.

3.3 KiB Raw Blame History

error-codes — stable code registry for the static-principal adapter