`error-codes`

(no submodules)

Purpose

The error-codes module owns the stable, namespaced registry of every error code that @suaveplan/react-control-surface is allowed to throw, plus the ReactControlSurfaceError subclass that wraps the foundation SuaveplanError base. Codes are produced through defineCodes("REACT_CONTROL_SURFACE", ...) so a single source of truth governs both the runtime string values and the TypeScript literal-union narrowing that downstream packages depend on.

This module never throws on its own — it is a passive registry. Throwing is the responsibility of higher layers (the binding registry for missing handlers, the runtime walker for unknown kinds, the validation layer for malformed schemas). Centralising metadata here keeps the documentation shipped next to the code that emits it and lets the test suite cross-check the codes set against the metadata table on every CI run.

Features

Three documented codes: UNKNOWN_KIND, BINDING_HANDLER_MISSING, INVALID_SCHEMA.
Frozen metadata table keyed by code with a human-readable description and severity ("warning" | "error").
ReactControlSurfaceError subclass with category narrowing, severity reflected in the error's name, structured context, and a cause chain.
registerReactControlSurfaceErrorCodes() idempotent registration hook for parity with sibling packages.

Usage: Basic

import {
    REACT_CONTROL_SURFACE_CODES,
    ReactControlSurfaceError,
} from "@suaveplan/react-control-surface/error-codes";

throw new ReactControlSurfaceError(
    REACT_CONTROL_SURFACE_CODES.UNKNOWN_KIND,
    "react-control-surface.unknown-kind",
    { context: { kind: "not-a-thing" } }
);

Usage: Advanced

import {
    REACT_CONTROL_SURFACE_CODES,
    REACT_CONTROL_SURFACE_ERROR_METADATA,
    ReactControlSurfaceError,
} from "@suaveplan/react-control-surface/error-codes";

function failBinding(kind: string, cause?: unknown): never {
    const code = REACT_CONTROL_SURFACE_CODES.BINDING_HANDLER_MISSING;
    const severity = REACT_CONTROL_SURFACE_ERROR_METADATA[code].severity;
    if (severity === "error") {
        throw new ReactControlSurfaceError(
            code,
            "react-control-surface.binding-handler-missing",
            { context: { kind }, cause }
        );
    }
    return undefined as never;
}

API Reference

REACT_CONTROL_SURFACE_CODES — frozen record { UNKNOWN_KIND, BINDING_HANDLER_MISSING, INVALID_SCHEMA }.
ReactControlSurfaceErrorCode — literal union of the three code strings.
REACT_CONTROL_SURFACE_ERROR_METADATA — frozen Record<code, { description, severity }>.
ReactControlSurfaceError — SuaveplanError subclass with category = "react-control-surface".
registerReactControlSurfaceErrorCodes(): void — idempotent no-op hook.

Implementation Notes

The metadata is created via Object.freeze at module load so consumers cannot mutate it at runtime. defineCodes returns a Readonly<Record<key, string>> whose value strings are the namespaced literal codes (e.g. "REACT_CONTROL_SURFACE.UNKNOWN_KIND"). Severity is encoded both in the metadata table and the constructed Error#name, which keeps log scrapers that filter by name in sync with the severity model. The class is final from the consumer's point of view — extending it further would create a parallel hierarchy and is explicitly out of scope.

3.4 KiB Raw Blame History

error-codes