`error-codes` — stable error registry for `@suaveplan/react-packer`

(no submodules)

Purpose

Defines the canonical error-code registry and concrete error class for the React-tier packer companion. Every failure mode surfaced through usePackedResource and its variants funnels through ReactPackerError, which extends @suaveplan/error's SuaveplanError so consumers get cause-chain traversal, OTel span-event tagging, and i18n message resolution for free.

This module is the single source of truth for REACT_PACKER_* codes — no other file may invent new ones. Hooks and the provider import the exported constants and class to raise typed errors; tests assert on the code constants rather than string-comparing message keys.

Features

REACT_PACKER_CODES — frozen registry of three codes: LOAD_FAILED, FONT_LOAD_FAILED, ABORTED.
ReactPackerError — SuaveplanError subclass with a unique brand Symbol so cross-realm instanceof failures still permit safe discrimination via ReactPackerError.is(value).
cause preservation — when a hook wraps a PackerBrowserError or a DOMException from document.fonts.load, the original error rides on .cause for downstream debugging and OTel attribute capture.
Stable shape — adding new codes requires a new OpenSpec change so the public registry never drifts mid-version.

Usage: Basic

import { REACT_PACKER_CODES, ReactPackerError } from "@suaveplan/react-packer";

try {
    await loadSomething();
} catch (cause) {
    throw new ReactPackerError(
        REACT_PACKER_CODES.LOAD_FAILED,
        "react-packer.load-failed",
        { cause }
    );
}

Usage: Advanced

import { REACT_PACKER_CODES, ReactPackerError } from "@suaveplan/react-packer";

function onError(value: unknown): string {
    if (ReactPackerError.is(value)) {
        switch (value.code) {
            case REACT_PACKER_CODES.LOAD_FAILED:
                return "Could not unpack the resource.";
            case REACT_PACKER_CODES.FONT_LOAD_FAILED:
                return "Font failed to load; falling back to system font.";
            case REACT_PACKER_CODES.ABORTED:
                return "Cancelled.";
            default:
                return "Unexpected error.";
        }
    }
    return "Unknown error.";
}

API Reference

REACT_PACKER_CODES — Readonly<{ LOAD_FAILED, FONT_LOAD_FAILED, ABORTED }> registered via @suaveplan/error's defineCodes("REACT_PACKER", ...).
ReactPackerErrorCode — union of the values of REACT_PACKER_CODES.
ReactPackerError(code, messageKey, options?) — constructor accepts the registered code, an i18n message key, and the standard SuaveplanErrorOptions (including cause and params).
ReactPackerError.is(value: unknown): value is ReactPackerError — returns true only when value is a real ReactPackerError carrying the brand symbol.

Implementation Notes

The brand Symbol is module-local, so passing a forged object with the same shape will not satisfy is(...). This is intentional — duck-typed substitutes break OTel reporting and cause chains.
SuaveplanError already pins .code and .message (resolved from the messageKey) as read-only fields; subclasses do not need to redeclare them.
The brand assignment in the constructor is what makes super(code, ...) safe — TypeScript's definite-assignment analysis is satisfied by the public readonly [BRAND]: true field plus the constructor write.

3.5 KiB Raw Blame History

error-codes — stable error registry for @suaveplan/react-packer