# `error-codes` — `WS_BROKER_REDIS_CODES`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

```ts
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

```ts
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.