Initial Commit

packages/foundation/data/mime/src/errors/mime-error.md

@@ -0,0 +1,59 @@
+# errors/mime-error
+
+## Purpose
+
+The base error class for all `@suaveplan/mime` errors. Extends `SuaveplanError` from `@suaveplan/error` with the `MIME_ERROR_CODES` namespace and provides a common ancestor for `instanceof` checks across all MIME-specific error types.
+
+## Features
+
+- Extends `SuaveplanError` for consistent error serialization and OTel integration
+- `code` field set to `MIME_ERROR_CODES.INVALID_CONTENT_TYPE` by default (overridden by subclasses)
+- `name` property set to `"MimeError"` for easy identification in logs
+- Compatible with `SuaveplanError`'s cause-chain traversal and redaction APIs
+- Used as the base for `instanceof MimeError` checks when callers don't need the specific subtype
+
+## Usage: Basic Example
+
+```typescript
+import { MimeError } from "@suaveplan/mime/errors";
+
+try {
+    // Any MIME operation
+} catch (err) {
+    if (err instanceof MimeError) {
+        console.error("MIME error:", err.message, "code:", err.code);
+    }
+}
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { MimeError } from "@suaveplan/mime/errors";
+import { InvalidContentTypeError, UnknownMimeTypeError } from "@suaveplan/mime/errors";
+
+// Route by specific subtype
+function handleMimeError(err: MimeError) {
+    if (err instanceof InvalidContentTypeError) {
+        return Response.json({ error: "bad_content_type" }, { status: 400 });
+    }
+    if (err instanceof UnknownMimeTypeError) {
+        return Response.json({ error: "unsupported_type" }, { status: 415 });
+    }
+    throw err; // Unexpected subtype — re-throw
+}
+```
+
+## API Reference
+
+### `class MimeError extends SuaveplanError`
+
+The base class. All `@suaveplan/mime` error classes extend this.
+
+## Implementation Notes
+
+`MimeError` exists primarily to provide a stable `instanceof` target for callers who want to catch any MIME-related error without caring about the specific subtype. All subclasses set their own `code` from `MIME_ERROR_CODES` and override `name` with their class name. The inheritance chain is: `SuaveplanError → MimeError → {subtype}`.
+
+### Subclass Index
+
+Direct subclasses are `InvalidContentTypeError`, `UnknownMimeTypeError`, `UnknownSignatureError`, `InsufficientBytesError`, and `ParseError`. Every subclass sets its own `code` from the stable `MIME_ERROR_CODES` registry, overrides `name`, and inherits the wire-serialisation, OTel span-event adapter, and i18n resolver behaviour from `SuaveplanError`. Tests typically assert `err instanceof MimeError` first for broad catches, then narrow with `instanceof` on the specific subclass.