first commit

docs/media/image/colours/src/error-codes/error-codes.md

@@ -0,0 +1,61 @@
+# 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.