Initial Commit

packages/foundation/data/mime/src/reverse/reverse.md

@@ -0,0 +1,70 @@
+# reverse/reverse
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides `getMimeExtension` for reverse lookup: given a MIME type string, returns the canonical file extension associated with that type. This is the inverse of extension-based detection — useful for generating filenames, setting `Content-Disposition` headers, and file download naming.
+
+## Features
+
+- Returns the canonical (first) extension for any registered MIME type
+- Returns `undefined` for unknown MIME types (no throws)
+- Case-insensitive MIME type matching (delegates to registry)
+- Returns extensions without a leading dot
+- O(1) lookup via the registry's forward map
+
+## Usage: Basic Example
+
+```typescript
+import { getMimeExtension } from "@suaveplan/mime/reverse/reverse";
+
+console.log(getMimeExtension("image/png"));         // "png"
+console.log(getMimeExtension("application/pdf"));   // "pdf"
+console.log(getMimeExtension("text/javascript"));   // "js"
+console.log(getMimeExtension("unknown/type"));      // undefined
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { getMimeExtension } from "@suaveplan/mime/reverse/reverse";
+
+function buildFilename(baseName: string, mimeType: string): string {
+    const ext = getMimeExtension(mimeType);
+    if (!ext) return baseName; // Unknown type — keep original name
+    // Avoid double extension
+    return baseName.endsWith(`.${ext}`) ? baseName : `${baseName}.${ext}`;
+}
+
+// Content-Disposition header generation
+function contentDisposition(mimeType: string, name: string): string {
+    const ext = getMimeExtension(mimeType);
+    const filename = ext ? `${name}.${ext}` : name;
+    return `attachment; filename="${filename}"`;
+}
+
+console.log(contentDisposition("application/pdf", "report"));
+// 'attachment; filename="report.pdf"'
+```
+
+## API Reference
+
+### `getMimeExtension(mime: string): string | undefined`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `mime` | `string` | MIME type string (e.g., `"image/png"`). |
+
+**Returns:** The canonical file extension string without a leading dot, or `undefined` if the MIME type is not in the database.
+
+**Throws:** Never.
+
+## Implementation Notes
+
+The "canonical" extension is the first element of the `extensions` array in the `MimeEntry`. The built-in database places the most common extension first by convention (e.g., `"jpeg"` before `"jpg"` for `image/jpeg`). Callers that need all extensions for a type should use `getEntryByMime` directly from `@suaveplan/mime/db/registry` and access `entry.extensions`.
+
+### Lookup Tables
+
+The reverse index maps MIME string → preferred extension, MIME string → alias list, and alias → canonical MIME. Tables are precomputed at module load from the same curated IANA database the forward lookup uses, so the two directions can never drift. Lookups are O(1) against frozen `Map` instances with zero runtime cost after first import.