# ExifError

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

```ts
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

```ts
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`

```ts
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`

```ts
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`

```ts
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.