isBinaryFile

isBinaryFile is a small, focused Node.js library that answers one question reliably: is this file binary or text? It reads only the first few hundred bytes of a file (or an in-memory Buffer), checks for null bytes and BOM markers, and falls back to a suspicious-character heuristic ported from the silver searcher (ag) project to flag non-ASCII-heavy content as binary. Both async (isBinaryFile) and synchronous (isBinaryFileSync) entry points are provided, each accepting either a file path or a raw Buffer.

Beyond the basic heuristic, the library ships explicit encoding hints so callers with prior knowledge of a file’s likely encoding (UTF-16 with or without BOM, Latin-1/ISO-8859-1, or CJK encodings like Big5, GB2312, GBK, EUC-KR, and Shift-JIS) can avoid false positives that a generic byte-scanning heuristic would otherwise produce. UTF-16 without a BOM is auto-detected by analyzing null-byte position patterns even without a hint. It’s widely used as a dependency inside file-watching, linting, and build tooling that needs to skip binary assets when processing a directory tree.

What You Get

• Async and sync APIs - isBinaryFile() returns a Promise<boolean>, isBinaryFileSync() returns a boolean directly, both accepting a file path or Buffer.
• BOM-aware detection - recognizes UTF-8, UTF-16 (LE/BE), and UTF-32 (LE/BE) byte-order marks to correctly classify text files that would otherwise trip a naive null-byte check.
• Encoding hints - pass an explicit encoding option (utf-16, latin1, cjk, big5, gb2312, gbk, euc-kr, shift-jis) to tune detection for files using non-UTF-8 encodings.
• No-BOM UTF-16 auto-detection - inspects null-byte position parity across the sampled bytes to identify UTF-16LE/BE text even when no BOM is present.
• Bounded, allocation-safe reads - only samples up to 512 bytes per file, with explicit bounds checks in its internal byte reader to avoid unbounded array allocation on malformed input.
• TypeScript-first - written entirely in TypeScript with published .d.ts types and an ESM-only package output.

Common Use Cases

• Skipping binary assets in file-watchers and build tools - a bundler or linter walks a directory tree and needs to skip images, fonts, and compiled artifacts before attempting to parse them as text.
• Safe diffing and search tools - a search-and-replace or grep-like CLI tool needs to avoid treating binary files as text (and printing garbage) the way Perl’s -B switch or the silver searcher (ag) do.
• Upload/ingestion pipelines - a service accepting arbitrary file uploads needs a fast, sample-based check to route binary and text files to different processing paths.
• Internationalized text processing - an application handling legacy text files in Latin-1, Shift-JIS, Big5, or other non-UTF-8 encodings needs encoding hints to avoid false ‘binary’ classifications on valid non-ASCII text.

Under The Hood

Architecture The library is a single-purpose module split into two files: src/index.ts, which exposes the public isBinaryFile/isBinaryFileSync functions and the internal isBinaryCheck heuristic (BOM checks, a bounded Reader class used to speculatively parse the sampled bytes as a Protobuf message, and a suspicious-byte ratio fallback), and src/encoding.ts, which isolates all encoding-hint logic (UTF-16 no-BOM detection via null-byte parity, and per-hint text validity checks for Latin-1/CJK encodings). The async and sync code paths are intentionally near-duplicates of each other (one using node:fs/promises, the other node:fs sync calls) rather than sharing a common core, keeping each path simple and dependency-free at the cost of some duplication between isBinaryFile and isBinaryFileSync.

Tech Stack The package targets modern Node.js (engines.node >= 24.0.0), is published as ESM-only ("type": "module") with hand-written TypeScript compiled via tsc to lib/, and has zero runtime dependencies — only devDependencies for tooling (typescript, jest/ts-jest for testing, oxlint for linting, prettier for formatting). There is no framework or build system beyond the TypeScript compiler itself, reflecting the library’s intentionally narrow scope.

Code Quality Tests live under test/ (async.test.ts, sync.test.ts, encoding-hints.test.ts) and run against a large fixture corpus (test/fixtures/) covering real binary formats (PDF, GIF), UTF-8/16/32 BOM variants, CJK-encoded text samples, and edge cases like near-UTF-8-boundary byte counts, indicating deliberate attention to encoding edge cases rather than only happy-path coverage. The project uses oxlint for linting and prettier for formatting, runs tests via Jest with ESM support (NODE_OPTIONS=--experimental-vm-modules), and gates publishing behind prepublishOnly running both tests and lint. GitHub Actions CI runs on Node 24 for every push and PR, with a separate release-please workflow automating versioning and changelog generation.

API Design The public surface is deliberately minimal: two functions (async and sync variants), each overloaded to accept either a file path string or a raw Buffer, plus one options object (encoding, size). There’s no configuration object, class, or setup step — callers install the package and call one function. The encoding-hint vocabulary is a closed, documented string union (EncodingHint) rather than free-form strings, which keeps misuse (typo’d encoding names) a compile-time TypeScript error rather than a silent runtime miss. Getting started requires zero boilerplate beyond a single import.