vault error codes

Purpose

codes.ts defines the stable error-code registry for @suaveplan/vault. Every failure raised by the orchestration layer — locked-state rejections, bad-credential unlocks, manifest tampering, item validation, attachment / share / sync failures, and opaque-handle violations — carries one of these literal codes. The codes are frozen at module-load via defineCodes("VAULT", [...]) so consumer code can assert on the exact strings without depending on JavaScript identifier ordering or import-time side effects.

The codes form the discriminated-union narrowing surface for VaultError. Together with the VaultError class they form the complete error contract: callers import { VAULT_CODES, VaultError, type VaultErrorCode } from "@suaveplan/vault/errors", branch on err.code, and let TypeScript exhaustively check the switch.

Features

Two-level namespacing — VAULT.LOCKED for top-level lifecycle errors, VAULT.ITEM.NOT_FOUND for module-scoped errors. The dot-separated form is searchable and groups related failures (ITEM.*, ATTACHMENT.*, SHARE.*, SYNC.*).
Every code is a literal string in the VaultErrorCode union — no enum cost, no value coupling.
Hard-frozen registry — defineCodes returns a frozen object so consumers cannot accidentally mutate or extend the registry at runtime.

Usage: Basic Example

import { VAULT_CODES, VaultError } from "@suaveplan/vault/errors";

throw new VaultError(VAULT_CODES.LOCKED, "error.vault.locked");

Usage: Advanced Example

import { VAULT_CODES, VaultError, type VaultErrorCode } from "@suaveplan/vault/errors";

function describe(err: VaultError): string {
    const code: VaultErrorCode = err.code;
    switch (code) {
        case VAULT_CODES.LOCKED:
            return "Vault is locked — call unlock() first.";
        case VAULT_CODES.INVALID_CREDENTIALS:
            return "Wrong password or secret key.";
        case VAULT_CODES["ITEM.NOT_FOUND"]:
            return "Item does not exist in this vault.";
        case VAULT_CODES["ITEM.VERSION_CONFLICT"]:
            return "Item was modified concurrently — refetch and retry.";
        // ... exhaustive
        default:
            return "Unknown vault error.";
    }
}

API Reference

VAULT_CODES — frozen Record<string, "VAULT.X.Y"> literal registry.
VaultErrorCode — union of every value in VAULT_CODES.

Implementation Notes

The registry is intentionally fixed in source — adding a code is a public-API change requiring an OpenSpec proposal and a coordinated release with consumers.
defineCodes("VAULT", [...]) automatically prefixes each entry with VAULT.; the source array contains the unqualified suffix so visual scanning stays compact.
Sub-namespaces (ITEM, ATTACHMENT, SHARE, SYNC) match the file layout under src/ so locating a code's emission site is mechanical.

2.9 KiB Raw Blame History