`error-codes`

(no submodules)

Purpose

Defines the stable REACT_MIDI.* error-code namespace published by @suaveplan/react-midi. Every code is generated via defineCodes from @suaveplan/error, paired with metadata (description, severity) in a frozen registry, and thrown via the ReactMidiError class which extends SuaveplanError. The metadata table is the single source of truth for downstream documentation generators, i18n resolvers, and the test suite that cross-checks code/metadata parity.

Features

Five stable codes: ACCESS_DENIED, UNSUPPORTED_PLATFORM, PORT_NOT_FOUND, SYSEX_NOT_PERMITTED, NO_PROVIDER.
ReactMidiError carries code, messageKey, optional context and cause, plus a severity-flavoured name for log filtering.
registerReactMidiErrorCodes() is an idempotent registration hook (no-op; metadata is module-static).

Usage: Basic

import { REACT_MIDI_CODES, ReactMidiError } from "@suaveplan/react-midi";

throw new ReactMidiError(
    REACT_MIDI_CODES.PORT_NOT_FOUND,
    "react-midi.port-not-found",
    { context: { portId: "midi-in-1" } }
);

Usage: Advanced

import {
    REACT_MIDI_CODES,
    REACT_MIDI_ERROR_METADATA,
    ReactMidiError,
} from "@suaveplan/react-midi";

function logIfWarning(err: unknown): void {
    if (err instanceof ReactMidiError) {
        const meta = REACT_MIDI_ERROR_METADATA[err.code];
        if (meta.severity === "warning") {
            console.warn(err.code, meta.description);
        } else {
            throw err;
        }
    }
}

API Reference

REACT_MIDI_CODES — frozen { readonly [Reason]: "REACT_MIDI.<Reason>" }.
REACT_MIDI_ERROR_METADATA — frozen { readonly [Code]: { description, severity } }.
class ReactMidiError extends SuaveplanError<ReactMidiErrorCode>.
function registerReactMidiErrorCodes(): void.

Implementation Notes

The five codes are deliberately small in number: every public hook surfaces at most one of them, and the four runtime codes (ACCESS_DENIED, UNSUPPORTED_PLATFORM, PORT_NOT_FOUND, SYSEX_NOT_PERMITTED) map one-to-one onto the four failure modes a Web MIDI consumer must handle. NO_PROVIDER is the structural error thrown by hooks invoked outside <MidiProvider>.

ReactMidiError extends SuaveplanError and therefore inherits the standard code, messageKey, context, and cause fields plus the package-wide category constant. The thrown name carries the severity in parentheses (e.g. ReactMidiError(error)) so log aggregators can filter on the rendered string when the consumer has not chained an i18n resolver. The metadata table is intentionally Object.freezed so consumers can rely on it as a stable read-only lookup across the process lifetime.

2.8 KiB Raw Blame History

error-codes