`error-codes`

(no submodules)

Purpose

Stable error-code registry for @suaveplan/react-audio-player. Every error thrown by a public surface in this package carries a code from REACT_AUDIO_PLAYER_CODES, a messageKey for i18n resolution, and an optional context / cause chain. Codes are namespaced under the REACT_AUDIO_PLAYER. prefix so the wire format { code: "REACT_AUDIO_PLAYER.LRC_PARSE_FAILED" } is greppable and stable across versions.

The registry is the single source of truth for the package's error contract — the test suite walks REACT_AUDIO_PLAYER_ERROR_METADATA and confirms every code is reachable from a real call site, so a code that gets added without a thrower (or a thrower whose code gets removed) is a build break.

Features

Five public codes: NO_PROVIDER, PLAYLIST_EMPTY, PERSISTENCE_FAILED, LRC_PARSE_FAILED, INVALID_OPTIONS.
Frozen metadata map keyed by code; every entry has a description and severity ("error" | "warning").
ReactAudioPlayerError class extends SuaveplanError; carries a stable category = "react-audio-player" field.
Idempotent registerReactAudioPlayerErrorCodes() for parity with sibling audio packages.

Usage: Basic

import {
    REACT_AUDIO_PLAYER_CODES,
    ReactAudioPlayerError,
} from "@suaveplan/react-audio-player/error-codes";

if (!provider) {
    throw new ReactAudioPlayerError(
        REACT_AUDIO_PLAYER_CODES.NO_PROVIDER,
        "react-audio-player.no-provider"
    );
}

Usage: Advanced

import {
    REACT_AUDIO_PLAYER_CODES,
    REACT_AUDIO_PLAYER_ERROR_METADATA,
    ReactAudioPlayerError,
} from "@suaveplan/react-audio-player/error-codes";

try {
    parseLrc(input);
} catch (cause) {
    const code = REACT_AUDIO_PLAYER_CODES.LRC_PARSE_FAILED;
    const meta = REACT_AUDIO_PLAYER_ERROR_METADATA[code];
    throw new ReactAudioPlayerError(code, "lrc.parse.failed", {
        cause,
        context: { severity: meta.severity, bytes: input.length },
    });
}

API Reference

REACT_AUDIO_PLAYER_CODES — Readonly<Record<…, string>> of the five public codes (frozen).
ReactAudioPlayerErrorCode — union of the code string-literals.
REACT_AUDIO_PLAYER_ERROR_METADATA — frozen metadata map.
ReactAudioPlayerError extends SuaveplanError<ReactAudioPlayerErrorCode>.
registerReactAudioPlayerErrorCodes(): void — idempotent no-op.

Implementation Notes

defineCodes is the workspace's standard helper for producing namespaced code maps; it freezes the result and asserts that every key is a valid identifier at module load. Metadata is declared with Object.freeze so consumers (and the test suite) cannot mutate it at runtime.

SuaveplanError is the universal base error from @suaveplan/error; it carries code, messageKey, context, and cause plus a stable wire-format serialisation. The category = "react-audio-player" literal is the discriminator used by the cross-package error router when an error crosses a package boundary.

name is set to ReactAudioPlayerError(<severity>) so stack-trace output includes the severity at a glance. This is a string-only augmentation; it does not change the prototype chain so instanceof ReactAudioPlayerError still narrows correctly.

3.3 KiB Raw Blame History

error-codes