Initial Commit

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

@@ -0,0 +1,63 @@
+# error-codes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the stable numeric error-code registry for every error class in `@suaveplan/mime`. Each code is a non-overlapping integer in the `5000–5099` range, allocated via `defineCodes` from `@suaveplan/error`. Stable codes enable error identification across serialization, transport, and version upgrades without relying on class names or message strings.
+
+## Features
+
+- Five distinct error codes: `INVALID_CONTENT_TYPE`, `UNKNOWN_MIME_TYPE`, `INSUFFICIENT_BYTES`, `PARSE_ERROR`, `UNKNOWN_SIGNATURE`
+- Allocated via `@suaveplan/error`'s `defineCodes` for namespace isolation
+- Zero runtime overhead — values are plain numbers resolved at import time
+- Deterministic: the same integer is guaranteed across package versions
+
+## Usage: Basic Example
+
+```typescript
+import { MIME_ERROR_CODES } from "@suaveplan/mime/errors/codes";
+
+// Identify any MIME error by numeric code
+if (error.code === MIME_ERROR_CODES.INVALID_CONTENT_TYPE) {
+    console.error("Malformed Content-Type header");
+}
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { MIME_ERROR_CODES } from "@suaveplan/mime/errors/codes";
+import { InvalidContentTypeError } from "@suaveplan/mime/errors";
+
+// The code on each thrown error matches the registry
+try {
+    parseContentType("not-a-content-type");
+} catch (err) {
+    if (err instanceof InvalidContentTypeError) {
+        console.log(err.code === MIME_ERROR_CODES.INVALID_CONTENT_TYPE); // true
+    }
+}
+```
+
+## API Reference
+
+### `MIME_ERROR_CODES`
+
+| Name | Description |
+|------|-------------|
+| `INVALID_CONTENT_TYPE` | Malformed or unparseable Content-Type header |
+| `UNKNOWN_MIME_TYPE` | MIME type not found in the built-in database |
+| `INSUFFICIENT_BYTES` | Too few bytes provided for magic-byte detection |
+| `PARSE_ERROR` | General parse failure (XML/HTML charset sniffing) |
+| `UNKNOWN_SIGNATURE` | Byte signature pattern not recognized |
+
+## Implementation Notes
+
+The range `5000–5099` is reserved for `@suaveplan/mime`. Adjacent packages use non-overlapping ranges so that a project-wide error router can dispatch on code alone. The `defineCodes` call enforces uniqueness and throws at import time if a range collision is detected during development.
+
+### Registry Layout
+
+Every code lives under the `MIME` namespace and is produced by `defineCodes` from `@suaveplan/error`: `MIME.PARSE.INVALID`, `MIME.CONTENT_TYPE.INVALID`, `MIME.TYPE.UNKNOWN`, `MIME.SIGNATURE.UNKNOWN`, `MIME.BYTES.INSUFFICIENT`. The `MimeErrorCode` union is used by the `MimeError<TCode>` generic so subclasses advertise exactly which codes they can carry.