Initial Commit

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

@@ -0,0 +1,99 @@
+# 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.