skills/docs/media/image/image-quantisation/src/errors/image-quantisation-error.md

QuantisationError

(no submodules)

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

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

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

Usage: Advanced Example

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.