unicode-escaper

A robust, zero-dependency Unicode escape/unescape library for JavaScript and TypeScript. Supports multiple escape formats, bidirectional conversion, and streaming for large files.

Features

• Multiple escape formats: \uXXXX, \u{XXXXX}, \xNN, &#xNNNN;, &#NNNN;, U+XXXX
• Bidirectional: Both escape and unescape in one package
• Streaming support: Process large files efficiently with Node.js and Web Streams
• Full Unicode support: Handles BMP, supplementary planes, surrogate pairs, and emoji
• Zero dependencies: Lightweight and fast
• TypeScript-first: Written in TypeScript with strict types
• Dual ESM/CJS: Works with both module systems
• Customizable filters: Control exactly which characters to escape

Installation

npm install unicode-escaper
# or
pnpm add unicode-escaper
# or
yarn add unicode-escaper

Quick Start

import { escape, unescape } from "unicode-escaper";

// Escape non-ASCII characters
escape("Hello 世界");
// => 'Hello \u4E16\u754C'

// Unescape back to original
unescape("Hello \\u4E16\\u754C");
// => 'Hello 世界'

Escape Formats

Format	Example	Description
unicode	\u4E16	Standard JavaScript Unicode escape (default)
unicode-es6	\u{4E16}	ES6 Unicode escape (supports full range)
hex	\xE9	Hex escape (0x00-0xFF only)
html-hex	世	HTML hexadecimal entity
html-decimal	世	HTML decimal entity
codepoint	U+4E16	Unicode code point notation

API Reference

Core Functions

escape(input, options?)

Escapes Unicode characters in a string.

import { escape } from "unicode-escaper";

// Default: preserve ASCII, escape everything else
escape("Café 世界 😀");
// => 'Caf\u00E9 \u4E16\u754C \uD83D\uDE00'

// Use ES6 format for emoji (cleaner output)
escape("Hello 😀", { format: "unicode-es6" });
// => 'Hello \u{1F600}'

// HTML entities
escape("Café", { format: "html-hex" });
// => 'Café'

escape("Café", { format: "html-decimal" });
// => 'Café'

// Escape everything (including ASCII)
escape("Hi", { preserveAscii: false });
// => '\u0048\u0069'

// Preserve Latin-1 characters
escape("Café 世界", { preserveLatin1: true });
// => 'Café \u4E16\u754C'

// Lowercase hex digits
escape("世", { uppercase: false });
// => '\u4e16'

unescape(input, options?)

Unescapes Unicode sequences back to characters.

import { unescape } from "unicode-escaper";

// Automatically detects and unescapes all formats
unescape("\\u4E16"); // => '世'
unescape("\\u{1F600}"); // => '😀'
unescape("\\xE9"); // => 'é'
unescape("世"); // => '世'
unescape("世"); // => '世'
unescape("U+4E16"); // => '世'

// Handle surrogate pairs
unescape("\\uD83D\\uDE00"); // => '😀'

// Only unescape specific formats
unescape("\\u4E16 世", { formats: ["unicode"] });
// => '世 世'

// Strict mode (throws on invalid sequences)
unescape("\\uZZZZ", { lenient: false });
// => throws Error

Convenience Functions

import {
  escapeToUnicode, // \uXXXX format
  escapeToUnicodeES6, // \u{XXXXX} format
  escapeToHex, // \xNN format
  escapeToHtmlHex, // &#xNNNN; format
  escapeToHtmlDecimal, // &#NNNN; format
  escapeToCodePoint, // U+XXXX format
  escapeAll, // Escape all characters
  escapeNonPrintable, // Escape control chars and non-ASCII
} from "unicode-escaper";

escapeToUnicodeES6("😀"); // => '\u{1F600}'
escapeToHtmlHex("世"); // => '世'
escapeAll("Hi"); // => '\u0048\u0069'

import {
  unescapeUnicode, // Only \uXXXX
  unescapeUnicodeES6, // Only \u{XXXXX}
  unescapeHex, // Only \xNN
  unescapeHtmlHex, // Only &#xNNNN;
  unescapeHtmlDecimal, // Only &#NNNN;
  unescapeCodePoint, // Only U+XXXX
  unescapeHtml, // Both HTML formats
  unescapeJs, // All JavaScript formats
} from "unicode-escaper";

Custom Filters

Control which characters to escape using filter functions:

import { escape, isNotAscii, isNotBmp, and, or, oneOf } from "unicode-escaper";

// Escape only non-ASCII (default behavior)
escape("Hello 世界", { filter: isNotAscii });

// Escape only emoji (non-BMP characters)
escape("Hello 世界 😀", { filter: isNotBmp });
// => 'Hello 世界 \uD83D\uDE00'

// Escape vowels
escape("Hello", { filter: oneOf("aeiouAEIOU") });
// => 'H\u0065ll\u006F'

// Combine filters
escape("Test", { filter: and(isNotAscii, isNotBmp) });

Available filters:

• isAscii / isNotAscii - ASCII range (0x00-0x7F)
• isLatin1 / isNotLatin1 - Latin-1 range (0x00-0xFF)
• isBmp / isNotBmp - Basic Multilingual Plane (0x0000-0xFFFF)
• isPrintableAscii / isNotPrintableAscii - Printable ASCII (0x20-0x7E)
• isControl - Control characters
• isWhitespace - Whitespace characters
• isSurrogate / isHighSurrogate / isLowSurrogate - Surrogate code points
• inRange(start, end) / notInRange(start, end) - Custom range
• oneOf(chars) / noneOf(chars) - Character set
• and(...filters) / or(...filters) / not(filter) - Combinators
• all / none - Always true/false

Utility Functions

import {
  getCodePoint, // Get code point of a character
  fromCodePoint, // Create character from code point
  getCharInfo, // Get detailed character information
  toCodePoints, // Convert string to code point array
  fromCodePoints, // Convert code point array to string
  codePointLength, // Get length in code points (not UTF-16)
  toHex, // Convert code point to hex string
  parseHex, // Parse hex string to code point
  isValidUnicode, // Check for unpaired surrogates
  normalizeNFC, // Normalize to NFC
  normalizeNFD, // Normalize to NFD
  unicodeEquals, // Compare Unicode equivalence
} from "unicode-escaper";

// Get code point
getCodePoint("😀"); // => 128512 (0x1F600)

// Character info
getCharInfo("😀");
// => {
//   char: '😀',
//   codePoint: 128512,
//   hex: '1F600',
//   isAscii: false,
//   isBmp: false,
//   isLatin1: false,
//   isHighSurrogate: false,
//   isLowSurrogate: false,
//   utf16Length: 2
// }

// Code point length (differs from string.length for emoji)
"😀".length; // => 2 (UTF-16 code units)
codePointLength("😀"); // => 1 (actual characters)

// Parse various formats
parseHex("U+1F600"); // => 128512
parseHex("0x4E16"); // => 19990
parseHex("\\u{4E16}"); // => 19990

Streaming Support

Process large files efficiently without loading everything into memory:

Node.js Streams

import { createReadStream, createWriteStream } from "fs";
import { pipeline } from "stream/promises";
import { EscapeStream, UnescapeStream } from "unicode-escaper";

// Escape a file
await pipeline(
  createReadStream("input.txt", "utf8"),
  new EscapeStream({ escapeOptions: { format: "unicode-es6" } }),
  createWriteStream("escaped.txt")
);

// Unescape a file
await pipeline(
  createReadStream("escaped.txt", "utf8"),
  new UnescapeStream(),
  createWriteStream("output.txt")
);

Web Streams API

import {
  createWebEscapeStream,
  createWebUnescapeStream,
} from "unicode-escaper";

// Works in browsers and modern Node.js
const response = await fetch("data.txt");
const escaped = response.body
  .pipeThrough(new TextDecoderStream())
  .pipeThrough(createWebEscapeStream({ format: "html-hex" }))
  .pipeThrough(new TextEncoderStream());

Detection Utilities

import { hasEscapeSequences, countEscapeSequences } from "unicode-escaper";

hasEscapeSequences("\\u4E16"); // => true
hasEscapeSequences("Hello"); // => false

countEscapeSequences("\\u4E16\\u754C"); // => 2

// Filter by format
hasEscapeSequences("\\u4E16", ["unicode"]); // => true
hasEscapeSequences("\\u4E16", ["html-hex"]); // => false

TypeScript Support

Full TypeScript support with strict types:

import type {
  EscapeFormat,
  EscapeOptions,
  UnescapeOptions,
  FilterFunction,
  CharacterInfo,
  EscapeResult,
} from "unicode-escaper";

// Type-safe options
const options: EscapeOptions = {
  format: "unicode-es6",
  preserveAscii: true,
  uppercase: true,
};

// Custom filter with proper typing
const myFilter: FilterFunction = (char, codePoint) => {
  return codePoint > 0x7f;
};

Comparison with escape-unicode

Feature	escape-unicode	unicode-escaper
Escape formats	\uXXXX only	6 formats
Unescape	Separate package	Built-in
Streaming	No	Yes
Web Streams	No	Yes
ESM + CJS	CJS only	Both
Browser support	Node only	Both
TypeScript	Yes	Yes (strict)
Zero deps	Yes	Yes

International Language Support

Fully tested with diverse Unicode scripts:

Language	Script	Example	Escaped
Korean	Hangul	안녕하세요	\uC548\uB155\uD558\uC138\uC694
Japanese	Hiragana/Katakana/Kanji	こんにちは	\u3053\u3093\u306B\u3061\u306F
Arabic	Arabic	مرحبا	\u0645\u0631\u062D\u0628\u0627
Thai	Thai	สวัสดี	\u0E2A\u0E27\u0E31\u0E2A\u0E14\u0E35
Russian	Cyrillic	Привет	\u041F\u0440\u0438\u0432\u0435\u0442
Hindi	Devanagari	नमस्ते	\u0928\u092E\u0938\u094D\u0924\u0947
Chinese	Han	你好	\u4F60\u597D
Vietnamese	Latin Extended	Xin chào	Xin ch\u00E0o
French	Latin Extended	Café	Caf\u00E9
Turkish	Latin Extended	Türkçe	T\u00FCrk\u00E7e
Spanish	Latin Extended	¡Hola!	\u00A1Hola!
Portuguese	Latin Extended	São Paulo	S\u00E3o Paulo

import { escape, unescape } from "unicode-escaper";

// Korean
escape("안녕하세요"); // => '\uC548\uB155\uD558\uC138\uC694'

// Japanese (mixed scripts)
escape("東京 とうきょう トウキョウ");

// Arabic (RTL)
escape("مرحبا"); // => '\u0645\u0631\u062D\u0628\u0627'

// Thai (with tone marks)
escape("สวัสดี");

// Russian
escape("Привет"); // => '\u041F\u0440\u0438\u0432\u0435\u0442'

// Hindi (with combining marks)
escape("नमस्ते"); // => '\u0928\u092E\u0938\u094D\u0924\u0947'

// Chinese
escape("你好世界"); // => '\u4F60\u597D\u4E16\u754C'

// Vietnamese (with diacritics)
escape("Xin chào"); // => 'Xin ch\u00E0o'

// Turkish (special i variants)
escape("İstanbul"); // => '\u0130stanbul'

// Spanish (inverted punctuation)
escape("¡Hola!"); // => '\u00A1Hola!'

// Portuguese (tildes and cedilla)
escape("São Paulo"); // => 'S\u00E3o Paulo'

// Mixed multi-language content
const mixed = "Hello 안녕 こんにちは 你好 مرحبا สวัสดี Привет नमस्ते";
unescape(escape(mixed)) === mixed; // => true

Supported Features

• Combining characters: Thai tone marks, Arabic diacritics, Hindi matras/virama, Vietnamese diacritics
• Bidirectional text: RTL markers, mixed LTR/RTL content
• Native numerals: Thai ๒๐๒๔, Arabic ٢٠٢٤, Devanagari २०२४
• Conjunct consonants: Hindi samyuktakshar (क्ष, त्र, ज्ञ)
• Supplementary planes: Emoji, ancient scripts, mathematical symbols
• Normalization: Handles NFC/NFD forms correctly
• Extended Latin: French accents, Turkish special i (ı İ), Spanish ñ, Portuguese ã/õ

Browser Support

Works in all modern browsers that support ES2022. For older browsers, you may need polyfills for:

• String.prototype.codePointAt
• String.fromCodePoint
• Web Streams API (if using streaming)

License

Apache-2.0