`error-codes`

(no submodules)

Purpose

Defines LIFECYCLE_CODES — the frozen, namespaced registry of the four error codes raised by the @suaveplan/api-lifecycle package — and LifecycleError, the typed SuaveplanError subclass that carries them. Every failure path in the lifecycle package (illegal transition, mutex contention, retry-budget exhaustion, manifest version downgrade) constructs a LifecycleError so callers can branch on either instanceof LifecycleError or the stable error.code string.

Features

Four-code registry built via @suaveplan/error's defineCodes helper, so the produced map is type-narrowed to { readonly K: "LIFECYCLE.K" }.
LifecycleError extends SuaveplanError<LifecycleCode> — instanceof works, and the name is set to "LifecycleError" for self-describing stack traces.
Frozen at module load (Object.freeze), so accidental mutation throws in strict mode rather than silently corrupting the registry.

Usage: Basic

import { LIFECYCLE_CODES, LifecycleError } from "@suaveplan/api-lifecycle/error-codes";

throw new LifecycleError(
    LIFECYCLE_CODES.ILLEGAL_TRANSITION,
    "Cannot transition from installed → stopped without going through stopping",
);

Usage: Advanced

Discriminating in a generic error handler:

import { LifecycleError, LIFECYCLE_CODES } from "@suaveplan/api-lifecycle/error-codes";

function handle(err: unknown): "retry" | "park" | "abort" {
    if (!(err instanceof LifecycleError)) return "abort";
    switch (err.code) {
        case LIFECYCLE_CODES.RETRY_BUDGET_EXHAUSTED:
            return "park";
        case LIFECYCLE_CODES.MUTEX_HELD:
            return "retry";
        default:
            return "abort";
    }
}

The code is a template-literal type so exhaustiveness checks in switch statements catch missing branches at compile time.

API Reference

LIFECYCLE_CODES — frozen record. Keys: ILLEGAL_TRANSITION, MUTEX_HELD, RETRY_BUDGET_EXHAUSTED, REINSTALL_REQUIRED_VERSION_DOWNGRADE.
type LifecycleCode — the union of every code's fully-qualified string.
class LifecycleError — constructor (code, message, options?) mirroring the SuaveplanError shape.

Implementation Notes

This file is the single source of truth for the namespace string LIFECYCLE. Adding a new code requires appending the bare reason to the tuple passed to defineCodes — the type is inferred from that tuple, so no other code change is needed. The error class itself is protected constructor upstream; this package narrows the namespace and adds name = "LifecycleError".

2.6 KiB Raw Blame History

error-codes