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

compress-image-error

(no submodules)

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

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

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

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.