`error-codes.ts`

Purpose

Hosts the canonical HIBP_CODES registry — exactly seven error codes that classify every failure path inside @suaveplan/hibp. Lives at the package root (rather than in a nested errors/ directory) so the scripts/conformance.ts scanner can find it and verify every code is actually thrown by at least one production source file.

Features

Seven stable codes — RATE_LIMITED, UNAUTHORIZED, NOT_FOUND, MALFORMED_RESPONSE, NETWORK_ERROR, ABORTED, PAYLOAD_TOO_LARGE.
Each value is the namespaced HIBP.<KEY> form, suitable for stable string matching in logs and structured-error registries.
Registered through defineCodes from @suaveplan/error so the wider registry knows the namespace and can validate it at startup.

Usage: Basic Example

import { HIBP_CODES, type HibpErrorCode } from "@suaveplan/hibp";

function isFatal(code: HibpErrorCode): boolean {
    return code === HIBP_CODES.MALFORMED_RESPONSE;
}

Usage: Advanced Example

import { HibpError, HIBP_CODES } from "@suaveplan/hibp";

export function classifyHibpFailure(err: unknown): "retry" | "abort" | "report" {
    if (!(err instanceof HibpError)) return "report";
    switch (err.code) {
        case HIBP_CODES.RATE_LIMITED:
        case HIBP_CODES.NETWORK_ERROR:
            return "retry";
        case HIBP_CODES.ABORTED:
            return "abort";
        default:
            return "report";
    }
}

API Reference

HIBP_CODES — frozen record. Keys are bare names (RATE_LIMITED, …); values are namespaced strings ("HIBP.RATE_LIMITED", …).
HibpErrorCode — string-literal union of every registered value.

Implementation Notes

The seven codes were chosen so each one corresponds to a distinct caller remediation path: rate-limit backoff, credential rotation, resource absence, schema regression, transport failure, user-driven cancellation, and over-sized response. Adding a new code is a breaking change because downstream consumers fan out on code literally. Removing a code is likewise breaking and forbidden by the conformance gate, which verifies every registered code is thrown by at least one production path.

2.2 KiB Raw Blame History

error-codes.ts