`error-codes`

(no submodules)

Purpose

error-codes.ts is the single source of truth for every error class and stable code emitted by @suaveplan/packer-browser. It registers the PACKER_BROWSER_CODES constant via defineCodes from @suaveplan/error so the wire-serialiser, OTel adapter, and i18n resolver in the broader error stack pick up the codes automatically. Every production path that throws routes through PackerBrowserError so consumers can classify failures without string-matching message text.

Features

Six stable codes covering the Cluster A failure surface: RESOURCE_NOT_FOUND, SW_REGISTRATION_FAILED, ARCHIVE_SIGNATURE_INVALID, UNSUPPORTED_RESOURCE_TYPE, ABORTED, LOAD_FAILED.
PackerBrowserError extends SuaveplanError<TCode> with .name branded "PackerBrowserError" so logger sinks render structured output.
PACKER_BROWSER_ERROR_METADATA table mapping every code to { httpStatus, severity, retryable, description } — consumed by HTTP boundary middleware and retry policies.

Usage: Basic

import {
    PACKER_BROWSER_CODES,
    PackerBrowserError,
} from "@suaveplan/packer-browser";

throw new PackerBrowserError(
    PACKER_BROWSER_CODES.RESOURCE_NOT_FOUND,
    "Packed resource fetch returned HTTP 404."
);

Usage: Advanced

import {
    PACKER_BROWSER_CODES,
    PACKER_BROWSER_ERROR_METADATA,
    PackerBrowserError,
} from "@suaveplan/packer-browser";

try {
    await manager.load("/missing.packed");
} catch (err) {
    if (err instanceof PackerBrowserError) {
        const meta =
            PACKER_BROWSER_ERROR_METADATA[
                err.code as keyof typeof PACKER_BROWSER_ERROR_METADATA
            ];
        if (meta.retryable) {
            // schedule a retry
        }
    }
}

API Reference

PACKER_BROWSER_CODES — frozen record mapping bare code names (e.g. RESOURCE_NOT_FOUND) to their fully-qualified form ("PACKER_BROWSER.RESOURCE_NOT_FOUND").
PackerBrowserErrorCode — union of every value in PACKER_BROWSER_CODES.
PACKER_BROWSER_ERROR_METADATA[code] — { httpStatus: number; severity: "info" | "warning" | "error"; retryable: boolean; description: string }.
class PackerBrowserError<TCode> extends SuaveplanError<TCode> — constructor (code, message, options?).

Implementation Notes

The registry is intentionally exhaustive of the Cluster A surface, not of the eventual public contract — Cluster B (encrypted-archive keyring) and Cluster C (BackgroundFetch / range / multi-origin) will extend the list. Every existing code is reachable from a production call site; unused entries are banned by CLAUDE.md §2c and would fail the conformance gate. The metadata httpStatus field is the value to surface from any HTTP-boundary translator (e.g. a Hono middleware) that re-renders a PackerBrowserError as an outbound response.

2.9 KiB Raw Permalink Blame History

error-codes