# QuantisationError

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

## Purpose

Structured error type for all `@suaveplan/image-quantisation` failures. Extends `SuaveplanError` so that callers receive stable codes, i18n-ready message keys, and optional cause chains. This unified error type eliminates the need for consumers to catch multiple different exception classes and enables programmatic branching on the `code` property.

## Features

- Stable `QUANTISATION.*` error codes via `defineCodes`
- Typed `code` property for programmatic discrimination
- i18n-ready message keys with no hard-coded user strings
- OTel span-event compatibility via `toSpanEvent`

## Usage: Basic Example

```ts
import {
    QuantisationError,
    QUANTISATION_CODES,
} from "@suaveplan/image-quantisation/errors";

throw new QuantisationError(
    QUANTISATION_CODES.INVALID_DIMENSIONS,
    "quantisation.invalid_dimensions"
);
```

## Usage: Advanced Example

```ts
import {
    QuantisationError,
    QUANTISATION_CODES,
} from "@suaveplan/image-quantisation/errors";

try {
    quantise(pixels, 0, 1);
} catch (err) {
    if (err instanceof QuantisationError) {
        console.log(err.code); // "QUANTISATION.INVALID_DIMENSIONS"
    }
}
```

## API Reference

### `QUANTISATION_CODES`

Constant object exported from `defineCodes("QUANTISATION", [...])`.

- `INVALID_PIXEL_BUFFER`
- `INVALID_COLOR_COUNT`
- `INVALID_DIMENSIONS`
- `PROCESSING_FAILED`

### `QuantisationError`

Constructor: `new QuantisationError(code, messageKey, options?)`

- `code` — one of the `QUANTISATION_CODES` values
- `messageKey` — i18n message resolver key
- `options?.cause` — optional underlying `Error`

## Implementation Notes

Error codes are registered at module load time. The `defineCodes` utility guarantees that every code string is prefixed with the namespace, so collisions across packages are impossible. The `INVALID_COLOR_COUNT` code is reserved for future use when palette-size validation is tightened. Consumers should always test against the exported `QUANTISATION_CODES` constant rather than hard-coding strings, because the exact prefix may change during major version bumps. The `QuantisationError` class is kept in its own feature module so that consumers who only need the error type can import it without pulling in the full quantisation logic.