`error-codes`

(no submodules)

Purpose

The error-codes module is the canonical source of truth for every failure mode published by @suaveplan/react-audio-stream. It declares the seven dotted codes under the REACT_AUDIO_STREAM. namespace via defineCodes, the frozen metadata table, and the ReactAudioStreamError class — every error thrown by the package extends this class and carries one of these codes. Consumers discriminate failures with instanceof ReactAudioStreamError or by matching on the stable error.code string without needing to know which sub-feature originated the throw.

The codes line up one-to-one with the Requirement 9 surface of the parent OpenSpec change so the human-authored spec can be cross-checked against runtime reality: a test asserts every entry in REACT_AUDIO_STREAM_ERROR_METADATA is reachable from at least one production call site.

Features

Seven stable, lexically sorted codes: NO_PROVIDER, INVALID_STATE, SIGNALLING_FAILED, PEER_NOT_FOUND, MEDIA_PERMISSION_DENIED, RECONNECT_EXHAUSTED, INVALID_OPTIONS.
ReactAudioStreamError extends SuaveplanError — inherits structured context, cause-chain support, and serialization to the shared wire format.
Idempotent registerReactAudioStreamErrorCodes() registration hook for symmetry with sibling Suaveplan packages.
Object.freeze-d metadata table — mutation attempts throw in strict mode and a test guards the invariant.

Usage: Basic

import {
  REACT_AUDIO_STREAM_CODES,
  ReactAudioStreamError,
} from "@suaveplan/react-audio-stream/error-codes";

throw new ReactAudioStreamError(
  REACT_AUDIO_STREAM_CODES.NO_PROVIDER,
  "react-audio-stream.no-provider",
);

Usage: Advanced

import {
  REACT_AUDIO_STREAM_CODES,
  REACT_AUDIO_STREAM_ERROR_METADATA,
  ReactAudioStreamError,
} from "@suaveplan/react-audio-stream/error-codes";

try {
  await session.join();
} catch (err) {
  if (err instanceof ReactAudioStreamError) {
    const meta = REACT_AUDIO_STREAM_ERROR_METADATA[err.code];
    logger.warn({
      code: err.code,
      severity: meta.severity,
      description: meta.description,
      context: err.context,
    }, "stream session failure");
  }
  throw err;
}

API Reference

REACT_AUDIO_STREAM_CODES — frozen object literal keyed by short code, value is the dotted string ("REACT_AUDIO_STREAM.NO_PROVIDER").
ReactAudioStreamErrorCode — derived union of every value in the code registry.
ReactAudioStreamErrorMetadata — { description, severity } pair per code.
REACT_AUDIO_STREAM_ERROR_METADATA — Record<ReactAudioStreamErrorCode, ReactAudioStreamErrorMetadata>, Object.freeze-d at module load.
ReactAudioStreamError — SuaveplanError<ReactAudioStreamErrorCode> subclass; category is the literal "react-audio-stream".
registerReactAudioStreamErrorCodes(): void — idempotent no-op retained for parity with sibling registries.

Implementation Notes

defineCodes literally typesetting the runtime values means the ReactAudioStreamErrorCode union is derived without a second hand-maintained declaration. Adding a code requires only an entry in both REACT_AUDIO_STREAM_CODES and REACT_AUDIO_STREAM_ERROR_METADATA — the metadata test fails otherwise. Severity is currently error on every entry; the field exists so future warning-class diagnostics (deprecated transport probes, lossy fallbacks) slot in without a schema change. The class extends the foundation SuaveplanError directly — the parent OpenSpec change references an AudioError from @suaveplan/audio-core but the chunk-A dep allowlist excludes that package, so we follow the same pattern as sibling @suaveplan/react-audio which also extends the foundation base.

3.8 KiB Raw Blame History

error-codes