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