`errors/errors.ts`

(no submodules)

Purpose

Defines the stable error-code registry and the concrete OverviewError subclass of SuaveplanError. Every public entry point in @suaveplan/overview that throws does so through this class, so callers can rely on a single instanceof OverviewError check and a literal-typed code field for discrimination.

The registry has six entries — one per failure mode that the package can detect — and the §2c "never delete spec elements to satisfy a gate" rule means each entry is exercised by a real call site somewhere in src/, asserted by the static test every code has a real call site in src/.

Features

Six stable codes registered through defineCodes("OVERVIEW", [...])
Frozen, fully-inferred code record — OVERVIEW_CODES.PARSE_FAILED is the literal "OVERVIEW.PARSE_FAILED"
OverviewCode closed union for exhaustive switch statements
OverviewError extends SuaveplanError<OverviewCode> so instanceof narrows error.code
Preserves cause chain, context, and trace-id propagation via SuaveplanErrorOptions

Usage: Basic

import { OverviewError, OVERVIEW_CODES } from "@suaveplan/overview";

throw new OverviewError(
  OVERVIEW_CODES.UNKNOWN_PACKAGE,
  "overview.unknown_package",
  { context: { pkg: "@suaveplan/missing" } },
);

Usage: Advanced

import { OverviewError } from "@suaveplan/overview";

try {
  // ...
} catch (err) {
  if (err instanceof OverviewError) {
    switch (err.code) {
      case "OVERVIEW.CYCLE_DETECTED":
        // type-narrowed; safe to read err.context?.cycle
        break;
      case "OVERVIEW.PARSE_FAILED":
        break;
      default:
        break;
    }
  }
  throw err;
}

The exhaustive switch benefits from OverviewCode being a closed union — adding a new code without handling it in a downstream switch is a TypeScript error.

API Reference

OVERVIEW_CODES — Readonly<{PARSE_FAILED, INVALID_RECORD, CYCLE_DETECTED, UNKNOWN_PACKAGE, DISCOVERY_ABORTED, INVALID_TIER}> with literal OVERVIEW.<X> values
type OverviewCode — closed union of every value in OVERVIEW_CODES
class OverviewError extends SuaveplanError<OverviewCode> — constructor (code, messageKey, options?)

Implementation Notes

The defineCodes helper from @suaveplan/error freezes its return value so the registry cannot be mutated at runtime. OverviewError deliberately re-exposes the protected constructor of SuaveplanError as public (the language requires each subclass to do this explicitly) so callers can new an instance directly without a factory. The class is final by convention — sub-classing it would dilute instanceof narrowing.

2.7 KiB Raw Blame History

errors/errors.ts