detection/from-magic-bytes

(no submodules)

- helpers — Low-level byte-inspection utilities used……

helpers — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
registry — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
helpers — Low-level byte-inspection utilities used……
helpers — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
registry — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
helpers — Low-level byte-inspection utilities used……
helpers — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
registry — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
helpers — Low-level byte-inspection utilities used…
helpers — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
registry — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…
helpers — Low-level byte-inspection utilities used by the magic-byte signature matchers. Provides helpers for common patterns: pr…
registry — The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-…

Purpose

Implements magic-byte (file signature) detection for MIME types. Maintains a registry of byte-pattern matchers sorted by priority, and provides functions to find the best match, all matches, or reset the registry. Magic-byte detection has the highest confidence (0.95) in the unified detect() function because byte signatures are objective evidence that cannot be spoofed by file naming or HTTP headers.

Features

detectFromMagicBytes(bytes) — returns the highest-priority matching MIME type
detectAllFromMagicBytes(bytes) — returns all matching MIME types sorted by priority
Registry sorted by descending priority for deterministic match order
Accepts any Uint8Array or ArrayBuffer-backed view
Returns undefined (not throws) when no signature matches
Supports minimum-bytes threshold per signature — skips signatures when the input is too short

Usage: Basic Example

import { detectFromMagicBytes } from "@suaveplan/mime/detection/from-magic-bytes/from-magic-bytes";

// PNG magic bytes: 89 50 4E 47 0D 0A 1A 0A
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

Usage: Advanced Example

import {
    detectFromMagicBytes,
    detectAllFromMagicBytes,
} from "@suaveplan/mime/detection/from-magic-bytes/from-magic-bytes";

// Detect all matching signatures (useful for ambiguous formats like MP4 variants)
const mp4Bytes = new Uint8Array([...]);
const allMatches = detectAllFromMagicBytes(mp4Bytes);
for (const match of allMatches) {
    console.log(match.mime, match.priority);
}

// Returns undefined for unrecognized byte sequences
const random = new Uint8Array([0x00, 0x01, 0x02, 0x03]);
console.log(detectFromMagicBytes(random)); // undefined

API Reference

`detectFromMagicBytes(bytes: Uint8Array): SignatureMatch | undefined`

Parameter	Type	Description
`bytes`	`Uint8Array`	Byte buffer to inspect (first N bytes of a file).

Returns: The highest-priority SignatureMatch (mime, priority), or undefined.

`detectAllFromMagicBytes(bytes: Uint8Array): SignatureMatch[]`

Returns all matching signatures sorted by descending priority.

Implementation Notes

The registry is sorted once whenever a new signature is registered, using a stable sort on priority (descending). Detection iterates the sorted array and returns the first match (for detectFromMagicBytes) or all matches (for detectAllFromMagicBytes). Signatures with a minBytes threshold are skipped when the input buffer is too short, enabling detection on partial reads without false negatives from truncated magic sequences.

4.6 KiB Raw Blame History