`error-codes`

(no submodules)

Purpose

Provides the stable error-code registry and the typed WsBunError subclass for @suaveplan/api-ws-bun. Every production failure path in the package routes through one of the ten WS_BUN.* codes defined here, which means a downstream consumer can branch on error.code === WS_BUN_CODES.TENANT_CAP_EXCEEDED without importing implementation modules.

The constants are frozen at module load time by defineCodes from @suaveplan/error, so consumers can compare against the namespaced literal string ("WS_BUN.HANDSHAKE_REJECTED") directly when that is convenient — for example inside a JSON-serialised error wire format or a Hono error handler.

Features

Ten-entry registry covering handshake, tenant caps, backpressure, heartbeat, reconnect token validation, reconnect-buffer wiring, subprotocols, close timeouts and principal expiry.
WsBunError extends SuaveplanError<WsBunErrorCode> so instanceof narrows the code field to the registry's literal union.
One raise* helper per code so every entry has a production throw-site (CI checklist 6.3).
Helpers attach a stable message prefix per code so logs stay grep-able.

Usage: Basic

import { raiseTenantCapExceeded, WS_BUN_CODES } from "@suaveplan/api-ws-bun";

try {
    raiseTenantCapExceeded("tenant-a", 1000);
} catch (err) {
    if ((err as { code?: string }).code === WS_BUN_CODES.TENANT_CAP_EXCEEDED) {
        // surface 429 to the caller
    }
}

Usage: Advanced

import {
    WS_BUN_CODES,
    WsBunError,
    type WsBunErrorCode,
} from "@suaveplan/api-ws-bun";

function logIfWsBun(error: unknown, logger: { error: (m: string) => void }) {
    if (error instanceof WsBunError) {
        const code: WsBunErrorCode = error.wsBunCode;
        logger.error(`${code}: ${error.message}`);
        return code === WS_BUN_CODES.HEARTBEAT_FAILED;
    }
    return false;
}

API Reference

WS_BUN_CODES — frozen Record<LiteralName, "WS_BUN.<LiteralName>"> produced by defineCodes. Keys: HANDSHAKE_REJECTED, TENANT_CAP_EXCEEDED, BACKPRESSURE_EVICTED, HEARTBEAT_FAILED, RECONNECT_TOKEN_INVALID, RECONNECT_TOKEN_EXPIRED, RECONNECT_BUFFER_MISS, SUBPROTOCOL_UNSUPPORTED, CLOSE_TIMEOUT, PRINCIPAL_EXPIRED.
WsBunError — concrete subclass of SuaveplanError<WsBunErrorCode> with a wsBunCode mirror property.
raise* helpers — one per code, all return never, all throw WsBunError with a pre-formatted message.

Implementation Notes

The raise* helpers exist not only as ergonomic shortcuts but as a forcing-function: CI rule §6.3 demands every code in the registry have at least one production raise-site. Concentrating the raise calls in this module guarantees that property regardless of how the engine internals evolve.

Codes are intentionally namespaced (WS_BUN.* rather than WS.*) so error reports never confuse this engine adapter with the abstract @suaveplan/api-ws contract package, which owns the parallel WS.* namespace.

3.0 KiB Raw Blame History

error-codes