error-codes

(no submodules)

Purpose

error-codes.ts declares the canonical error-code registry for @suaveplan/colours. Every failure mode that the colour package can surface — from invalid hex strings to unsupported CSS colour formats — is assigned a stable, namespaced string via defineCodes from @suaveplan/error. This gives downstream log analysers, retry policies, and problem+json renderers a deterministic contract they can match against without parsing human-readable messages.

Features

Three stable codes under the COLOUR.* namespace
Type-safe ColourCode union derived from the registry object
Zero runtime side effects — the registry is a plain constant

Usage: Basic Example

import { COLOUR_CODES } from "@suaveplan/colours/error-codes";

function handleColourError(err: { code: string }) {
    if (err.code === COLOUR_CODES.INVALID_INPUT) {
        return { status: 400, message: "Invalid colour" };
    }
}

Usage: Advanced Example

import { COLOUR_CODES, type ColourCode } from "@suaveplan/colours/error-codes";

const retryableCodes: ColourCode[] = [
    COLOUR_CODES.CONVERSION_FAILED,
];

function shouldRetry(code: ColourCode): boolean {
    return retryableCodes.includes(code);
}

API Reference

`COLOUR_CODES`

A frozen object mapping human-readable keys to namespaced string values:

INVALID_INPUT → "COLOUR.INVALID_INPUT"
UNSUPPORTED_FORMAT → "COLOUR.UNSUPPORTED_FORMAT"
CONVERSION_FAILED → "COLOUR.CONVERSION_FAILED"

`ColourCode`

A TypeScript union of all three code string literals. Useful for function parameters and discriminated unions.

Implementation Notes

The registry is produced by defineCodes("COLOUR", [...]). If the namespace or code list ever changes, every test that asserts against COLOUR_CODES.* will fail, which is the desired behaviour — it prevents silent drift in the error contract.

Error codes are intentionally coarse-grained. They group related failure modes under a single code so that retry policies and alerting rules do not need to track an ever-expanding list of micro-codes. When more detail is required, the factory functions attach a context object with the raw input or format string.

2.2 KiB Raw Blame History