suaveplan/packages/media/image/exif/src/errors/exif-error.md

ExifError

(no submodules)

Purpose

Provides the stable error code registry and base error class for the @suaveplan/exif package. Every error thrown by the package uses ExifError with a code from EXIF_CODES, enabling programmatic error handling without string matching on error messages.

The design mirrors the @suaveplan/error pattern but keeps the package dependency-free: no runtime @suaveplan/* imports are needed.

Features

• Stable code registry via EXIF_CODES constant object
• ExifError class with code and optional cause chaining
• TypeScript ExifErrorCode union type for exhaustive switch statements
• Four distinct codes covering all error surfaces: format detection, parsing, writing, and data validation

Usage: Basic Example

import { ExifError, EXIF_CODES } from "@suaveplan/exif/errors";

throw new ExifError("Buffer is not a JPEG or PNG image", EXIF_CODES.UNSUPPORTED_FORMAT);

Usage: Advanced Example

import { ExifError, EXIF_CODES, type ExifErrorCode } from "@suaveplan/exif/errors";

function handleExifError(err: ExifError): void {
  switch (err.code as ExifErrorCode) {
    case "EXIF.UNSUPPORTED_FORMAT":
      console.warn("Unsupported image format:", err.message);
      break;
    case "EXIF.PARSE_ERROR":
      console.error("Parsing failed:", err.message, err.cause);
      break;
    case "EXIF.WRITE_ERROR":
      console.error("Write failed:", err.message);
      break;
    case "EXIF.INVALID_DATA":
      console.error("Invalid metadata:", err.message);
      break;
  }
}

// With cause chaining
try {
  const data = parseIfd(reader, 0);
} catch (cause) {
  throw new ExifError("IFD parse failed at offset 0", EXIF_CODES.PARSE_ERROR, { cause });
}

API Reference

EXIF_CODES

const EXIF_CODES: {
  UNSUPPORTED_FORMAT: "EXIF.UNSUPPORTED_FORMAT";
  PARSE_ERROR: "EXIF.PARSE_ERROR";
  WRITE_ERROR: "EXIF.WRITE_ERROR";
  INVALID_DATA: "EXIF.INVALID_DATA";
}

Stable string code registry. Use these constants rather than literal strings to guard against typos.

ExifErrorCode

type ExifErrorCode = "EXIF.UNSUPPORTED_FORMAT" | "EXIF.PARSE_ERROR" | "EXIF.WRITE_ERROR" | "EXIF.INVALID_DATA";

Union type of all valid codes, suitable for exhaustive switches.

ExifError

class ExifError extends Error {
  readonly code: ExifErrorCode;
  constructor(message: string, code: ExifErrorCode, options?: { cause?: unknown }): ExifError;
}

• message — human-readable description of the error
• code — one of the EXIF_CODES values for programmatic handling
• options.cause — upstream error to chain (accessible via err.cause)

The name property is always "ExifError" for instanceof-free type narrowing via err.name.

Implementation Notes

This module is intentionally minimal. It carries no runtime dependencies and exports only what is needed for error handling across the package. The EXIF_CODES object is declared as const so TypeScript narrows each property to its literal type, enabling the ExifErrorCode union to be derived without duplication.

ExifError extends Error directly rather than @suaveplan/error's base class to keep the package fully dependency-free. This is a deliberate trade-off: the package is a leaf node in the dependency graph and should impose zero peer requirements on consumers.