Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• readme.md
• package.json
• src/index.ts
• src/decode.ts
• src/escape.ts
• scripts/trie/README.md

The entities library provides a high-performance solution for encoding and decoding XML and HTML entities. It is designed to be fast, configurable, and tree-shakable, making it suitable for both server-side Node.js environments and browser-based applications. The library is used internally by popular tools such as htmlparser2, the AWS SDK, and cheerio.

At its core, the library utilizes an optimized array-mapped trie structure (radix tree) to handle named character references, ensuring low memory consumption (~250Kb) and high traversal speed. It supports multiple levels of entity complexity, ranging from basic XML specials to the full suite of HTML5 named entities, including support for astral code points and surrogate pairs.

Sources: readme.md:1-20, package.json:2-10, scripts/trie/README.md:1-15

Installation and Basic Usage

To include entities in your project, install it via npm. The package provides ES module exports for its primary functionalities.

npm install entities

Sources: readme.md:24-26, package.json:22-38

Quick Start Example

The following snippet demonstrates the standard entry points for encoding and decoding:

import * as entities from "entities";

// Encoding example
const escaped = entities.escapeUTF8("& ü"); // "& ü"
const encodedXml = entities.encodeXML("& ü"); // "& ü"

// Decoding example
const decodedHtml = entities.decodeHTML("asdf & ÿ ü '"); // "asdf & ÿ ü '"

Sources: readme.md:30-41

Core API Structure

The library is organized into three main modules: encode, decode, and escape. While the top-level encode and decode functions provide a convenient interface, direct use of specialized functions (e.g., decodeHTML) is recommended for better tree-shaking results.

Configuration Options

The library uses enums and interfaces to define processing behavior across different entity levels and encoding strategies.

Option	Type	Description
level	EntityLevel	Choose between XML (0) or HTML (1).
mode (Decoding)	DecodingMode	Legacy (allow missing ;), Strict (require ;), or Attribute.
mode (Encoding)	EncodingMode	UTF8, ASCII, Extensive, Attribute, or Text.

Sources: src/index.ts:10-70, src/decode.ts:67-75

Architectural Flow

The following diagram illustrates how the general encode and decode wrappers delegate to specialized internal logic based on user options:

Decoding Mechanics

Decoding is handled through a trie-based state machine. The library supports a Streaming mode via the EntityDecoder class, which allows processing partial entity strings as they arrive.

Decoding Modes

Decoding behavior changes significantly depending on the target context:

1. Legacy: Supports HTML entities that may not be terminated by a semicolon (e.g., &amp becomes &).
2. Strict: Requires a semicolon for a valid match. This is mandatory for XML.
3. Attribute: Follows specific WHATWG rules where entities in attributes are rejected if they are not properly terminated and are followed by alphanumeric characters or =.

Sources: src/decode.ts:67-76, src/decode.ts:503-518

The EntityDecoder State Machine

The EntityDecoder class maintains internal state to handle multi-chunk inputs.

Encoding and Escaping

The library provides several ways to prepare text for XML/HTML consumption:

• Escaping: Only replaces characters that are dangerous in the specific context (e.g., < to <).
  • escapeUTF8: Minimal escaping (5 XML specials) while keeping UTF-8 characters intact.
  • escapeAttribute: Specifically escapes characters dangerous in HTML attributes (", &, \u00A0).
  • escapeText: Specifically escapes characters dangerous in HTML text nodes (&, <, >, \u00A0).
• Encoding: A more aggressive approach that converts non-ASCII characters into numeric entities (e.g., ü to ü).

Sources: src/escape.ts:98-175, src/index.ts:40-61

Performance Optimization: The Hybrid Scan

The encoding process uses a "Hybrid Scan" to achieve high speeds. It first performs a fast inline scan of a 32-character window for escapable characters using a bitset. If no specials are found, it utilizes a native RegExp jump to skip clean spans of text.

Performance Summary

Benchmarking indicates that entities is significantly faster than alternative libraries like he or html-entities. As of late 2025, the library leads in operations per second for decoding, encoding, and escaping.

Operation	entities (ops/s)	Comparison (Avg μs)
Decoding	~5,838,416	175.57 μs
Encoding	~2,770,115	368.09 μs
Escaping	~4,616,468	223.84 μs

Sources: readme.md:43-70