# error-codes

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

```ts
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

```ts
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.