Error code registry

Purpose

codes.ts defines the canonical, frozen registry of every fully-qualified error code emitted by @suaveplan/vault-sync. Codes are stable string literals consumers can switch on — they are part of the public API contract. The registry doubles as the source of truth for the VaultSyncCode type union, so adding a new code in a single place automatically widens the type and the spec-conformance.test.ts "every code is thrown" gate must observe the new value before the change can ship.

Features

Single source of truth for every VAULTSYNC.* code emitted from production
Frozen registry produced via defineCodes("VAULTSYNC", ...) from @suaveplan/error
Inferred literal-union type VaultSyncCode for exhaustive switch-narrowing
Import-time freezing — codes cannot be added or removed at runtime
Zero circular-dep risk: registry depends only on @suaveplan/error

Usage: Basic Example

import { VAULT_SYNC_CODES } from "@suaveplan/vault-sync/errors";

console.log(VAULT_SYNC_CODES["MERGE.STRATEGY_UNKNOWN"]);
// → "VAULTSYNC.MERGE.STRATEGY_UNKNOWN"

Usage: Advanced Example

import { VaultSyncError } from "@suaveplan/vault-sync";
import { VAULT_SYNC_CODES, type VaultSyncCode } from "@suaveplan/vault-sync/errors";

function describeFailure(err: unknown): string {
    if (!(err instanceof VaultSyncError)) return "non-vault-sync failure";
    const code: VaultSyncCode = err.code;
    switch (code) {
        case VAULT_SYNC_CODES["MERGE.STRATEGY_UNKNOWN"]:
            return "Unknown CRDT merge strategy";
        case VAULT_SYNC_CODES["SYNC.PAYLOAD_TAMPERED"]:
            return "Sync payload integrity check failed";
        case VAULT_SYNC_CODES["QUEUE.DEPTH_EXCEEDED"]:
            return "Offline queue at hard cap";
        default:
            // Exhaustive: TypeScript will fail if a new code is unhandled.
            return `unhandled vault-sync code: ${code as string}`;
    }
}

API Reference

VAULT_SYNC_CODES — Readonly<Record<reason, "VAULTSYNC.<REASON>">>. Frozen via Object.freeze. Iterating with Object.values(VAULT_SYNC_CODES) yields every code that may be emitted from production paths.
type VaultSyncCode — the literal union derived from typeof VAULT_SYNC_CODES[keyof typeof VAULT_SYNC_CODES]. Use as the TCode type parameter of SuaveplanError.

Implementation Notes

The registry is intentionally flat — there is no nested structure or runtime metadata. Metadata such as severity, retryability, and i18n message keys live where they are needed (the throwing call site, the i18n catalog, the OTel adapter), not on the code object itself.

Any new entry must be paired with:

A production path that throws the code under realistic conditions.
A new branch in spec-conformance.test.ts confirming the code is reachable.
An update to the codes table in the package README.md.

2.9 KiB Raw Blame History