eilseq

Detect filenames containing Unicode characters that macOS rejects with an EILSEQ (illegal byte sequence) error.

Install

npm install eilseq

Usage

import { eilseqRegex, isEilseqFilename } from "eilseq";

eilseqRegex.test("report-\u0378.txt"); // true
isEilseqFilename("report-\u0378.txt"); // true
isEilseqFilename("report.txt"); // false

eilseqRegex is a Unicode-aware regular expression matching any character in the generated dataset. isEilseqFilename(filename) returns whether a string contains at least one such character.

This package detects only the characters that produced EILSEQ when tested individually. It does not validate unrelated filename constraints such as path separators, reserved names, or maximum filename length.

Regenerating the data

The dataset depends on the filesystem behavior of macOS and must be generated on macOS. _generate.ts tries every Unicode scalar value as a filename in a fresh temporary directory. It writes the minified eilseq-characters.gen.json audit artifact and the compact src/regex.gen.ts source, then removes the temporary directory.

The JSON data is checked into the GitHub repository for inspection and reproducibility, but it is intentionally excluded from the npm package.

Install dependencies and regenerate the JSON file:

vp install
vp run generate

Validate the package:

vp check
vp test
vp run build