db/registry

Purpose

The central in-memory MIME type database for @suaveplan/mime. Maintains two indexes over the built-in MimeEntry list: a type → extensions forward map and an extension → entry reverse map. Provides O(1) lookup in both directions and supports registering additional entries at runtime for extensibility.

Features

getEntryByMime(mime) — forward lookup: MIME type string → MimeEntry
getEntryByExtension(ext) — reverse lookup: file extension → MimeEntry
registerEntry(entry) — register a custom MIME type at runtime
First-write-wins semantics: built-in entries take precedence over later registrations for the same extension
Extension keys are normalized to lowercase with no leading dot
Both indexes are populated lazily on first access (module load)
_indexEntryForTesting — exported only for internal test instrumentation

Usage: Basic Example

import { getEntryByMime, getEntryByExtension } from "@suaveplan/mime/db/registry";

// Forward lookup
const pngEntry = getEntryByMime("image/png");
console.log(pngEntry?.extensions); // ["png"]

// Reverse lookup
const entry = getEntryByExtension("jpg");
console.log(entry?.mime); // "image/jpeg"

Usage: Advanced Example

import { getEntryByMime, registerEntry } from "@suaveplan/mime/db/registry";

// Register a custom MIME type
registerEntry({
    mime: "application/x-my-format",
    extensions: ["myf", "myfmt"],
    encoding: "binary",
});

// Immediately available via lookup
const custom = getEntryByMime("application/x-my-format");
console.log(custom?.extensions); // ["myf", "myfmt"]

// Built-in extensions are protected (first-write-wins)
// Registering a second entry for ".png" will not override image/png
registerEntry({ mime: "image/x-fake-png", extensions: ["png"] });
const png = getEntryByExtension("png");
console.log(png?.mime); // still "image/png"

API Reference

`getEntryByMime(mime: string): MimeEntry | undefined`

Looks up a MimeEntry by its MIME type string. Returns undefined if not found.

`getEntryByExtension(ext: string): MimeEntry | undefined`

Looks up a MimeEntry by file extension (with or without leading dot, case-insensitive). Returns undefined if not found.

`registerEntry(entry: MimeEntry): void`

Registers a new MIME type entry. First-write-wins for extensions: if an extension is already in the index, the new entry does not replace it.

Implementation Notes

The registry is initialized at module load by iterating BUILTIN_DB once and calling the private index() function for each entry. The index() function implements the first-write-wins extension guard: if (!byExtension.has(key)) byExtension.set(key, entry). This guard prevents downstream registerEntry calls from overriding the canonical extension-to-type mapping established by the built-in database, which is important for stable behavior across multiple registerEntry calls in plugin-style usage.

2.9 KiB Raw Blame History