`error-codes`

(no submodules)

Purpose

error-codes.ts defines the stable error-code registry for @suaveplan/react-auth plus the ten typed ReactAuthError subclasses that wrap each code. Every code is registered through @suaveplan/error's defineCodes("REACT_AUTH", [...]), which produces a frozen { KEY: "REACT_AUTH.KEY" } map and forms the basis for programmatic error handling, OTel attribute tagging, and i18n key resolution. Each subclass extends ReactAuthError (which extends SuaveplanError<ReactAuthErrorCode>), carries its own constructor with structured context fields when appropriate, and is thrown from at least one production path. Consumers can catch either ReactAuthError for the family or a specific subclass for narrow handling.

Features

Frozen REACT_AUTH_CODES map with 10 stable codes.
Typed ReactAuthError base + 10 typed subclasses.
Structured cause chain support via SuaveplanError.
Optional context payload propagation (e.g. permission on ReactAuthPermissionDeniedError).
ReactAuthErrorCode union type for switch-narrowed handling.

Usage: Basic

import { ReactAuthError, ReactAuthConfigInvalidError } from "@suaveplan/react-auth";

try {
    createAuthClient({ baseURL: "not-a-url" });
} catch (err) {
    if (err instanceof ReactAuthConfigInvalidError) {
        console.error("config invalid", err.code, err.message);
    }
}

Usage: Advanced

Switch on error.code for routing across the family:

import {
    REACT_AUTH_CODES,
    type ReactAuthErrorCode,
    ReactAuthError,
} from "@suaveplan/react-auth";

function describe(err: unknown): string {
    if (!(err instanceof ReactAuthError)) return "unknown";
    const code: ReactAuthErrorCode = err.code;
    switch (code) {
        case REACT_AUTH_CODES.CONFIG_INVALID:
            return "configuration failure";
        case REACT_AUTH_CODES.CONTEXT_MISSING:
            return "provider not mounted";
        case REACT_AUTH_CODES.GUARD_PROPS_INVALID:
        case REACT_AUTH_CODES.GUARD_OPTIONS_INVALID:
            return "guard misuse";
        default:
            return err.code;
    }
}

API Reference

const REACT_AUTH_CODES — frozen map of 10 codes (CONFIG_INVALID, CONTEXT_MISSING, GUARD_PROPS_INVALID, GUARD_OPTIONS_INVALID, CLIENT_NOT_INITIALISED, BETTER_AUTH_RESPONSE_INVALID, SIGN_IN_FAILED, SIGN_UP_FAILED, SESSION_FETCH_FAILED, PERMISSION_DENIED).
type ReactAuthErrorCode — union of every code value.
class ReactAuthError extends SuaveplanError<ReactAuthErrorCode> — base.
class ReactAuthConfigInvalidError — invalid AuthClientConfig.
class ReactAuthContextMissingError — useAuth outside <AuthProvider>.
class ReactAuthGuardPropsInvalidError — invalid <AuthGuard> props.
class ReactAuthGuardOptionsInvalidError — invalid useAuthGuard options.
class ReactAuthClientNotInitialisedError — client used before construction completes.
class ReactAuthBetterAuthResponseInvalidError — payload outside the union shape.
class ReactAuthSignInFailedError — wrapper for sign-in failure (carries cause).
class ReactAuthSignUpFailedError — wrapper for sign-up failure (carries cause).
class ReactAuthSessionFetchFailedError — wrapper for session-fetch failure.
class ReactAuthPermissionDeniedError — permission check denied (carries permission context).

Implementation Notes

Every subclass takes an options object with message and optional cause/context fields. cause is normalised to Error | undefined (non-Error throwables are dropped so the cause chain never carries opaque values). The ReactAuthPermissionDeniedError constructor builds its message from the provided permission name when present, falling back to a generic string. The context object is propagated through SuaveplanError and surfaces both in the wire-format payload and on the OTel span event so error attribution flows through to dashboards.

4.0 KiB Raw Blame History

error-codes