detection/from-magic-bytes/registry

Purpose

The mutable signature registry for magic-byte detection. Stores all registered byte-pattern matchers and provides CRUD-like access: registerSignature to add a matcher, getSignatures to read the sorted list, and resetSignatures to clear all entries (used in tests). This module is the single source of truth for the ordered list of matchers consumed by detectFromMagicBytes.

Features

registerSignature(sig) — add a new signature matcher; re-sorts registry by priority
getSignatures() — returns the full registry array sorted by descending priority
resetSignatures() — clears all registered signatures (test isolation only)
Priority-ordered registry: higher priority signatures are checked first
Thread-safe within a single JavaScript execution context (no async race conditions)

Usage: Basic Example

import {
    registerSignature,
    getSignatures,
} from "@suaveplan/mime/detection/from-magic-bytes/registry";

registerSignature({
    mime: "application/x-my-format",
    priority: 50,
    minBytes: 4,
    match: (bytes) => bytes[0] === 0x4d && bytes[1] === 0x59,
});

console.log(getSignatures().find(s => s.mime === "application/x-my-format"));

Usage: Advanced Example

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

// Custom signature for a proprietary binary format
registerSignature({
    mime: "application/x-leveldb",
    priority: 75,
    minBytes: 8,
    match: (bytes) =>
        bytes[0] === 0xff &&
        bytes[1] === 0x06 &&
        bytes[2] === 0x00 &&
        bytes[3] === 0x00,
});

// Signature with a scan offset
registerSignature({
    mime: "image/x-xcf",
    priority: 80,
    minBytes: 9,
    match: (bytes) => {
        // "gimp xcf " at offset 0
        const magic = [0x67, 0x69, 0x6d, 0x70, 0x20, 0x78, 0x63, 0x66, 0x20];
        return magic.every((b, i) => bytes[i] === b);
    },
});

API Reference

`registerSignature(sig: Signature): void`

Parameter	Type	Description
`sig.mime`	`string`	MIME type this signature identifies
`sig.priority`	`number`	Higher values are checked first (0–100 typical range)
`sig.minBytes`	`number`	Minimum bytes required to run the matcher
`sig.match`	`(bytes: Uint8Array) => boolean`	Byte-pattern predicate

`getSignatures(): Signature[]`

Returns the full sorted registry array. Do not mutate the returned array directly.

`resetSignatures(): void`

Clears all signatures. Intended for test isolation only — not safe for production use.

Implementation Notes

The registry maintains a sorted array rather than a priority queue for simplicity. registerSignature performs an in-place sort after insertion, which is O(n log n) but acceptable given that signatures are registered at module load time (once per process) and detection reads are O(n) anyway. The sort is stable in modern JavaScript engines, so signatures with equal priority retain their insertion order.

3.0 KiB Raw Blame History Unescape Escape