`error-codes`

(no submodules)

Purpose

Frozen registry of SECRETS_VAULT.* error codes thrown by the vault-backed SecretsLike adapter and its watcher / allow-list helpers. Kept distinct from upstream SECRETS.* (owned by @suaveplan/api-secrets) and SECRETS_ENV.* (the env adapter) so a single log line is enough for operators to identify whether the failure originated in vault-locked state, allow-list rejection, backend I/O failure, or write-path mutation. Built on defineCodes + SuaveplanError so the throwable carries the canonical code field and structured-logger name attribute.

Features

SECRETS_VAULT_CODES — frozen object literal with six entries: NOT_FOUND, NOT_ALLOWED, VAULT_LOCKED, VAULT_UNAVAILABLE, WRITE_FAILED, INVALID_OPTIONS.
SecretsVaultCode — string-literal union of the six codes.
SecretsVaultError — SuaveplanError<SecretsVaultCode> subclass with error.name === "SecretsVaultError".
SECRETS_VAULT_ERROR_NAME — exported constant for cross-package name-equality checks.

Usage: Basic

import {
    SECRETS_VAULT_CODES,
    SecretsVaultError,
} from "@suaveplan/api-secrets-vault/error-codes";

throw new SecretsVaultError(
    SECRETS_VAULT_CODES.NOT_ALLOWED,
    "error.secrets_vault.not_allowed",
    { context: { name: "AWS" } }
);

Usage: Advanced

Cause-chained surfacing from a backend I/O failure:

import {
    SECRETS_VAULT_CODES,
    SecretsVaultError,
} from "@suaveplan/api-secrets-vault/error-codes";

try {
    await backend.get("STRIPE");
} catch (cause) {
    throw new SecretsVaultError(
        SECRETS_VAULT_CODES.VAULT_UNAVAILABLE,
        "error.secrets_vault.vault_unavailable",
        { cause, context: { name: "STRIPE" } }
    );
}

API Reference

SECRETS_VAULT_CODES: Readonly<{ NOT_FOUND, NOT_ALLOWED, VAULT_LOCKED, VAULT_UNAVAILABLE, WRITE_FAILED, INVALID_OPTIONS }>
type SecretsVaultCode = (typeof SECRETS_VAULT_CODES)[…]
const SECRETS_VAULT_ERROR_NAME = "SecretsVaultError"
class SecretsVaultError extends SuaveplanError<SecretsVaultCode>
- constructor(code, messageKey, options?: SuaveplanErrorOptions)

Implementation Notes

The codes register at module load via the package's root barrel side-effect-importing this file. That guarantees subpath consumers who import @suaveplan/api-secrets-vault/adapter directly still get the registry populated for cross-package code lookups. The throwable attaches the original error on cause per WHATWG semantics, which the error.cause-chain redactor in @suaveplan/error walks during log emission.

VAULT_LOCKED is intentionally raised eagerly rather than letting the backend's own locked-state error bubble up — this preserves the package's strict-mode invariant (no plaintext fallback on a locked vault) and lets the adapter throw a consistent code regardless of which @suaveplan/vault version is in scope.

2.9 KiB Raw Blame History

error-codes