`error-codes.ts` — `OPENAPI_UI_SWAGGER.*` registry

(no submodules)

Purpose

This module owns the stable error-code registry for @suaveplan/api-openapi-ui-swagger. Every public failure path raises an OpenapiUiSwaggerError carrying one of the two namespaced codes, so consumers can discriminate without parsing message strings. The codes survive across releases and form part of the public contract; renaming one is a breaking change.

The registry is built via defineCodes("OPENAPI_UI_SWAGGER", [...]) from @suaveplan/error. The resulting object freezes the code map at module load, so attempts to mutate it from outside throw immediately. The companion OpenapiUiSwaggerError widens the SuaveplanError constructor to public (no factory required) and re-exposes the parsed code on a swaggerUiCode accessor for narrowing in instanceof branches.

Features

Two-entry registry: ASSETS_MISSING, INVALID_OPTIONS.
OpenapiUiSwaggerCode union literal type derived from the registry.
OpenapiUiSwaggerError extending SuaveplanError<OpenapiUiSwaggerCode>.
Side-effect import from src/index.ts so consumers picking up the package barrel get the registry initialised.

Usage: Basic

import {
    OPENAPI_UI_SWAGGER_CODES,
    OpenapiUiSwaggerError,
} from "@suaveplan/api-openapi-ui-swagger/error-codes";

throw new OpenapiUiSwaggerError(
    OPENAPI_UI_SWAGGER_CODES.INVALID_OPTIONS,
    "theme must be one of 'light' | 'dark' | 'system'"
);

Usage: Advanced

import { OpenapiUiSwaggerError } from "@suaveplan/api-openapi-ui-swagger/error-codes";

try {
    bootSwaggerUi(configFromOperator);
} catch (err) {
    if (
        err instanceof OpenapiUiSwaggerError &&
        err.swaggerUiCode === "ASSETS_MISSING"
    ) {
        // Fall back to a remote-CDN profile and report the gap.
        return bootSwaggerUi({ ...configFromOperator, uiAssets: "cdn" });
    }
    throw err;
}

API Reference

OPENAPI_UI_SWAGGER_CODES: Readonly<Record<"ASSETS_MISSING"|"INVALID_OPTIONS", string>>.
type OpenapiUiSwaggerCode = "OPENAPI_UI_SWAGGER.ASSETS_MISSING" | "OPENAPI_UI_SWAGGER.INVALID_OPTIONS".
class OpenapiUiSwaggerError extends SuaveplanError<OpenapiUiSwaggerCode> — public constructor (code, message, options?).

Implementation Notes

Adding a new code is a public-API change: bump the package version and add a **Verified by:** entry in the spec for the throw site that emits it. Removing a code is a breaking change.

The registry is intentionally tiny — Swagger UI is a presentation surface and most failures are configuration mistakes (caught by INVALID_OPTIONS) or asset-pipeline gaps (caught by ASSETS_MISSING). The conformance gate (conformance.ts) walks the registry and asserts each code is thrown from at least one non-test source file in this package.

2.8 KiB Raw Permalink Blame History

error-codes.ts — OPENAPI_UI_SWAGGER.* registry