mime-bytes 0.0.2

package/esm/index.js

@@ -0,0 +1,11 @@
+// Main export file for mime-bytes package
+// Export the main detector class and convenience functions
+export { FileTypeDetector, defaultDetector, detectFromStream, detectFromBuffer, detectFromExtension } from './file-type-detector';
+// Export registry types and functions
+export { FILE_TYPES, CONTENT_TYPE_MAPPINGS, getFileTypeByMagicBytes, getFileTypeByExtension, getFileTypesByCategory, getContentTypeByExtension, detectCharset } from './file-types-registry';
+// Export peek stream functionality
+export { peek, BufferPeekStream } from './peak';
+// Export utility functions
+export * from './utils/magic-bytes';
+export * from './utils/mime-types';
+export * from './utils/extensions';

package/esm/peak.js

@@ -0,0 +1,90 @@
+// TypeScript implementation of peek stream for efficient file type detection
+// Based on reference-packages/buffer-peak/peak.js
+import { Transform } from 'stream';
+export class BufferPeekStream extends Transform {
+    peekBytes;
+    buffer;
+    bufferLength;
+    peeked;
+    constructor(options) {
+        super(options);
+        this.peekBytes = options.peekBytes || 16;
+        this.buffer = Buffer.alloc(0);
+        this.bufferLength = 0;
+        this.peeked = false;
+    }
+    _transform(chunk, encoding, callback) {
+        if (this.peeked) {
+            // After peeking, just pass through
+            this.push(chunk);
+            callback();
+            return;
+        }
+        // Accumulate data until we have enough to peek
+        const chunkBuffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding);
+        this.buffer = Buffer.concat([this.buffer, chunkBuffer]);
+        this.bufferLength += chunkBuffer.length;
+        if (this.bufferLength >= this.peekBytes) {
+            // We have enough data to peek
+            this.peeked = true;
+            // Emit the peek event with the requested bytes
+            const peekBuffer = this.buffer.slice(0, this.peekBytes);
+            this.emit('peek', peekBuffer);
+            // Push all accumulated data
+            this.push(this.buffer);
+            this.buffer = Buffer.alloc(0);
+            this.bufferLength = 0;
+            callback();
+        }
+        else {
+            // Need more data
+            callback();
+        }
+    }
+    _flush(callback) {
+        if (!this.peeked && this.bufferLength > 0) {
+            // Not enough data was received, emit what we have
+            this.peeked = true;
+            this.emit('peek', this.buffer);
+            this.push(this.buffer);
+        }
+        callback();
+    }
+}
+export function peek(source, bytesOrCallback, callback) {
+    let bytes;
+    let cb;
+    if (typeof bytesOrCallback === 'function') {
+        bytes = 16; // Default peek bytes
+        cb = bytesOrCallback;
+    }
+    else {
+        bytes = bytesOrCallback;
+        cb = callback;
+    }
+    const dest = new BufferPeekStream({ peekBytes: bytes });
+    if (cb) {
+        dest.once('peek', (buffer) => {
+            cb(null, buffer, dest);
+        });
+        dest.once('error', (err) => {
+            cb(err, Buffer.alloc(0), dest);
+        });
+    }
+    return source.pipe(dest);
+}
+// Promise-based version
+peek.promise = function (source, bytes = 16) {
+    return new Promise((resolve, reject) => {
+        const dest = peek(source, bytes, (err, buffer, stream) => {
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve([buffer, stream]);
+            }
+        });
+        // Handle source errors
+        source.once('error', reject);
+    });
+};

package/esm/utils/extensions.js

@@ -0,0 +1,114 @@
+// Extension utility functions
+// Normalize file extension
+export function normalizeExtension(extension) {
+    return extension.toLowerCase().replace(/^\./, '');
+}
+// Extract extension from filename
+export function getExtension(filename) {
+    const lastDot = filename.lastIndexOf('.');
+    if (lastDot === -1 || lastDot === filename.length - 1) {
+        return '';
+    }
+    return normalizeExtension(filename.substring(lastDot + 1));
+}
+// Check if extension is commonly associated with compressed files
+export function isCompressedExtension(extension) {
+    const compressed = [
+        'zip', 'rar', '7z', 'tar', 'gz', 'bz2', 'xz', 'lz', 'lzma', 'z',
+        'tgz', 'tbz', 'tbz2', 'txz', 'tlz', 'arc', 'arj', 'cab', 'dmg',
+        'iso', 'lha', 'lzh', 'pkg', 'deb', 'rpm', 'msi', 'jar', 'war',
+        'ear', 'sar', 'aar', 'apk', 'ipa', 'xpi', 'egg', 'whl', 'gem'
+    ];
+    return compressed.includes(normalizeExtension(extension));
+}
+// Check if extension is commonly associated with document files
+export function isDocumentExtension(extension) {
+    const documents = [
+        'pdf', 'doc', 'docx', 'odt', 'rtf', 'tex', 'wpd', 'txt', 'md',
+        'xls', 'xlsx', 'ods', 'csv', 'ppt', 'pptx', 'odp', 'epub', 'mobi',
+        'azw', 'azw3', 'fb2', 'lit', 'pdb', 'ps', 'eps', 'indd', 'xps'
+    ];
+    return documents.includes(normalizeExtension(extension));
+}
+// Check if extension is commonly associated with media files
+export function isMediaExtension(extension) {
+    const media = [
+        // Video
+        'mp4', 'avi', 'mkv', 'mov', 'wmv', 'flv', 'webm', 'vob', 'ogv',
+        'ogg', 'm4v', '3gp', '3g2', 'mpg', 'mpeg', 'mp2', 'mpe', 'mpv',
+        'm2v', 'svi', 'mxf', 'roq', 'nsv', 'f4v', 'f4p', 'f4a', 'f4b',
+        // Audio
+        'mp3', 'wav', 'flac', 'aac', 'ogg', 'oga', 'wma', 'm4a', 'opus',
+        'ape', 'wv', 'amr', 'ac3', 'dts', 'spx', 'mid', 'midi', 'kar',
+        'aiff', 'aif', 'aifc', 'au', 'snd', 'voc', 'ra', 'rm', 'ram'
+    ];
+    return media.includes(normalizeExtension(extension));
+}
+// Check if extension is commonly associated with image files
+export function isImageExtension(extension) {
+    const images = [
+        'jpg', 'jpeg', 'png', 'gif', 'bmp', 'svg', 'webp', 'ico', 'tif',
+        'tiff', 'psd', 'raw', 'heif', 'heic', 'indd', 'ai', 'eps', 'ps',
+        'xcf', 'cdr', 'cmx', 'dib', 'jxr', 'hdp', 'wdp', 'cur', 'icns',
+        'pbm', 'pgm', 'ppm', 'pnm', 'pcx', 'dcx', 'dds', 'dng', 'cr2',
+        'cr3', 'crw', 'nef', 'nrw', 'orf', 'raf', 'rw2', 'rwl', 'srw',
+        'arw', 'srf', 'sr2', 'bay', 'cap', 'iiq', 'eip', 'dcs', 'dcr',
+        'drf', 'k25', 'kdc', 'mdc', 'mef', 'mos', 'mrw', 'pef', 'ptx',
+        'pxn', 'r3d', 'x3f', 'qoi'
+    ];
+    return images.includes(normalizeExtension(extension));
+}
+// Check if extension is commonly associated with executable files
+export function isExecutableExtension(extension) {
+    const executables = [
+        'exe', 'dll', 'so', 'dylib', 'app', 'deb', 'rpm', 'dmg', 'pkg',
+        'msi', 'bat', 'cmd', 'sh', 'ps1', 'vbs', 'js', 'jar', 'class',
+        'pyc', 'pyo', 'elf', 'o', 'out', 'bin', 'run', 'com', 'scr',
+        'cpl', 'ocx', 'sys', 'drv', 'efi', 'mui', 'ax', 'ime', 'rs',
+        'tsp', 'fon', 'wasm', 'ko', 'mod', 'prx', 'puff', 'axf', 'dex'
+    ];
+    return executables.includes(normalizeExtension(extension));
+}
+// Get category from extension
+export function getCategoryFromExtension(extension) {
+    const ext = normalizeExtension(extension);
+    if (isImageExtension(ext))
+        return 'image';
+    if (isMediaExtension(ext))
+        return 'media';
+    if (isDocumentExtension(ext))
+        return 'document';
+    if (isCompressedExtension(ext))
+        return 'archive';
+    if (isExecutableExtension(ext))
+        return 'executable';
+    // Check for specific categories
+    const categories = {
+        font: ['ttf', 'otf', 'woff', 'woff2', 'eot', 'fon', 'fnt'],
+        database: ['db', 'db3', 'sqlite', 'sqlite3', 'mdb', 'accdb', 'dbf'],
+        code: ['js', 'ts', 'jsx', 'tsx', 'py', 'java', 'c', 'cpp', 'h', 'hpp', 'cs', 'php', 'rb', 'go', 'rs', 'swift', 'kt', 'scala', 'r', 'lua', 'pl', 'sh', 'bash', 'zsh', 'fish', 'ps1', 'psm1', 'psd1', 'bat', 'cmd'],
+        config: ['json', 'xml', 'yaml', 'yml', 'toml', 'ini', 'cfg', 'conf', 'properties', 'env'],
+        text: ['txt', 'md', 'markdown', 'rst', 'asciidoc', 'adoc', 'org', 'tex', 'log']
+    };
+    for (const [category, extensions] of Object.entries(categories)) {
+        if (extensions.includes(ext)) {
+            return category;
+        }
+    }
+    return 'other';
+}
+// Common double extensions (e.g., .tar.gz)
+const DOUBLE_EXTENSIONS = [
+    'tar.gz', 'tar.bz2', 'tar.xz', 'tar.lz', 'tar.lzma', 'tar.Z',
+    'tar.br', 'tar.zst', 'user.js', 'min.js', 'min.css', 'd.ts'
+];
+// Get double extension if applicable
+export function getDoubleExtension(filename) {
+    const lower = filename.toLowerCase();
+    for (const doubleExt of DOUBLE_EXTENSIONS) {
+        if (lower.endsWith('.' + doubleExt)) {
+            return doubleExt;
+        }
+    }
+    return null;
+}

package/esm/utils/magic-bytes.js

@@ -0,0 +1,61 @@
+// Magic bytes utility functions
+export function hexToBuffer(hexArray) {
+    const bytes = hexArray.map(hex => {
+        if (hex === '?')
+            return 0; // Wildcard placeholder
+        return parseInt(hex.replace(/0x/i, ''), 16);
+    });
+    return Buffer.from(bytes);
+}
+export function bufferToHex(buffer) {
+    return buffer.toString('hex');
+}
+export function compareBytes(buffer, pattern, offset = 0) {
+    // Empty patterns should not match
+    if (!pattern || pattern.length === 0) {
+        return false;
+    }
+    if (offset + pattern.length > buffer.length) {
+        return false;
+    }
+    for (let i = 0; i < pattern.length; i++) {
+        if (pattern[i] === '?')
+            continue; // Skip wildcards
+        const expectedByte = parseInt(pattern[i].replace(/0x/i, ''), 16);
+        const actualByte = buffer[offset + i];
+        if (expectedByte !== actualByte) {
+            return false;
+        }
+    }
+    return true;
+}
+export function findMagicBytes(buffer, patterns) {
+    for (let i = 0; i < patterns.length; i++) {
+        const { pattern, offset = 0 } = patterns[i];
+        if (compareBytes(buffer, pattern, offset)) {
+            return i;
+        }
+    }
+    return -1;
+}
+// Extract a specific number of bytes from buffer at offset
+export function extractBytes(buffer, offset, length) {
+    if (offset + length > buffer.length) {
+        return buffer.slice(offset);
+    }
+    return buffer.slice(offset, offset + length);
+}
+// Check if buffer contains text-like content
+export function isTextLike(buffer) {
+    const sampleSize = Math.min(buffer.length, 512);
+    let printableCount = 0;
+    for (let i = 0; i < sampleSize; i++) {
+        const byte = buffer[i];
+        // Check for printable ASCII characters, tabs, newlines, carriage returns
+        if ((byte >= 32 && byte <= 126) || byte === 9 || byte === 10 || byte === 13) {
+            printableCount++;
+        }
+    }
+    // If more than 85% are printable characters, likely text
+    return (printableCount / sampleSize) > 0.85;
+}

package/esm/utils/mime-types.js

@@ -0,0 +1,90 @@
+// MIME type utility functions
+// Common MIME type categories
+export const MIME_CATEGORIES = {
+    IMAGE: 'image',
+    VIDEO: 'video',
+    AUDIO: 'audio',
+    APPLICATION: 'application',
+    TEXT: 'text',
+    FONT: 'font'
+};
+// Extract category from MIME type
+export function getMimeCategory(mimeType) {
+    const category = mimeType.split('/')[0];
+    if (Object.values(MIME_CATEGORIES).includes(category)) {
+        return category;
+    }
+    return null;
+}
+// Check if MIME type is binary
+export function isBinaryMimeType(mimeType) {
+    const textTypes = [
+        'text/',
+        'application/json',
+        'application/xml',
+        'application/javascript',
+        'application/typescript',
+        'application/x-sh',
+        'application/x-csh',
+        'application/x-python',
+        'application/x-ruby',
+        'application/x-perl'
+    ];
+    return !textTypes.some(type => mimeType.startsWith(type));
+}
+// Normalize MIME type (remove parameters)
+export function normalizeMimeType(mimeType) {
+    return mimeType.split(';')[0].trim().toLowerCase();
+}
+// Get file category from MIME type
+export function getFileCategoryFromMime(mimeType) {
+    const normalized = normalizeMimeType(mimeType);
+    if (normalized.startsWith('image/'))
+        return 'image';
+    if (normalized.startsWith('video/'))
+        return 'video';
+    if (normalized.startsWith('audio/'))
+        return 'audio';
+    if (normalized.startsWith('font/'))
+        return 'font';
+    if (normalized.startsWith('text/'))
+        return 'text';
+    // Special cases for application types
+    if (normalized.includes('zip') || normalized.includes('compressed') || normalized.includes('archive')) {
+        return 'archive';
+    }
+    if (normalized.includes('pdf') || normalized.includes('document') || normalized.includes('msword') || normalized.includes('officedocument')) {
+        return 'document';
+    }
+    if (normalized.includes('executable') || normalized.includes('x-msdownload') || normalized.includes('x-elf') || normalized.includes('x-mach')) {
+        return 'executable';
+    }
+    if (normalized.includes('sqlite') || normalized.includes('database')) {
+        return 'database';
+    }
+    return 'other';
+}
+// Common MIME type aliases
+const MIME_ALIASES = {
+    'application/x-javascript': 'application/javascript',
+    'text/javascript': 'application/javascript',
+    'application/x-mpegURL': 'application/vnd.apple.mpegurl',
+    'audio/mp3': 'audio/mpeg',
+    'audio/x-mp3': 'audio/mpeg',
+    'audio/x-mpeg': 'audio/mpeg',
+    'video/x-m4v': 'video/mp4',
+    'audio/x-m4a': 'audio/mp4',
+    'image/jpg': 'image/jpeg',
+    'image/x-png': 'image/png',
+    'image/x-icon': 'image/vnd.microsoft.icon',
+    'text/xml': 'application/xml',
+    'application/x-compressed': 'application/x-compress',
+    'application/x-gzip': 'application/gzip',
+    'application/x-bzip': 'application/x-bzip2',
+    'application/x-tar': 'application/tar'
+};
+// Resolve MIME type aliases
+export function resolveMimeAlias(mimeType) {
+    const normalized = normalizeMimeType(mimeType);
+    return MIME_ALIASES[normalized] || normalized;
+}

package/file-type-detector.d.ts

@@ -0,0 +1,101 @@
+import { Readable } from 'stream';
+import { FileTypeDefinition, DetectionResult } from './file-types-registry';
+export interface FileTypeDetectorOptions {
+    peekBytes?: number;
+    checkMultipleOffsets?: boolean;
+    maxOffset?: number;
+}
+export declare class FileTypeDetector {
+    private fileTypes;
+    private options;
+    private magicBytesCache;
+    private extensionCache;
+    constructor(options?: FileTypeDetectorOptions);
+    /**
+     * Detect file type from a stream (PRIMARY METHOD - memory efficient)
+     * @param stream - Readable stream to detect from
+     * @returns Detection result or null if not detected
+     */
+    detectFromStream(stream: Readable): Promise<DetectionResult | null>;
+    /**
+     * Detect file type from an already-read buffer
+     * @param buffer - Buffer to detect from
+     * @returns Detection result or null if not detected
+     */
+    detectFromBuffer(buffer: Buffer): Promise<DetectionResult | null>;
+    /**
+     * Detect file type from extension only
+     * @param extension - File extension (with or without dot)
+     * @returns Array of possible detection results with lower confidence
+     */
+    detectFromExtension(extension: string): DetectionResult[];
+    /**
+     * Get all file types by category
+     * @param category - Category name (e.g., 'image', 'video', 'archive')
+     * @returns Array of file type definitions
+     */
+    getByCategory(category: string): FileTypeDefinition[];
+    /**
+     * Add a new file type dynamically
+     * @param fileType - File type definition to add
+     */
+    addFileType(fileType: FileTypeDefinition): void;
+    /**
+     * Remove a file type by name
+     * @param name - Name of the file type to remove
+     */
+    removeFileType(name: string): boolean;
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+    /**
+     * Get all registered file types
+     * @returns Array of all file type definitions
+     */
+    getAllFileTypes(): FileTypeDefinition[];
+    /**
+     * Check magic bytes at a specific offset
+     * @private
+     */
+    private checkMagicBytesAtOffset;
+    /**
+     * Generate offsets to check based on buffer size
+     * @private
+     */
+    private generateOffsets;
+    /**
+     * Enhance detection result with additional information
+     * @private
+     */
+    private enhanceDetectionResult;
+    /**
+     * Detect file type with fallback to extension
+     * @param input - Readable stream or Buffer
+     * @param filename - Optional filename for extension fallback
+     * @returns Detection result with attached stream for reuse (if input was stream)
+     */
+    detectWithFallback(input: Readable | Buffer, filename?: string): Promise<(DetectionResult & {
+        _stream?: Readable;
+    }) | null>;
+    /**
+     * Check if a buffer matches a specific file type
+     * @param buffer - Buffer to check
+     * @param fileTypeName - Name of the file type to check against
+     * @returns True if matches, false otherwise
+     */
+    isFileType(buffer: Buffer, fileTypeName: string): boolean;
+    /**
+     * Get statistics about registered file types
+     * @returns Statistics object
+     */
+    getStatistics(): {
+        totalTypes: number;
+        byCategory: Record<string, number>;
+        byMimePrefix: Record<string, number>;
+    };
+}
+export declare const defaultDetector: FileTypeDetector;
+export declare function detectFromStream(stream: Readable): Promise<DetectionResult | null>;
+export declare function detectFromBuffer(buffer: Buffer): Promise<DetectionResult | null>;
+export declare function detectFromExtension(extension: string): DetectionResult[];