isbinaryfile

To use this library in your Node.js project, install it using npm:

npm install isbinaryfile

For files using non-UTF-8 encodings, provide an encoding hint in the options object to prevent false positives (e.g., flagging text as binary because of non-ASCII characters).

import { isBinaryFile, isBinaryFileSync } from 'isbinaryfile';

// UTF-16 hint
const result1 = await isBinaryFile('utf16-file.txt', { encoding: 'utf-16' });

// Latin-1 hint
const result2 = isBinaryFileSync('german-text.txt', { encoding: 'latin1' });

// CJK hints
const result3 = isBinaryFileSync('chinese-big5.txt', { encoding: 'big5' });
const result4 = isBinaryFileSync('asian-text.txt', { encoding: 'cjk' });

Use the synchronous isBinaryFileSync function to check a file path or a buffer. It returns a boolean immediately.

Arguments:

• filepath: A string indicating the path to the file.
• bytes: A Buffer of the file's contents.

Options:

• size: The size of the buffer to check (defaults to bytes.length).
• encoding: An encoding hint.

import { isBinaryFileSync } from 'isbinaryfile';
import fs from 'fs';

const filename = 'fixtures/pdf.pdf';

// Sync with file path
const resultPath = isBinaryFileSync(filename);

// Sync with buffer
const bytes = fs.readFileSync(filename);
const resultBytes = isBinaryFileSync(bytes);

// Sync with explicit size
const partialBuffer = Buffer.alloc(100);
console.log(isBinaryFileSync(partialBuffer, { size: 100 }));

Use the asynchronous isBinaryFile function to check if a file at a given path is binary. It returns a Promise<boolean>: true if the file is binary, false otherwise.

Note: If the file does not exist or is a directory, an error is thrown.

import { isBinaryFile } from 'isbinaryfile';

const filename = 'path/to/file.ext';
const result = await isBinaryFile(filename);
if (result) {
  console.log('It is binary!');
}

Use the asynchronous isBinaryFile function with a Buffer to check if the provided bytes represent a binary file.

Options:

• size: The size of the buffer to check (defaults to bytes.length).
• encoding: An encoding hint to improve detection accuracy.

import { isBinaryFile } from 'isbinaryfile';

const bytes = Buffer.from([0x00, 0x01, 0x02]);
const result = await isBinaryFile(bytes, { size: bytes.length });

You can pass an IsBinaryOptions object to the detection functions to improve accuracy or handle specific buffer constraints.

Options:

• encoding (optional): An EncodingHint to provide a hint about the expected encoding. This helps avoid false positives by using specialized validation for that encoding.
• size (optional): The size of the buffer. This is only used when the input is a Buffer. It allows you to specify the logical size of the buffer if it differs from the actual allocated length.

import { isBinaryFile, type IsBinaryOptions, type EncodingHint } from 'isbinaryfile';

const options: IsBinaryOptions = {
  encoding: 'utf8' as EncodingHint, // Example hint
  size: 1024
};

await isBinaryFile(myBuffer, options);

Use the asynchronous isBinaryFile function to determine if a file (provided as a string path) or a Buffer is a binary file. It returns a Promise<boolean> that resolves to true if the content is detected as binary, and false if it is text.

Parameters:

• file: A string representing the file path or a Buffer containing the file content.
• options (optional): An IsBinaryOptions object to refine detection.

Returns: Promise<boolean>

import { isBinaryFile } from 'isbinaryfile';

// Check a file path
const isFileBinary = await isBinaryFile('path/to/file.txt');

// Check a Buffer
const buffer = Buffer.from('some content');
const isBufferBinary = await isBinaryFile(buffer);

Use the synchronous isBinaryFileSync function to determine if a file (provided as a string path) or a Buffer is a binary file. This is useful in environments where blocking the event loop is acceptable or required.

Parameters:

• file: A string representing the file path or a Buffer containing the file content.
• options (optional): An IsBinaryOptions object to refine detection.

Returns: boolean

import { isBinaryFileSync } from 'isbinaryfile';

// Check a file path synchronously
const isFileBinary = isBinaryFileSync('path/to/file.txt');

// Check a Buffer synchronously
const buffer = Buffer.from('some content');
const isBufferBinary = isBinaryFileSync(buffer);

When using encoding hints to improve text detection accuracy for non-UTF-8 files, you can provide one of the following supported encoding strings. These hints help the library distinguish between text and binary data when dealing with specific character sets like UTF-16 or CJK.

type EncodingHint =
  | 'utf-16'       // UTF-16 (auto-detect endianness)
  | 'utf-16le'     // UTF-16 Little Endian
  | 'utf-16be'     // UTF-16 Big Endian
  | 'latin1'       // ISO-8859-1 / Latin-1
  | 'iso-8859-1'   // Alias for latin1
  | 'cjk'          // Generic CJK (Big5, GB2312, GBK, EUC-KR, Shift-JIS)
  | 'big5'         // Traditional Chinese
  | 'gb2312'       // Simplified Chinese
  | 'gbk'          // Extended GB2312
  | 'euc-kr'       // Korean
  | 'shift-jis';   // Japanese