crypto-vault — Error code registry

Purpose

codes.ts is the canonical, frozen registry of every error code emitted by @suaveplan/crypto-vault. The registry exists so that consumers — vault orchestrators, sync layers, telemetry pipelines, audit log post-processors — can assert against a stable set of strings rather than parsing free-form messages. The registry is built with defineCodes from @suaveplan/error, which freezes the resulting record at module load and infers each code's literal type so instanceof CryptoVaultError can narrow code to the union.

Features

Frozen CRYPTO_VAULT_CODES record with CRYPTOVAULT.<MODULE>.<REASON> namespacing.
CryptoVaultCode type union for exhaustive switch discrimination.
One canonical home for every failure mode the package can produce. Adding a new code requires touching this file plus the production path that throws.

Usage: Basic Example

import {
    CRYPTO_VAULT_CODES,
    CryptoVaultError,
} from "@suaveplan/crypto-vault/errors";

throw new CryptoVaultError(
    CRYPTO_VAULT_CODES["BIP39.INVALID_ENTROPY_LENGTH"],
    "error.crypto-vault.bip39.invalid-entropy-length",
    { context: { length: 7 } }
);

Usage: Advanced Example

import { CryptoVaultError } from "@suaveplan/crypto-vault/errors";
import type { CryptoVaultCode } from "@suaveplan/crypto-vault/errors";

function describe(err: unknown): string {
    if (!(err instanceof CryptoVaultError)) return "unknown error";
    const code: CryptoVaultCode = err.code;
    switch (code) {
        case "CRYPTOVAULT.BIP39.INVALID_MNEMONIC":
            return "Invalid recovery phrase";
        case "CRYPTOVAULT.SRP.AUTHENTICATION_FAILED":
            return "Wrong password — try again";
        default:
            return `Unhandled crypto-vault code: ${code}`;
    }
}

API Reference

`CRYPTO_VAULT_CODES`

A frozen Record<string, string> mapping each reason key (e.g. BIP39.INVALID_ENTROPY_LENGTH) to its fully-qualified code (e.g. CRYPTOVAULT.BIP39.INVALID_ENTROPY_LENGTH).

`CryptoVaultCode`

Union of every string literal value held by CRYPTO_VAULT_CODES. Use as the generic parameter of CryptoVaultError.

Implementation Notes

The registry is intentionally append-only. Removing a code is a breaking change for any consumer that asserts on it.
Codes are checked at runtime via the defineCodes factory — any duplicate reason in the array would surface as the same key collapsing in the output record.
Every code listed here must be thrown by at least one production path. The spec-conformance test enumerates the registry and verifies the production surface throws each code at least once.

2.7 KiB Raw Blame History