`error-codes` — `WS_BROKER_REDIS_CODES`

(no submodules)

Purpose

This module defines the stable error-code registry for @suaveplan/api-ws-broker-redis. Every failure surface the broker emits at runtime — Redis connection drops, publish/subscribe failures, buffer reads and writes, oversize payloads, deserialise failures, configuration errors, reconnect exhaustion, and command timeouts — carries one of the ten WS_BROKER_REDIS.* codes defined here. Callers branch on the literal string value (or instanceof WsBrokerRedisError) to drive recovery logic.

The registry is closed: adding a new code requires an OpenSpec change so production dashboards and alerting rules keyed on the existing codes stay stable.

Features

Ten stable codes covering every documented failure surface.
defineCodes("WS_BROKER_REDIS", [...]) so the runtime values are auto-namespaced to WS_BROKER_REDIS.<NAME>.
WsBrokerRedisError subclass with a public constructor (lint-enforced), so callers can new WsBrokerRedisError(code, message, { cause }) directly rather than coercing through a factory.
Tied-off TypeScript literal union (WsBrokerRedisErrorCode) for exhaustive switch statements at call sites.

Usage: Basic

import {
    WS_BROKER_REDIS_CODES,
    WsBrokerRedisError,
} from "@suaveplan/api-ws-broker-redis/error-codes";

try {
    await broker.publish("orders", envelope);
} catch (err) {
    if (
        err instanceof WsBrokerRedisError &&
        err.brokerCode === WS_BROKER_REDIS_CODES.PAYLOAD_TOO_LARGE
    ) {
        // Drop or split — Redis is not going to accept this frame.
        return;
    }
    throw err;
}

Usage: Advanced

import {
    type WsBrokerRedisErrorCode,
    WS_BROKER_REDIS_CODES,
} from "@suaveplan/api-ws-broker-redis/error-codes";

function classify(code: WsBrokerRedisErrorCode): "retry" | "drop" | "fatal" {
    switch (code) {
        case WS_BROKER_REDIS_CODES.CONNECTION_LOST:
        case WS_BROKER_REDIS_CODES.TIMEOUT:
        case WS_BROKER_REDIS_CODES.PUBLISH_FAILED:
            return "retry";
        case WS_BROKER_REDIS_CODES.PAYLOAD_TOO_LARGE:
        case WS_BROKER_REDIS_CODES.DESERIALISE_FAILED:
            return "drop";
        default:
            return "fatal";
    }
}

API Reference

WS_BROKER_REDIS_CODES — frozen registry mapping name → WS_BROKER_REDIS.<NAME>.
WsBrokerRedisErrorCode — literal union over every registered code.
WsBrokerRedisError — SuaveplanError<WsBrokerRedisErrorCode> subclass with brokerCode field and a public 2/3-arg constructor.

Implementation Notes

WsBrokerRedisError declares its own public constructor (rather than relying on the base SuaveplanError's protected one) so new WsBrokerRedisError(...) compiles cleanly from outside the file. This is required by the repo's check-error-subclass-constructors lint — TypeScript's TS2674 ("Constructor of class is protected and only accessible within the class declaration") would otherwise reject every call site.

The brokerCode field is a deliberate alias for code. Calling code commonly branches on the narrower WsBrokerRedisErrorCode literal union to get exhaustiveness from the TypeScript compiler; reading the alias keeps that narrowing locally explicit even when the catch block widened the type.

3.3 KiB Raw Blame History

error-codes — WS_BROKER_REDIS_CODES