first commit

docs/foundation/data/mime/src/db/builtin-db.md

@@ -0,0 +1,56 @@
+# db/builtin-db
+
+## Purpose
+
+The built-in MIME type database for `@suaveplan/mime`. Contains over 150 `MimeEntry` records covering the most common web, media, document, archive, font, and application MIME types. This is a static data file — it contains no runtime logic, only the `BUILTIN_DB` constant array consumed by the registry.
+
+## Features
+
+- 150+ MIME type entries across all major categories
+- Each entry includes: `mime` (canonical type string), `extensions` (array of associated file extensions), and `encoding` (`"binary"`, `"text"`, or `"base64"`)
+- Comprehensive coverage: images, audio, video, documents, archives, fonts, executables, data formats
+- Extensions are lowercase and without leading dots
+- Canonical extension (for `Content-Disposition` filename guessing) is always the first element
+
+## Usage: Basic Example
+
+```typescript
+import { BUILTIN_DB } from "@suaveplan/mime/db/builtin-db";
+
+// Inspect all text-type entries
+const textTypes = BUILTIN_DB.filter(e => e.mime.startsWith("text/"));
+console.log(textTypes.map(e => e.mime));
+// ["text/plain", "text/html", "text/css", ...]
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { BUILTIN_DB } from "@suaveplan/mime/db/builtin-db";
+import { getEntryByMime } from "@suaveplan/mime/db/registry";
+
+// Combine built-in with runtime lookup
+const entry = getEntryByMime("application/pdf");
+console.log(entry?.extensions); // ["pdf"]
+console.log(entry?.encoding);   // "binary"
+
+// Find all binary MIME types
+const binaryTypes = BUILTIN_DB.filter(e => e.encoding === "binary");
+console.log(binaryTypes.length); // 100+
+```
+
+## API Reference
+
+### `BUILTIN_DB: readonly MimeEntry[]`
+
+A frozen array of `MimeEntry` objects. Each entry has:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mime` | `string` | Canonical MIME type string (e.g., `"image/png"`) |
+| `extensions` | `string[]` | Associated file extensions without dots (e.g., `["png"]`) |
+| `encoding` | `"binary" \| "text" \| "base64"` | Transfer encoding hint |
+
+## Implementation Notes
+
+The database is intentionally a plain array rather than a pre-built map so that the registry can apply its first-write-wins semantics during initialization. Keeping data and behavior separate also makes it straightforward to swap the database at build time (e.g., for a minimal embedded build that includes only a subset of MIME types). The entries are ordered roughly by frequency of use, which has no algorithmic impact but improves grep readability.