Mimetics

Know thy files

Mimetics identifies file types based on magic bytes, patterns, and other unique file attributes. It provides an intuitive API for both synchronous and asynchronous file type detection, supporting various file formats including text, image, audio, video, and archive types.

Installation

To add Mimetics to your project, use:

1npm install mimetics

Usage

Mimetics allows you to detect file types from file buffers, file names, and even File objects in browser environments. You can also extend its functionality by adding custom definitions.

Basic Example

1const Mimetics = require('mimetics')
2const fs = require('fs')
3
4// Load a buffer from a file (e.g., sample.txt)
5const buffer = fs.readFileSync('sample.txt')
6const mimetics = new Mimetics()
7
8// Synchronous file type detection
9const fileType = mimetics.parse(buffer)
10console.log(fileType) // Output: { tag: 'text', type: 'text', ext: 'txt', mime: 'text/plain' }
11
12// Asynchronous file type detection (for ZIP files, etc.)
13mimetics.parseAsync(buffer).then(fileType => {
14  console.log(fileType)
15})

Adding Custom Definitions

You can extend Mimetics with custom definitions for additional file types.

1
2const Mimetics = require('mimetics')
3
4const customDefinitions = [
5  {
6    tag: 'custom',
7    type: 'myfiletype',
8    ext: 'myft',
9    mime: 'application/x-myfiletype',
10    magic: [0x12, 0x34, 0x56],
11    pattern: /^MYFILE/i,
12  }
13]
14
15const mimetics = new Mimetics()
16mimetics.addDefinitions(customDefinitions)
17
18const buffer = /* load a buffer for a custom file type */
19const fileType = mimetics.parse(buffer)
20console.log(fileType) // Output should match custom definition

Browser Example

1const Mimetics = require('mimetics')
2
3const fileInput = document.querySelector('#fileInput')
4fileInput.addEventListener('change', async (event) => {
5  const file = event.target.files[0]
6  const mimetics = new Mimetics()
7  
8  const fileType = await mimetics.fromFile(file)
9  console.log(fileType) // Output: file type information
10})

Supported File Types

Mimetics currently supports a variety of formats, including but not limited to:

• Text: Plain text (txt), Markdown (md), LaTeX (tex), RTF (rtf)
• Image: JPEG (jpg, jpeg), PNG (png), GIF (gif), BMP (bmp), ICON (ico), WebP (webp), PDF (pdf), SVG (svg)
• Audio: MP3 (mp3), OGG (ogg), WAV (wav)
• Video: MP4 (mp4), QuickTime (mov), AVI (avi), MKV (mkv), WebM (webm), FLV (flv)
• Archive: ZIP (zip), RAR (rar), GZIP (gz), 7ZIP (7z)
• Ebook: EPUB (epub)

API Reference

parse(buffer, name)

Synchronously parses a buffer to identify the file type.

• Parameters:

  • buffer (Uint8Array | ArrayBuffer): The file buffer to parse.
  • name (string, optional): The file name, which can help in detection.

• Returns: File type object or null if no match is found.

parseAsync(buffer, name)

Asynchronously parses a buffer to identify the file type, with support for ZIP archive analysis.

• Parameters:

  • buffer (Uint8Array | ArrayBuffer): The file buffer to parse.
  • name (string, optional): The file name, which can assist in detection.

• Returns: A promise resolving to a file type object or null if no match is found.

fromName(filePath)

Determines file type based on the file name extension.

• Parameters:

  • filePath (string): The file path or name.

• Returns: File type object based on the file extension or null if no match is found.

fromFile(file)

Asynchronously determines the file type from a File object (for browser use).

• Parameters:

  • file (File): File object to analyze.

• Returns: A promise resolving to a file type object.

addDefinitions(definitions)

Adds custom file definitions to the existing set.

• Parameters:
  • definitions (Array