`errors/errors.ts` — typed error hierarchy

(no submodules)

Purpose

This module exposes the typed error surface for @suaveplan/emblem-solver. It defines the stable, namespaced code registry EMBLEM_SOLVER_CODES and the EmblemSolverError class that extends SuaveplanError. Every failure path inside the package — schema validation, grid validation, IO checks — funnels through this hierarchy so callers can pattern-match on error.code to distinguish user input mistakes from defensive guards.

Features

Codes are produced by defineCodes("EMBLEM_SOLVER", [...] as const), yielding the namespaced strings EMBLEM_SOLVER.INVALID_GRID, EMBLEM_SOLVER.INVALID_OPTIONS, and EMBLEM_SOLVER.INVALID_PIXEL.
The registry is frozen — consumers can rely on identity equality across the module.
EmblemSolverError extends SuaveplanError<EmblemSolverCode>, so error.code narrows the union and instanceof EmblemSolverError discriminates the throw site.
Supports the full SuaveplanErrorOptions bag: cause, context, traceId, and clock for testing.

Usage: Basic

import {
    EMBLEM_SOLVER_CODES,
    EmblemSolverError,
} from "@suaveplan/emblem-solver/errors";

if (badInput) {
    throw new EmblemSolverError(
        EMBLEM_SOLVER_CODES.INVALID_GRID,
        "emblem-solver.invalid_grid"
    );
}

Usage: Advanced

try {
    convert(pixels, w, h, options);
} catch (err) {
    if (err instanceof EmblemSolverError) {
        switch (err.code) {
            case EMBLEM_SOLVER_CODES.INVALID_OPTIONS:
                return reportInputProblem(err);
            case EMBLEM_SOLVER_CODES.INVALID_GRID:
                return reportShapeProblem(err);
            case EMBLEM_SOLVER_CODES.INVALID_PIXEL:
                return reportPixelProblem(err);
        }
    }
    throw err;
}

API Reference

Symbol	Kind	Description
`EMBLEM_SOLVER_CODES`	const	Frozen `{ INVALID_GRID, INVALID_OPTIONS, INVALID_PIXEL }` map
`EmblemSolverCode`	type	Union of the namespaced strings
`EmblemSolverError`	class	`extends SuaveplanError<EmblemSolverCode>`

Implementation Notes

defineCodes runs at module load and Object.freezes the registry, guaranteeing identity stability — consumers that import via the root barrel or the ./errors subpath see the same object. The class constructor is deliberately thin: it forwards to SuaveplanError's protected constructor and sets name = "EmblemSolverError" so stack frames disambiguate. The INVALID_PIXEL code is reserved for future use (it appears in the code registry so consumers can switch on it ahead of any algorithmic change that introduces an unrepresentable RGBA value); the test suite exercises it via the round-trip code coverage check.

2.8 KiB Raw Blame History

errors/errors.ts — typed error hierarchy