first commit

docs/foundation/data/mime/src/detection/from-extension.md

@@ -0,0 +1,62 @@
+# detection/from-extension
+
+## Purpose
+
+Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lowercase, and looks up the result in the built-in MIME database. Returns a `DetectionResult` with `source: "extension"` and a confidence weight of 0.7 in the unified `detect()` function.
+
+## Features
+
+- Accepts both raw extensions (`.png`, `png`) and full filenames (`photo.jpeg`)
+- Strips directory path components automatically
+- Normalizes extensions to lowercase before lookup
+- Handles multiple dots in filenames correctly (uses the last extension)
+- Returns `undefined` for unknown extensions instead of throwing
+- Wraps the database entry in a `DetectionResult` envelope
+
+## Usage: Basic Example
+
+```typescript
+import { detectFromExtension } from "@suaveplan/mime/detection/from-extension";
+
+const result = detectFromExtension("photo.jpg");
+console.log(result?.mime);   // "image/jpeg"
+console.log(result?.source); // "extension"
+
+// Just an extension without filename
+const svg = detectFromExtension(".svg");
+console.log(svg?.mime); // "image/svg+xml"
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { detectFromExtension } from "@suaveplan/mime/detection/from-extension";
+
+function getMimeForUpload(filename: string): string {
+    const detected = detectFromExtension(filename);
+    // Fall back to binary stream for unknown extensions
+    return detected?.mime ?? "application/octet-stream";
+}
+
+// Handles paths with directories
+console.log(detectFromExtension("/uploads/2024/report.pdf")?.mime); // "application/pdf"
+
+// Unknown extension returns undefined
+console.log(detectFromExtension("file.xyz")); // undefined
+```
+
+## API Reference
+
+### `detectFromExtension(input: string): DetectionResult | undefined`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `input` | `string` | File extension (with or without dot) or full filename/path. |
+
+**Returns:** `DetectionResult` with `source: "extension"` and the matched `mime`, or `undefined` when the extension is not in the database.
+
+**Throws:** Never.
+
+## Implementation Notes
+
+The function extracts the extension by splitting on `.` and taking the last segment, then looking up `getEntryByExtension`. The split also handles filenames with no extension (returns `undefined`) and filenames starting with a dot (treated as hidden files with no extension, e.g. `.gitignore`). Path components are stripped by looking only at the basename portion after the last `/` or `\`. Lookup is O(1) via the registry's `Map<string, MimeEntry>` index.