# @suaveplan/mime - Structured MIME-type detection, parsing, and registry: magic-byte sniffing, RFC 7231 Content-Type parsing, IANA-sourced type database.
## Summary
Structured MIME-type detection, parsing, and registry for the Suaveplan platform. Provides RFC 7231 Content-Type parsing, magic-byte file signature detection, charset sniffing, and a 150+ entry IANA-sourced type database — all in a zero-dependency, tree-shakeable package.
## Documentation tree
- [sniff-bom](./src/charset/sniff-bom.md) — Detects character encoding from a Byte Order Mark (BOM) at the start of a binary buffer. BOM detection is the highest-c…
- [sniff-html-meta](./src/charset/sniff-html-meta.md) — Extracts a declared character encoding from an HTML `` tag by scanning the first 1,024 characters of an HTML docu…
- [sniff-xml-decl](./src/charset/sniff-xml-decl.md) — Extracts the declared encoding from an XML or SVG document's processing instruction (` _(no submodules)_ - helpers — Low-level byte-inspection utilities used……
- [archives](./src/detection/from-magic-bytes/signatures/archives.md) — Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all…
- [audio](./src/detection/from-magic-bytes/signatures/audio.md) — Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container…
- [data](./src/detection/from-magic-bytes/signatures/data.md) — Registers magic-byte signatures for binary data and structured-data formats with the global signature registry. Covers…
- [documents](./src/detection/from-magic-bytes/signatures/documents.md) — Registers magic-byte signatures for document and data format files with the global signature registry. Covers office do…
- [executables](./src/detection/from-magic-bytes/signatures/executables.md) — Registers magic-byte signatures for executable binary formats with the global signature registry. Covers native executa…
- [fonts](./src/detection/from-magic-bytes/signatures/fonts.md) — Registers magic-byte signatures for font file formats with the global signature registry. Covers all major web font and…
- [images](./src/detection/from-magic-bytes/signatures/images.md) — Registers magic-byte signatures for image formats with the global signature registry. Covers all major raster and vecto…
- [model3d](./src/detection/from-magic-bytes/signatures/model3d.md) — Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CA…
- [video](./src/detection/from-magic-bytes/signatures/video.md) — Registers magic-byte signatures for video container formats with the global signature registry. Covers all major video…
- [from-magic-bytes](./src/detection/from-magic-bytes/from-magic-bytes.md) — _(no submodules)_ - helpers — Low-level byte-inspection utilities used……
- [helpers](./src/detection/from-magic-bytes/helpers.md) — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- [registry](./src/detection/from-magic-bytes/registry.md) — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
- [detect](./src/detection/detect.md) — The unified MIME detection entry point for `@suaveplan/mime`. Merges evidence from three independent sources — magic by…
- [from-content-type](./src/detection/from-content-type.md) — Detects the MIME type from a raw `Content-Type` header string. Parses the header using the full RFC 7231 parser and wra…
- [from-extension](./src/detection/from-extension.md) — Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lo…
- [from-stream-reader](./src/detection/from-stream-reader.md) — Internal module providing the `toAsyncIterable` helper and the `drainViaReader` legacy fallback for `ReadableStream` so…
- [from-stream](./src/detection/from-stream.md) — Provides `detectFromStream`, which reads the first N bytes from any async byte source (`ReadableStream` or…
- [error-codes](./src/error-codes/error-codes.md) — Defines the stable numeric error-code registry for every error class in `@suaveplan/mime`. Each code is a non-overlappi…
- [error-codes](./src/error-codes/error-codes.md) — Defines the stable numeric error-code registry for every error class in `@suaveplan/mime`. Each code is a non-overlappi…
- [insufficient-bytes-error](./src/errors/insufficient-bytes-error.md) — Thrown when a magic-byte detection operation receives fewer bytes than the minimum required by the signature. Carries b…
- [invalid-content-type-error](./src/errors/invalid-content-type-error.md) — Thrown when a `Content-Type` header or media type string fails RFC 7231 validation. Carries the raw input string and op…
- [mime-error](./src/errors/mime-error.md) — The base error class for all `@suaveplan/mime` errors. Extends `SuaveplanError` from `@suaveplan/error` with the `MIME_…
- [parse-error](./src/errors/parse-error.md) — Thrown when a general parsing operation fails — for example, XML declaration parsing or BOM detection failures. Unlike…
- [unknown-mime-type-error](./src/errors/unknown-mime-type-error.md) — Thrown when a MIME type string is not found in the built-in database and no fallback is available. Carries the unrecogn…
- [unknown-signature-error](./src/errors/unknown-signature-error.md) — Thrown when a byte signature identifier is referenced but is not present in the signature registry. Used as a sentinel…
- [legacy](./src/legacy/get-mime-type.md) — _(no submodules)_
- [get-mime-type](./src/legacy/get-mime-type.md) — _(no submodules)_
- [reverse](./src/reverse/reverse.md) — _(no submodules)_
- [reverse](./src/reverse/reverse.md) — _(no submodules)_
- [telemetry](./src/telemetry/meters.md) — _(no submodules)_
- [meters](./src/telemetry/meters.md) — _(no submodules)_
- helpers — Low-level byte-inspection utilities used……
- [archives](./src/detection/from-magic-bytes/signatures/archives.md) — Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all…
- [audio](./src/detection/from-magic-bytes/signatures/audio.md) — Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container…
- [data](./src/detection/from-magic-bytes/signatures/data.md) — Registers magic-byte signatures for binary data and structured-data formats with the global signature registry. Covers…
- [documents](./src/detection/from-magic-bytes/signatures/documents.md) — Registers magic-byte signatures for document and data format files with the global signature registry. Covers office do…
- [executables](./src/detection/from-magic-bytes/signatures/executables.md) — Registers magic-byte signatures for executable binary formats with the global signature registry. Covers native executa…
- [fonts](./src/detection/from-magic-bytes/signatures/fonts.md) — Registers magic-byte signatures for font file formats with the global signature registry. Covers all major web font and…
- [images](./src/detection/from-magic-bytes/signatures/images.md) — Registers magic-byte signatures for image formats with the global signature registry. Covers all major raster and vecto…
- [model3d](./src/detection/from-magic-bytes/signatures/model3d.md) — Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CA…
- [video](./src/detection/from-magic-bytes/signatures/video.md) — Registers magic-byte signatures for video container formats with the global signature registry. Covers all major video…
- [from-magic-bytes](./src/detection/from-magic-bytes/from-magic-bytes.md) — _(no submodules)_- helpers — Low-level byte-inspection utilities used……
- [helpers](./src/detection/from-magic-bytes/helpers.md) — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- [registry](./src/detection/from-magic-bytes/registry.md) — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
- [detect](./src/detection/detect.md) — The unified MIME detection entry point for `@suaveplan/mime`. Merges evidence from three independent sources — magic by…
- [from-content-type](./src/detection/from-content-type.md) — Detects the MIME type from a raw `Content-Type` header string. Parses the header using the full RFC 7231 parser and wra…
- [from-extension](./src/detection/from-extension.md) — Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lo…
- [from-stream-reader](./src/detection/from-stream-reader.md) — Internal module providing the `toAsyncIterable` helper and the `drainViaReader` legacy fallback for `ReadableStream` so…
- [from-stream](./src/detection/from-stream.md) — Provides `detectFromStream`, which reads the first N bytes from any async byte source (`ReadableStream` or…
- [insufficient-bytes-error](./src/errors/insufficient-bytes-error.md) — Thrown when a magic-byte detection operation receives fewer bytes than the minimum required by the signature. Carries b…
- [invalid-content-type-error](./src/errors/invalid-content-type-error.md) — Thrown when a `Content-Type` header or media type string fails RFC 7231 validation. Carries the raw input string and op…
- [mime-error](./src/errors/mime-error.md) — The base error class for all `@suaveplan/mime` errors. Extends `SuaveplanError` from `@suaveplan/error` with the `MIME_…
- [parse-error](./src/errors/parse-error.md) — Thrown when a general parsing operation fails — for example, XML declaration parsing or BOM detection failures. Unlike…
- [unknown-mime-type-error](./src/errors/unknown-mime-type-error.md) — Thrown when a MIME type string is not found in the built-in database and no fallback is available. Carries the unrecogn…
- [unknown-signature-error](./src/errors/unknown-signature-error.md) — Thrown when a byte signature identifier is referenced but is not present in the signature registry. Used as a sentinel…
- [legacy](./src/legacy/get-mime-type.md) — _(no submodules)_- [get-mime-type](./src/legacy/get-mime-type.md) — _(no submodules)_- [reverse](./src/reverse/reverse.md) — _(no submodules)_- [reverse](./src/reverse/reverse.md) — _(no submodules)_- [telemetry](./src/telemetry/meters.md) — _(no submodules)_- [meters](./src/telemetry/meters.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the stable numeric error-code registry for every error class in `@suaveplan/mime`. Each code is a non-overlappi…
- helpers — Low-level byte-inspection utilities used……
- [archives](./src/detection/from-magic-bytes/signatures/archives.md) — Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all…
- [audio](./src/detection/from-magic-bytes/signatures/audio.md) — Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container…
- [data](./src/detection/from-magic-bytes/signatures/data.md) — Registers magic-byte signatures for binary data and structured-data formats with the global signature registry. Covers…
- [documents](./src/detection/from-magic-bytes/signatures/documents.md) — Registers magic-byte signatures for document and data format files with the global signature registry. Covers office do…
- [executables](./src/detection/from-magic-bytes/signatures/executables.md) — Registers magic-byte signatures for executable binary formats with the global signature registry. Covers native executa…
- [fonts](./src/detection/from-magic-bytes/signatures/fonts.md) — Registers magic-byte signatures for font file formats with the global signature registry. Covers all major web font and…
- [images](./src/detection/from-magic-bytes/signatures/images.md) — Registers magic-byte signatures for image formats with the global signature registry. Covers all major raster and vecto…
- [model3d](./src/detection/from-magic-bytes/signatures/model3d.md) — Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CA…
- [video](./src/detection/from-magic-bytes/signatures/video.md) — Registers magic-byte signatures for video container formats with the global signature registry. Covers all major video…
- [from-magic-bytes](./src/detection/from-magic-bytes/from-magic-bytes.md) — _(no submodules)_- helpers — Low-level byte-inspection utilities used……
- [helpers](./src/detection/from-magic-bytes/helpers.md) — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- [registry](./src/detection/from-magic-bytes/registry.md) — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
- [detect](./src/detection/detect.md) — The unified MIME detection entry point for `@suaveplan/mime`. Merges evidence from three independent sources — magic by…
- [from-content-type](./src/detection/from-content-type.md) — Detects the MIME type from a raw `Content-Type` header string. Parses the header using the full RFC 7231 parser and wra…
- [from-extension](./src/detection/from-extension.md) — Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lo…
- [from-stream-reader](./src/detection/from-stream-reader.md) — Internal module providing the `toAsyncIterable` helper and the `drainViaReader` legacy fallback for `ReadableStream` so…
- [from-stream](./src/detection/from-stream.md) — Provides `detectFromStream`, which reads the first N bytes from any async byte source (`ReadableStream` or…
- [insufficient-bytes-error](./src/errors/insufficient-bytes-error.md) — Thrown when a magic-byte detection operation receives fewer bytes than the minimum required by the signature. Carries b…
- [invalid-content-type-error](./src/errors/invalid-content-type-error.md) — Thrown when a `Content-Type` header or media type string fails RFC 7231 validation. Carries the raw input string and op…
- [mime-error](./src/errors/mime-error.md) — The base error class for all `@suaveplan/mime` errors. Extends `SuaveplanError` from `@suaveplan/error` with the `MIME_…
- [parse-error](./src/errors/parse-error.md) — Thrown when a general parsing operation fails — for example, XML declaration parsing or BOM detection failures. Unlike…
- [unknown-mime-type-error](./src/errors/unknown-mime-type-error.md) — Thrown when a MIME type string is not found in the built-in database and no fallback is available. Carries the unrecogn…
- [unknown-signature-error](./src/errors/unknown-signature-error.md) — Thrown when a byte signature identifier is referenced but is not present in the signature registry. Used as a sentinel…
- [legacy](./src/legacy/get-mime-type.md) — _(no submodules)_- [get-mime-type](./src/legacy/get-mime-type.md) — _(no submodules)_- [reverse](./src/reverse/reverse.md) — _(no submodules)_- [reverse](./src/reverse/reverse.md) — _(no submodules)_- [telemetry](./src/telemetry/meters.md) — _(no submodules)_- [meters](./src/telemetry/meters.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the stable numeric error-code registry for every error class in `@suaveplan/mime`. Each code is a non-overlappi…
- helpers — Low-level byte-inspection utilities used…
- [archives](./src/detection/from-magic-bytes/signatures/archives.md) — Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all…
- [audio](./src/detection/from-magic-bytes/signatures/audio.md) — Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container…
- [data](./src/detection/from-magic-bytes/signatures/data.md) — Registers magic-byte signatures for binary data and structured-data formats with the global signature registry. Covers…
- [documents](./src/detection/from-magic-bytes/signatures/documents.md) — Registers magic-byte signatures for document and data format files with the global signature registry. Covers office do…
- [executables](./src/detection/from-magic-bytes/signatures/executables.md) — Registers magic-byte signatures for executable binary formats with the global signature registry. Covers native executa…
- [fonts](./src/detection/from-magic-bytes/signatures/fonts.md) — Registers magic-byte signatures for font file formats with the global signature registry. Covers all major web font and…
- [images](./src/detection/from-magic-bytes/signatures/images.md) — Registers magic-byte signatures for image formats with the global signature registry. Covers all major raster and vecto…
- [model3d](./src/detection/from-magic-bytes/signatures/model3d.md) — Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CA…
- [video](./src/detection/from-magic-bytes/signatures/video.md) — Registers magic-byte signatures for video container formats with the global signature registry. Covers all major video…
- [from-magic-bytes](./src/detection/from-magic-bytes/from-magic-bytes.md) — _(no submodules)_- helpers — Low-level byte-inspection utilities used…
- [helpers](./src/detection/from-magic-bytes/helpers.md) — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- [registry](./src/detection/from-magic-bytes/registry.md) — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
- [detect](./src/detection/detect.md) — The unified MIME detection entry point for `@suaveplan/mime`. Merges evidence from three independent sources — magic by…
- [from-content-type](./src/detection/from-content-type.md) — Detects the MIME type from a raw `Content-Type` header string. Parses the header using the full RFC 7231 parser and wra…
- [from-extension](./src/detection/from-extension.md) — Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lo…
- [from-stream-reader](./src/detection/from-stream-reader.md) — Internal module providing the `toAsyncIterable` helper and the `drainViaReader` legacy fallback for `ReadableStream` so…
- [from-stream](./src/detection/from-stream.md) — Provides `detectFromStream`, which reads the first N bytes from any async byte source (`ReadableStream` or…
- [insufficient-bytes-error](./src/errors/insufficient-bytes-error.md) — Thrown when a magic-byte detection operation receives fewer bytes than the minimum required by the signature. Carries b…
- [invalid-content-type-error](./src/errors/invalid-content-type-error.md) — Thrown when a `Content-Type` header or media type string fails RFC 7231 validation. Carries the raw input string and op…
- [mime-error](./src/errors/mime-error.md) — The base error class for all `@suaveplan/mime` errors. Extends `SuaveplanError` from `@suaveplan/error` with the `MIME_…
- [parse-error](./src/errors/parse-error.md) — Thrown when a general parsing operation fails — for example, XML declaration parsing or BOM detection failures. Unlike…
- [unknown-mime-type-error](./src/errors/unknown-mime-type-error.md) — Thrown when a MIME type string is not found in the built-in database and no fallback is available. Carries the unrecogn…
- [unknown-signature-error](./src/errors/unknown-signature-error.md) — Thrown when a byte signature identifier is referenced but is not present in the signature registry. Used as a sentinel…
- [legacy](./src/legacy/get-mime-type.md) — _(no submodules)_- [get-mime-type](./src/legacy/get-mime-type.md) — _(no submodules)_- [reverse](./src/reverse/reverse.md) — _(no submodules)_- [reverse](./src/reverse/reverse.md) — _(no submodules)_- [telemetry](./src/telemetry/meters.md) — _(no submodules)_- [meters](./src/telemetry/meters.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the stable numeric error-code registry for every error class in `@suaveplan/mime`. Each code is a non-overlappi…
- [archives](./src/detection/from-magic-bytes/signatures/archives.md) — Registers magic-byte signatures for archive and compressed file formats with the global signature registry. Covers all…
- [audio](./src/detection/from-magic-bytes/signatures/audio.md) — Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container…
- [data](./src/detection/from-magic-bytes/signatures/data.md) — Registers magic-byte signatures for binary data and structured-data formats with the global signature registry. Covers…
- [documents](./src/detection/from-magic-bytes/signatures/documents.md) — Registers magic-byte signatures for document and data format files with the global signature registry. Covers office do…
- [executables](./src/detection/from-magic-bytes/signatures/executables.md) — Registers magic-byte signatures for executable binary formats with the global signature registry. Covers native executa…
- [fonts](./src/detection/from-magic-bytes/signatures/fonts.md) — Registers magic-byte signatures for font file formats with the global signature registry. Covers all major web font and…
- [images](./src/detection/from-magic-bytes/signatures/images.md) — Registers magic-byte signatures for image formats with the global signature registry. Covers all major raster and vecto…
- [model3d](./src/detection/from-magic-bytes/signatures/model3d.md) — Registers magic-byte signatures for 3D model file formats with the global signature registry. Covers formats used in CA…
- [video](./src/detection/from-magic-bytes/signatures/video.md) — Registers magic-byte signatures for video container formats with the global signature registry. Covers all major video…
- [from-magic-bytes](./src/detection/from-magic-bytes/from-magic-bytes.md) — _(no submodules)_- [helpers](./src/detection/from-magic-bytes/helpers.md) — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
- [registry](./src/detection/from-magic-bytes/registry.md) — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
- [detect](./src/detection/detect.md) — The unified MIME detection entry point for `@suaveplan/mime`. Merges evidence from three independent sources — magic by…
- [from-content-type](./src/detection/from-content-type.md) — Detects the MIME type from a raw `Content-Type` header string. Parses the header using the full RFC 7231 parser and wra…
- [from-extension](./src/detection/from-extension.md) — Detects the MIME type from a file extension or full filename. Strips path components and leading dots, normalizes to lo…
- [from-stream-reader](./src/detection/from-stream-reader.md) — Internal module providing the `toAsyncIterable` helper and the `drainViaReader` legacy fallback for `ReadableStream` so…
- [from-stream](./src/detection/from-stream.md) — Provides `detectFromStream`, which reads the first N bytes from any async byte source (`ReadableStream` or…
- [insufficient-bytes-error](./src/errors/insufficient-bytes-error.md) — Thrown when a magic-byte detection operation receives fewer bytes than the minimum required by the signature. Carries b…
- [invalid-content-type-error](./src/errors/invalid-content-type-error.md) — Thrown when a `Content-Type` header or media type string fails RFC 7231 validation. Carries the raw input string and op…
- [mime-error](./src/errors/mime-error.md) — The base error class for all `@suaveplan/mime` errors. Extends `SuaveplanError` from `@suaveplan/error` with the `MIME_…
- [parse-error](./src/errors/parse-error.md) — Thrown when a general parsing operation fails — for example, XML declaration parsing or BOM detection failures. Unlike…
- [unknown-mime-type-error](./src/errors/unknown-mime-type-error.md) — Thrown when a MIME type string is not found in the built-in database and no fallback is available. Carries the unrecogn…
- [unknown-signature-error](./src/errors/unknown-signature-error.md) — Thrown when a byte signature identifier is referenced but is not present in the signature registry. Used as a sentinel…
- [legacy](./src/legacy/get-mime-type.md) — _(no submodules)_ - [get-mime-type](./src/legacy/get-mime-type.md) — _(no submodules)_- [reverse](./src/reverse/reverse.md) — _(no submodules)_ - [reverse](./src/reverse/reverse.md) — _(no submodules)_- [telemetry](./src/telemetry/meters.md) — _(no submodules)_ - [meters](./src/telemetry/meters.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — Defines the stable numeric error-code registry for every error class in `@suaveplan/mime`. Each code is a non-overlappi…
## Features
- **RFC 7231 Content-Type parsing** — full quoted-string and OWS support
- **Magic-byte detection** — 150+ signatures across images, audio, video, archives, documents, executables, and fonts
- **Stream detection** — peek bytes from a `ReadableStream` or `AsyncIterable` without losing the original stream
- **Charset sniffing** — BOM, HTML `` tag, and XML declaration detection
- **Multi-source confidence scoring** — merge bytes + extension + Content-Type with agreement boost
- **Reverse lookup** — MIME type → canonical file extension
- **OpenTelemetry metrics** — optional OTel instrumentation
- **100% test coverage** — every branch and statement verified
## Installation
```bash
bun add @suaveplan/mime
```
## Quick Start
```typescript
import { detect } from "@suaveplan/mime";
// Multi-source detection with confidence scoring
const result = detect({
bytes: fileBuffer,
filename: "photo.jpg",
contentType: "image/jpeg",
});
console.log(result.mime); // "image/jpeg"
console.log(result.confidence); // 1.0 (all three sources agree)
```
## Module Reference
| Module | Description | Docs |
|--------|-------------|------|
| `@suaveplan/mime` | Main entry: `detect()`, `parseContentType()`, `formatContentType()` | [src/index.ts](src/index.ts) |
| `@suaveplan/mime/content-type` | RFC 7231 parser, formatter, equality/match utilities | [parse-content-type.md](src/content-type/parse-content-type.md) |
| `@suaveplan/mime/detection/detect` | Unified multi-source detector | [detect.md](src/detection/detect.md) |
| `@suaveplan/mime/detection/from-stream` | Stream-based detection with head/tail replay | [from-stream.md](src/detection/from-stream.md) |
| `@suaveplan/mime/detection/from-magic-bytes` | Raw magic-byte detection API | [from-magic-bytes.md](src/detection/from-magic-bytes/from-magic-bytes.md) |
| `@suaveplan/mime/charset/sniff-bom` | BOM detection from byte buffers | [sniff-bom.md](src/charset/sniff-bom.md) |
| `@suaveplan/mime/charset/sniff-html-meta` | HTML `` detection | [sniff-html-meta.md](src/charset/sniff-html-meta.md) |
| `@suaveplan/mime/charset/sniff-xml-decl` | XML encoding declaration detection | [sniff-xml-decl.md](src/charset/sniff-xml-decl.md) |
| `@suaveplan/mime/db/registry` | MIME database: forward and reverse lookup | [registry.md](src/db/registry.md) |
| `@suaveplan/mime/reverse` | MIME type → file extension reverse lookup | [reverse.md](src/reverse/reverse.md) |
| `@suaveplan/mime/errors` | Typed error classes | [mime-error.md](src/errors/mime-error.md) |
| `@suaveplan/mime/telemetry/meters` | Optional OTel metrics instrumentation | [meters.md](src/telemetry/meters.md) |
| `@suaveplan/mime/legacy` | `getMimeType()` compat shim | [get-mime-type.md](src/legacy/get-mime-type.md) |
## API Examples
### Content-Type Parsing
```typescript
import { parseContentType, formatContentType } from "@suaveplan/mime/content-type";
const ct = parseContentType("text/html; charset=UTF-8; format=flowed");
console.log(ct.type); // "text"
console.log(ct.subtype); // "html"
console.log(ct.essence); // "text/html"
console.log(ct.parameters.charset); // "utf-8" (lowercased)
console.log(formatContentType(ct)); // "text/html; charset=utf-8; format=flowed"
```
### Magic-Byte Detection
```typescript
import { detectFromMagicBytes } from "@suaveplan/mime/detection/from-magic-bytes/from-magic-bytes";
const pngBytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
const result = detectFromMagicBytes(pngBytes);
console.log(result?.mime); // "image/png"
console.log(result?.priority); // 100
```
### Stream Detection
```typescript
import { detectFromStream } from "@suaveplan/mime/detection/from-stream";
const { mime, head, tail } = await detectFromStream(uploadStream);
console.log(mime); // e.g. "video/mp4"
// Replay the full stream (head + tail)
const chunks: Uint8Array[] = [head];
for await (const chunk of tail) chunks.push(chunk);
```
### Charset Sniffing
```typescript
import { sniffBom } from "@suaveplan/mime/charset/sniff-bom";
import { sniffHtmlMeta } from "@suaveplan/mime/charset/sniff-html-meta";
const bom = sniffBom(fileBytes); // "utf-8" | "utf-16le" | null
const meta = sniffHtmlMeta(htmlText); // "iso-8859-1" | null
```
### Error Handling
```typescript
import { InvalidContentTypeError, UnknownMimeTypeError } from "@suaveplan/mime/errors";
import { parseContentType } from "@suaveplan/mime/content-type";
try {
parseContentType("not valid");
} catch (err) {
if (err instanceof InvalidContentTypeError) {
console.error("Bad header:", err.context?.raw);
}
}
```
## Registering Custom Signatures
```typescript
import { registerSignature } from "@suaveplan/mime/detection/from-magic-bytes/registry";
registerSignature({
mime: "application/x-my-format",
priority: 75,
minBytes: 4,
match: (bytes) =>
bytes[0] === 0x4d && bytes[1] === 0x59 &&
bytes[2] === 0x46 && bytes[3] === 0x4d,
});
```
## Coverage
This package maintains **100% statement, branch, function, and line coverage** — a requirement for Layer 0/1 foundation packages in Suaveplan.
## License
MIT