get-east-asian-width

get-east-asian-width is a tiny JavaScript library that determines the East Asian Width property of a Unicode code point, per Unicode Technical Report #11. East Asian Width categorizes characters by how much horizontal space they occupy in East Asian typography, which is essential for correctly aligning and laying out text that mixes Latin characters with Japanese, Chinese, or Korean script.

Unlike older similar packages that ship a Unicode table frozen at publish time, this library regenerates its lookup data from the latest official Unicode EastAsianWidth.txt on every release, so width classifications stay accurate as new code points and scripts are added to the standard each year.

What You Get

• eastAsianWidth(codePoint, options?) returning 1 or 2 columns for a given code point
• eastAsianWidthType(codePoint) returning the raw category (fullwidth, halfwidth, wide, narrow, neutral, ambiguous)
• An ambiguousAsWide option to control how context-dependent ambiguous characters are treated
• Lookup data regenerated from the current Unicode EastAsianWidth.txt on every release instead of a stale bundled table
• Full TypeScript type definitions (index.d.ts) with documented examples for both exports

Common Use Cases

• Computing the correct visual width of a string in a terminal emulator or TUI so CJK text doesn’t misalign output
• Powering higher-level string-width utilities (e.g. sindresorhus/string-width) that need per-character column counts
• Text wrapping and truncation logic in CLI tools that must account for double-width Japanese, Chinese, or Korean characters
• Font and layout engines that need to reserve the correct horizontal space per glyph in mixed-script documents

Under The Hood

Architecture: The library is organized as a thin classification layer over generated Unicode data. lookup-data.js holds flat sorted arrays of [start, end] code-point range pairs for each of the six width categories, produced by scripts/build.js, which fetches Unicode’s canonical EastAsianWidth.txt, groups ranges by category, and compresses them via simplify-ranges. lookup.js performs the actual classification: isAmbiguous, isFullWidth, isHalfWidth, isNarrow, and isWide each do a cheap min/max bounds check before delegating to isInRange(). isWide additionally precomputes a “fast path” range around the common CJK ideograph block (starting at U+4E00) so the overwhelmingly common case of wide CJK text resolves without a full binary search. index.js composes these primitives into the two public functions and validates input via Number.isSafeInteger.

Tech Stack: Pure ESM with zero runtime dependencies — package.json declares only devDependencies (ava for tests, xo for linting, typescript for .d.ts checking, simplify-ranges and outdent used solely by the build script). It targets Node.js 18+ and ships sideEffects: false for clean tree-shaking. The build pipeline that regenerates lookup-data.js from Unicode’s live UCD data is a one-off scripts/build.js script rather than a bundler, keeping the published package itself dependency-free.

Code Quality: utilities.js implements a textbook iterative binary search (isInRange) over the flat range arrays — O(log n) per lookup with no recursion overhead. test.js uses ava to cover all six width categories plus explicit validation of the TypeError thrown on non-integer input, giving confidence the classification boundaries and error paths both work. The codebase is small (under 200 lines across the runtime files), consistently formatted, and linted with xo, sindresorhus’s stricter-than-default ESLint config.

API Design: The public surface is deliberately minimal — two named functions and one boolean option (ambiguousAsWide) — with TSDoc comments on every export including runnable usage examples, matching the pattern used across the author’s other Unicode-string utilities (e.g. string-width, is-fullwidth-code-point). Both functions take a raw code point (as returned by String.prototype.codePointAt) rather than a string, keeping the API composable as a low-level primitive for other libraries to build on, at the minor cost of requiring callers to iterate code points themselves for multi-character strings.