`error-codes` — stable Router-Hono error registry

(no submodules)

Purpose

This module defines the canonical, frozen error-code namespace ROUTER_HONO.* shared by every production path inside @suaveplan/api-router-hono. Stable codes are how downstream observers (@suaveplan/api-host, structured-log consumers, OpenTelemetry dashboards) discriminate adapter failures from generic application errors without resorting to brittle string matching on error.message.

The registry is intentionally narrow — Hono itself owns most failure modes (404, 405, body parse, etc.) and surfaces them as ordinary HTTP responses. The two ROUTER_HONO.* codes carved out here cover the two scenarios where the adapter cannot delegate cleanly to Hono: a Hono-internal throw bubbling through the bridge, and a programmer-supplied peer (getHonoApp() consumers handing back a non-Hono shim).

Features

ROUTER_HONO.HONO_INTERNAL_ERROR — wraps any unexpected throw originating inside the Hono request/response bridge.
ROUTER_HONO.INVALID_HONO_PEER — guard for the getHonoApp() accessor and middleware-adapter when a non-Hono value is supplied.
RouterHonoError extends SuaveplanError<RouterHonoCode> so cause chains and Zod-validated wire format flow through @suaveplan/error unchanged.
defineCodes produces a frozen, namespaced map — duplicate codes fail at module load.

Usage: Basic

import { ROUTER_HONO_CODES, RouterHonoError } from "@suaveplan/api-router-hono/error-codes";

throw new RouterHonoError(
    ROUTER_HONO_CODES.HONO_INTERNAL_ERROR,
    "hono raised during dispatch",
    { cause: caught },
);

Usage: Advanced

import { RouterHonoError } from "@suaveplan/api-router-hono/error-codes";
import type { RouterHonoCode } from "@suaveplan/api-router-hono/error-codes";

function handle(err: unknown): RouterHonoCode | null {
    if (err instanceof RouterHonoError) return err.code;
    return null;
}

API Reference

ROUTER_HONO_CODES — Readonly<Record<"HONO_INTERNAL_ERROR" | "INVALID_HONO_PEER", "ROUTER_HONO.HONO_INTERNAL_ERROR" | "ROUTER_HONO.INVALID_HONO_PEER">>.
RouterHonoCode — string-literal union of the resolved codes.
RouterHonoError — SuaveplanError<RouterHonoCode> subclass with code, message, optional cause, optional context.

Implementation Notes

defineCodes enforces alphabetisation and uniqueness at build time. Adding a code requires extending the tuple here AND wiring at least one production throw site (see adapter.ts and middleware-adapter.ts). The registry is consumed by the error-codes.test.ts enumeration which asserts every entry maps to a value of the form ROUTER_HONO.<NAME> so observers can pattern-match the namespace prefix.

2.8 KiB Raw Blame History

error-codes — stable Router-Hono error registry