`error-codes`

(no submodules)

Purpose

This module owns the stable SECRETS_BUN.* code registry and the SecretsBunError subclass thrown by every failure path inside the Bun.secrets-backed adapter. Splitting these codes from the upstream SECRETS.* namespace gives operators a one-glance distinction between the abstract secrets contract (@suaveplan/api-secrets), the environment-variable adapter (SECRETS_ENV.*), and the OS-keystore adapter (SECRETS_BUN.*).

The registry is frozen at module-load time so no consumer can mutate the codes that downstream telemetry already aggregates on. SecretsBunError pins error.name to a single canonical string so structured loggers can group rolled-up failure rates across every concrete code.

Features

Six codes — NOT_FOUND, NOT_ALLOWED, KEYSTORE_UNAVAILABLE, KEYSTORE_LOCKED, WRITE_FAILED, INVALID_OPTIONS.
Frozen registry via defineCodes so the surface cannot drift between runs in the same process.
Single SecretsBunError subclass for every throwable.
Carries cause chains so the underlying Bun.secrets error survives the wrap.

Usage: Basic

import {
    SECRETS_BUN_CODES,
    SecretsBunError,
} from "@suaveplan/api-secrets-bun/error-codes";

throw new SecretsBunError(
    SECRETS_BUN_CODES.NOT_ALLOWED,
    "error.secrets_bun.not_allowed",
    { context: { name: "AWS_SECRET_KEY" } }
);

Usage: Advanced

Catch and route on code:

import {
    SECRETS_BUN_CODES,
    SecretsBunError,
} from "@suaveplan/api-secrets-bun/error-codes";

try {
    await secrets.require("STRIPE");
} catch (err) {
    if (err instanceof SecretsBunError) {
        if (err.code === SECRETS_BUN_CODES.KEYSTORE_LOCKED) {
            // Prompt the operator to unlock the OS keystore.
        } else if (err.code === SECRETS_BUN_CODES.NOT_FOUND) {
            // Surface a manifest-mismatch installer hint.
        }
    }
    throw err;
}

API Reference

SECRETS_BUN_CODES — frozen { [name]: "SECRETS_BUN.<name>" }.
SecretsBunCode — TypeScript union of every fully-qualified code.
SECRETS_BUN_ERROR_NAME — "SecretsBunError".
SecretsBunError extends SuaveplanError<SecretsBunCode> — concrete subclass with code typed to SecretsBunCode.

Implementation Notes

Codes follow the project convention <NAMESPACE>.<CASE> so the dotted prefix is a stable telemetry key for grouping at the metric backend. The SecretsBunError constructor sets this.name AFTER super because SuaveplanError's base assigns its own default name; overriding it unconditionally is the only way to guarantee the canonical name survives inheritance.

2.7 KiB Raw Blame History

error-codes