first commit

docs/media/image/compress-image/src/errors/compress-image-error.md

@@ -0,0 +1,82 @@
+# compress-image-error
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Defines the structured error class and stable code registry for the `@suaveplan/compress-image` package. All compression failures are surfaced through `CompressImageError`, which extends the project-wide `SuaveplanError` base class to guarantee consistent wire format, cause-chain traversal, OTel span-event integration, and Zod-validated JSON/binary serialization.
+
+Centralising codes in `COMPRESS_IMAGE_CODES` (produced by `defineCodes`) ensures that every error string is unique within the project namespace and will not silently change across package updates.
+
+## Features
+
+- Stable `COMPRESS_IMAGE_CODES` registry with four codes covering all failure surfaces
+- `CompressImageError` class with typed `code` property for narrow `instanceof` discrimination
+- Full cause-chain forwarding via the `cause` option
+- Compatible with the `SuaveplanError` OTel adapter and redaction middleware
+- Zero external runtime dependencies beyond `@suaveplan/error`
+
+## Usage: Basic Example
+
+```ts
+import { CompressImageError, COMPRESS_IMAGE_CODES } from '@suaveplan/compress-image/errors';
+
+throw new CompressImageError(
+  'Unsupported input format: tiff',
+  COMPRESS_IMAGE_CODES.UNSUPPORTED_FORMAT,
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { CompressImageError, COMPRESS_IMAGE_CODES } from '@suaveplan/compress-image/errors';
+
+async function runCompress(input: Uint8Array) {
+  try {
+    await adapter.compress(input, { quality: 80 });
+  } catch (err) {
+    throw new CompressImageError(
+      'Compression pipeline failed',
+      COMPRESS_IMAGE_CODES.COMPRESS_FAILED,
+      { cause: err instanceof Error ? err : undefined },
+    );
+  }
+}
+```
+
+## API Reference
+
+### `COMPRESS_IMAGE_CODES`
+
+An object map produced by `defineCodes('COMPRESS_IMAGE', { ... })`. Each value is a stable string code of the form `COMPRESS_IMAGE.<KEY>`.
+
+| Key | Description |
+|---|---|
+| `UNSUPPORTED_FORMAT` | Input image format is not recognized or not supported by the adapter |
+| `COMPRESS_FAILED` | The compression operation itself threw an error |
+| `INVALID_OPTIONS` | Zod validation rejected the provided `CompressOptions` |
+| `ADAPTER_NOT_SET` | `compress` / `resize` / `getInfo` was called before an adapter was configured |
+
+### `CompressImageError`
+
+```ts
+class CompressImageError extends SuaveplanError {
+  constructor(message: string, code: string, options?: { cause?: Error }): void
+}
+```
+
+**Parameters**
+
+| Name | Type | Description |
+|---|---|---|
+| `message` | `string` | Human-readable description of the failure |
+| `code` | `string` | A value from `COMPRESS_IMAGE_CODES` |
+| `options.cause` | `Error \| undefined` | Originating error for cause-chain traversal |
+
+## Implementation Notes
+
+`SuaveplanError` stores `code` on its instance and enforces the Zod-validated wire format so errors survive cross-process transport. The `name = 'CompressImageError'` assignment enables `instanceof` checks even after deserialization with the error registry.
+
+The constructor signature deviates slightly from `DatetimeError` — it accepts a plain `string` message rather than a messageKey because image compression errors carry enough context inline and do not require i18n resolution.