mime-bytes 0.0.2

package/esm/file-type-detector.js

@@ -0,0 +1,374 @@
+// Main file type detector class with stream-focused API
+import { peek } from './peak';
+import { FILE_TYPES, getFileTypeByExtension, getFileTypesByCategory, getContentTypeByExtension, detectCharset, getContentTypeForExtension } from './file-types-registry';
+import { compareBytes } from './utils/magic-bytes';
+import { normalizeExtension } from './utils/extensions';
+import { resolveMimeAlias } from './utils/mime-types';
+export class FileTypeDetector {
+    fileTypes;
+    options;
+    magicBytesCache;
+    extensionCache;
+    constructor(options = {}) {
+        // Create a copy of FILE_TYPES to avoid modifying the global registry
+        this.fileTypes = [...FILE_TYPES];
+        this.options = {
+            peekBytes: options.peekBytes || 32,
+            checkMultipleOffsets: options.checkMultipleOffsets !== false,
+            maxOffset: options.maxOffset || 12
+        };
+        this.magicBytesCache = new Map();
+        this.extensionCache = new Map();
+    }
+    /**
+     * 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
+     */
+    async detectFromStream(stream) {
+        try {
+            const [buffer, peekStream] = await peek.promise(stream, this.options.peekBytes);
+            // Check multiple offsets for different file types
+            const result = await this.detectFromBuffer(buffer);
+            // Important: Return the peek stream so it can be used for further processing
+            // The caller should use peekStream instead of the original stream
+            if (result) {
+                result._stream = peekStream;
+            }
+            return result;
+        }
+        catch (error) {
+            // Handle stream errors gracefully
+            // Only log errors in non-test environments
+            if (process.env.NODE_ENV !== 'test') {
+                console.error('Error detecting file type from stream:', error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Detect file type from an already-read buffer
+     * @param buffer - Buffer to detect from
+     * @returns Detection result or null if not detected
+     */
+    async detectFromBuffer(buffer) {
+        if (!buffer || buffer.length === 0) {
+            return null;
+        }
+        // Check multiple offsets if enabled
+        const offsets = this.options.checkMultipleOffsets
+            ? this.generateOffsets(buffer.length)
+            : [0];
+        for (const offset of offsets) {
+            const fileType = this.checkMagicBytesAtOffset(buffer, offset);
+            if (fileType) {
+                return this.enhanceDetectionResult(fileType, buffer);
+            }
+        }
+        // No magic bytes matched, but we can still detect charset for unknown files
+        const charset = detectCharset(buffer);
+        if (charset !== 'binary') {
+            // Return a generic text file result
+            return {
+                name: 'text',
+                mimeType: 'text/plain',
+                extensions: ['txt'],
+                charset,
+                contentType: 'text/plain',
+                confidence: 0.5 // Lower confidence since we only detected charset
+            };
+        }
+        return 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) {
+        const cleanExt = normalizeExtension(extension);
+        // Check cache first
+        if (this.extensionCache.has(cleanExt)) {
+            const cachedTypes = this.extensionCache.get(cleanExt);
+            return cachedTypes.map(fileType => ({
+                name: fileType.name,
+                mimeType: resolveMimeAlias(fileType.mimeType),
+                extensions: fileType.extensions,
+                charset: 'unknown', // Can't determine charset from extension alone
+                contentType: getContentTypeByExtension(cleanExt) || fileType.mimeType,
+                confidence: 0.8 // Lower confidence for extension-only detection
+            }));
+        }
+        const fileTypes = getFileTypeByExtension(cleanExt);
+        // Cache the result
+        this.extensionCache.set(cleanExt, fileTypes);
+        return fileTypes.map(fileType => ({
+            name: fileType.name,
+            mimeType: resolveMimeAlias(fileType.mimeType),
+            extensions: fileType.extensions,
+            charset: 'unknown', // Can't determine charset from extension alone
+            contentType: getContentTypeByExtension(cleanExt) || fileType.mimeType,
+            confidence: 0.8 // Lower confidence for extension-only detection
+        }));
+    }
+    /**
+     * Get all file types by category
+     * @param category - Category name (e.g., 'image', 'video', 'archive')
+     * @returns Array of file type definitions
+     */
+    getByCategory(category) {
+        return getFileTypesByCategory(category);
+    }
+    /**
+     * Add a new file type dynamically
+     * @param fileType - File type definition to add
+     */
+    addFileType(fileType) {
+        this.fileTypes.push(fileType);
+        // Clear caches when file types change
+        this.clearCache();
+    }
+    /**
+     * Remove a file type by name
+     * @param name - Name of the file type to remove
+     */
+    removeFileType(name) {
+        const index = this.fileTypes.findIndex(ft => ft.name === name);
+        if (index !== -1) {
+            this.fileTypes.splice(index, 1);
+            // Clear caches when file types change
+            this.clearCache();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Clear all caches
+     */
+    clearCache() {
+        this.magicBytesCache.clear();
+        this.extensionCache.clear();
+    }
+    /**
+     * Get all registered file types
+     * @returns Array of all file type definitions
+     */
+    getAllFileTypes() {
+        return [...this.fileTypes];
+    }
+    /**
+     * Check magic bytes at a specific offset
+     * @private
+     */
+    checkMagicBytesAtOffset(buffer, offset) {
+        // Check each file type in order
+        for (const fileType of this.fileTypes) {
+            // Skip if this file type requires a different offset
+            if (fileType.offset !== undefined && fileType.offset !== offset)
+                continue;
+            // Skip if offset is not 0 and file type doesn't specify an offset
+            if (offset > 0 && fileType.offset === undefined)
+                continue;
+            // Check if magic bytes match
+            if (compareBytes(buffer, fileType.magicBytes, offset)) {
+                return fileType;
+            }
+        }
+        return null;
+    }
+    /**
+     * Generate offsets to check based on buffer size
+     * @private
+     */
+    generateOffsets(bufferLength) {
+        const offsets = [];
+        for (let i = 0; i <= this.options.maxOffset && i < bufferLength; i += 4) {
+            offsets.push(i);
+        }
+        return offsets;
+    }
+    /**
+     * Enhance detection result with additional information
+     * @private
+     */
+    enhanceDetectionResult(fileType, buffer) {
+        // Use charset from file type definition if available, otherwise detect it
+        const charset = fileType.charset || detectCharset(buffer);
+        // Determine content type based on extension and charset
+        let contentType = fileType.contentType || fileType.mimeType;
+        // Try charset-aware content type lookup first
+        if (fileType.extensions.length > 0) {
+            const primaryExt = fileType.extensions[0];
+            const charsetAwareContentType = getContentTypeForExtension(primaryExt, charset);
+            if (charsetAwareContentType) {
+                contentType = charsetAwareContentType;
+            }
+            else if (!fileType.contentType) {
+                // Fall back to regular content type lookup if no charset-specific match
+                const inferredContentType = getContentTypeByExtension(primaryExt);
+                if (inferredContentType) {
+                    contentType = inferredContentType;
+                }
+            }
+        }
+        return {
+            name: fileType.name,
+            mimeType: resolveMimeAlias(fileType.mimeType),
+            extensions: fileType.extensions,
+            charset,
+            contentType: resolveMimeAlias(contentType),
+            confidence: 1.0 // High confidence for magic bytes detection
+        };
+    }
+    /**
+     * 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)
+     */
+    async detectWithFallback(input, filename) {
+        try {
+            let buffer;
+            let peekStream;
+            // Handle both Buffer and Readable inputs
+            if (Buffer.isBuffer(input)) {
+                buffer = input;
+            }
+            else {
+                const peekResult = await peek.promise(input, this.options.peekBytes);
+                buffer = peekResult[0];
+                peekStream = peekResult[1];
+            }
+            // Try magic bytes detection first
+            const magicResult = await this.detectFromBuffer(buffer);
+            if (magicResult) {
+                // If we have a filename, try to enhance with more specific content type
+                if (filename) {
+                    const lastDot = filename.lastIndexOf('.');
+                    if (lastDot !== -1) {
+                        const extension = filename.substring(lastDot + 1);
+                        // Check for generic text files that might have specific content types
+                        if (magicResult.name === 'text' && magicResult.charset) {
+                            const contentType = getContentTypeForExtension(extension, magicResult.charset);
+                            if (contentType) {
+                                // Enhance the result with charset-aware content type
+                                const enhancedResult = {
+                                    ...magicResult,
+                                    contentType,
+                                    confidence: 0.8 // Higher confidence since we have both magic bytes and extension
+                                };
+                                return peekStream ? { ...enhancedResult, _stream: peekStream } : enhancedResult;
+                            }
+                        }
+                        // Check for ZIP files that might be Office Open XML or other specific formats
+                        if (magicResult.name === 'zip' || magicResult.mimeType === 'application/zip') {
+                            const contentType = getContentTypeForExtension(extension, magicResult.charset || 'binary');
+                            if (contentType && contentType !== 'application/zip') {
+                                // Enhance the result with more specific content type
+                                const enhancedResult = {
+                                    ...magicResult,
+                                    contentType,
+                                    confidence: 0.9 // High confidence for known ZIP-based formats
+                                };
+                                return peekStream ? { ...enhancedResult, _stream: peekStream } : enhancedResult;
+                            }
+                        }
+                    }
+                }
+                // Attach the peek stream for reuse if available
+                return peekStream ? { ...magicResult, _stream: peekStream } : magicResult;
+            }
+            // Fallback to extension if filename provided
+            if (filename) {
+                const lastDot = filename.lastIndexOf('.');
+                if (lastDot !== -1) {
+                    const extension = filename.substring(lastDot + 1);
+                    const charset = detectCharset(buffer);
+                    // Try charset-aware content type lookup
+                    const contentType = getContentTypeForExtension(extension, charset);
+                    if (contentType) {
+                        // Create a result based on extension and detected charset
+                        const result = {
+                            name: extension.toLowerCase(),
+                            mimeType: contentType,
+                            extensions: [extension.toLowerCase()],
+                            charset,
+                            contentType,
+                            confidence: 0.7 // Higher confidence when charset matches
+                        };
+                        return peekStream ? { ...result, _stream: peekStream } : result;
+                    }
+                    // Fall back to regular extension detection
+                    const extensionResults = this.detectFromExtension(extension);
+                    if (extensionResults.length > 0) {
+                        const result = {
+                            ...extensionResults[0],
+                            charset, // Use detected charset
+                            confidence: 0.6 // Lower confidence for fallback
+                        };
+                        // Update content type if charset-specific mapping exists
+                        const charsetContentType = getContentTypeForExtension(extension, charset);
+                        if (charsetContentType) {
+                            result.contentType = charsetContentType;
+                        }
+                        return peekStream ? { ...result, _stream: peekStream } : result;
+                    }
+                }
+            }
+            // No detection possible
+            return null;
+        }
+        catch (error) {
+            // Only log errors in non-test environments
+            if (process.env.NODE_ENV !== 'test') {
+                console.error('Error in detectWithFallback:', error);
+            }
+            return 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, fileTypeName) {
+        const fileType = this.fileTypes.find(ft => ft.name === fileTypeName);
+        if (!fileType)
+            return false;
+        const offset = fileType.offset || 0;
+        return compareBytes(buffer, fileType.magicBytes, offset);
+    }
+    /**
+     * Get statistics about registered file types
+     * @returns Statistics object
+     */
+    getStatistics() {
+        const stats = {
+            totalTypes: this.fileTypes.length,
+            byCategory: {},
+            byMimePrefix: {}
+        };
+        for (const fileType of this.fileTypes) {
+            // Count by category
+            const category = fileType.category || 'other';
+            stats.byCategory[category] = (stats.byCategory[category] || 0) + 1;
+            // Count by MIME prefix
+            const mimePrefix = fileType.mimeType.split('/')[0];
+            stats.byMimePrefix[mimePrefix] = (stats.byMimePrefix[mimePrefix] || 0) + 1;
+        }
+        return stats;
+    }
+}
+// Export a default instance for convenience
+export const defaultDetector = new FileTypeDetector();
+// Convenience functions using the default detector
+export async function detectFromStream(stream) {
+    return defaultDetector.detectFromStream(stream);
+}
+export async function detectFromBuffer(buffer) {
+    return defaultDetector.detectFromBuffer(buffer);
+}
+export function detectFromExtension(extension) {
+    return defaultDetector.detectFromExtension(extension);
+}