istextorbinary

The library uses a two-step detection process to ensure high accuracy and performance:

1. Extension Check: If a filename is provided, the library checks its extensions from right to left against known text and binary extension lists. This allows for accurate detection of files with multiple extensions (e.g., app.x.y).
2. Contents Check: If no filename is provided, or if the extension check is indeterminate, the library inspects the buffer contents. It checks 24 bytes at the start, middle, and end of the buffer. This three-location check is designed to be more accurate than single-location checks while remaining more performant than scanning large chunks of data.

Note: The combination of extension and content checks is necessary because UTF-16 characters can be indistinguishable from binary data if only content is checked.

For browser-based usage using ES Modules, you can use one of the following CDNs:

Skypack

<script type="module">
    import * as pkg from '//cdn.skypack.dev/istextorbinary@^9.5.0'
</script>

unpkg

<script type="module">
    import * as pkg from '//unpkg.com/istextorbinary@^9.5.0'
</script>

jspm

<script type="module">
    import * as pkg from '//dev.jspm.io/istextorbinary@9.5.0'
</script>

Import the Deno-compatible edition directly from unpkg:

import * as pkg from 'https://unpkg.com/istextorbinary@^9.5.0/edition-deno/index.ts'

To use the package in a Node.js project, install it via npm:

npm install --save istextorbinary

You can fine-tune the getEncoding detection by passing an EncodingOpts object. This is useful if you want to target a specific offset or change the size of the inspected chunk.

EncodingOpts properties:

• chunkLength (number, default: 24): The number of bytes to inspect in a single chunk.
• chunkBegin (number, optional): The starting byte offset for the inspection. If chunkBegin is not provided, the function defaults to its multi-pass (start, middle, end) strategy. If provided, it performs a single check at that specific location.

import { getEncoding, type EncodingOpts } from 'istextorbinary';

const opts: EncodingOpts = {
  chunkLength: 64,
  chunkBegin: 1024
};

const encoding = getEncoding(buffer, opts);
// Note: Providing chunkBegin disables the automatic start/middle/end multi-pass check.

Determines if a file or buffer is text. The detection logic follows this priority:

1. Extension Check: If a filename is provided, it checks the file extension against known text and binary extension lists. This is the fastest method.
2. Encoding Check: If the extension is unknown or no filename is provided, it falls back to inspecting the buffer using getEncoding().

Returns true if text, false if binary, or null if neither filename nor buffer were provided.

import { isText } from 'istextorbinary';

// Using filename for fast extension check
const isTextFile = isText('example.txt'); // true

// Using buffer for encoding detection
const isTextBuffer = isText(undefined, buffer);

// No info provided
const result = isText(); // null

Determines if a file or buffer is binary. It is a convenience wrapper around isText() that returns the inverse result.

Returns true if binary, false if text, or null if neither filename nor buffer were provided.

import { isBinary } from 'istextorbinary';

const isBinaryFile = isBinary('image.png'); // true
const isBinaryBuffer = isBinary(undefined, buffer); // true/false/null

Inspects a buffer to determine if its encoding is 'utf8' or 'binary'.

Detection Strategy: By default, the function performs a multi-pass check to ensure accuracy. It inspects the start, middle, and end of the buffer for characters that are invalid in UTF-8. This is necessary because a buffer might appear to be UTF-8 in one section but contain binary data in another.

Returns:

• 'utf8' if the buffer is valid text.
• 'binary' if invalid UTF-8 characters (like control characters $\le 8$ or the replacement character �) are found.
• null if no buffer is provided.

import { getEncoding } from 'istextorbinary';

const encoding = getEncoding(buffer); // 'utf8' | 'binary' | null

To use isTextOrBinary in a CommonJS environment, require the package directly. The package exports a function that determines if a given input (typically a Buffer or Uint8Array) represents text or binary data.

const isTextOrBinary = require('istextorbinary');

// Example usage (assuming input is a Buffer or Uint8Array)
const result = isTextOrBinary(someBuffer);
console.log(result); // true if text, false if binary

The EncodingOpts interface defines configuration for the getEncoding function.

export interface EncodingOpts {
	/** Defaults to 24 */
	chunkLength?: number;

	/** If not provided, will check the start, middle, and end */
	chunkBegin?: number;
}