Performance and Benchmarks

Relevant source files

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

• readme.md
• scripts/benchmark.ts
• src/decode.ts
• src/escape.ts
• scripts/trie/README.md
• scripts/write-decode-map.ts
• package.json

Introduction

The entities library is designed as a high-performance solution for encoding and decoding XML and HTML entities. As of September 2025, it is positioned as the fastest library for decoding HTML entities, outperforming alternatives like html-entities, he, and parse-entities. The performance is achieved through highly optimized data structures, such as radix trees (tries) mapped to typed arrays, and efficient scanning paths that utilize both bitsets and regular expressions to bypass clean spans of text.

Sources: readme.md:9-11, readme.md:85-88, scripts/trie/README.md:1-12

Benchmarking Architecture

The project utilizes tinybench to conduct performance measurements. The benchmarks compare entities against other popular libraries across three primary categories: Escaping, Encoding, and Decoding.

Benchmark Components

The benchmarking suite is defined in scripts/benchmark.ts and categorized into specific tasks:

• Escaping: Compares entities.escapeUTF8 against he.escape and html-entities (special characters mode).
• Encoding: Compares entities.encodeHTML against he.encode and html-entities (non-ASCII printable mode).
• Decoding: Compares entities.decodeHTML against he.decode, parse-entities, and html-entities.

Sources: scripts/benchmark.ts:16-60, package.json:69

Execution Flow

The following diagram illustrates the benchmarking process for a single category:

The benchmark script uses a 1-second warmup and a 10-second execution time to ensure statistical relevance.
Sources: scripts/benchmark.ts:85-93

Performance Results (Node v24.6.0)

The following tables summarize the benchmark results conducted on Apple M2 hardware.

Decoding Performance

Library	Version	ops/s	avg (μs)	slower
entities	7.0.0	5,838,416	175.57	—
html-entities	2.6.0	2,919,637	347.77	50.0%
he	1.2.0	2,318,438	446.48	60.3%
parse-entities	4.0.2	852,855	1,199.51	85.4%

Sources: readme.md:28-34

Encoding Performance

Library	Version	ops/s	avg (μs)	slower
entities	7.0.0	2,770,115	368.09	—
html-entities	2.6.0	1,491,963	679.96	46.2%
he	1.2.0	481,278	2,118.25	82.6%

Sources: readme.md:38-43

Technical Optimizations

The library's performance is not accidental; it is the result of specific architectural choices regarding data storage and string traversal.

Optimized Decode Tries

To minimize memory consumption and maximize traversal speed, entities maps its radix tree to a Uint16Array. This avoids the overhead of JavaScript objects for each trie node. The nodes use a bit-packed layout to store value lengths, flags (like semicolon requirements), and branch offsets.

Compact Runs:* Chains of single-child nodes are collapsed into "compact runs" to reduce pointer chasing.

• Dictionary Encoding: Frequently used values in the trie are encoded via a dictionary to save space.

Sources: scripts/trie/README.md:21-45, scripts/trie/README.md:95-103, scripts/write-decode-map.ts:28-48

Scan Path Consistency

For escaping and encoding, the library uses a two-stage approach:

1. Inline Scan: A short window (e.g., 32 characters) is checked using bitsets (XML_BITSET_VALUE) to identify escapable characters.
2. Regex Fallback: If the inline window is clean, a module-level global regular expression (xmlEncodeRegex) is used to skip large "clean" spans of text using native code performance.

Sources: src/escape.ts:32-75

Resource Footprint

entities is designed to be lightweight. It supports tree shaking, though developers are encouraged to use specific functions (like escapeUTF8 or decodeHTML) rather than the top-level encode/decode wrappers to minimize bundle size. The library has no runtime dependencies and performs no I/O, ensuring deterministic performance profiles.

Sources: readme.md:88-91, SECURITY.md:14-17

Summary

The entities project prioritizes execution speed and memory efficiency through the use of typed arrays and optimized trie traversals. Benchmarks consistently show entities as a leader in the Node.js ecosystem for HTML/XML entity processing, with decoding speeds reaching over 5.8 million operations per second on modern hardware.

Sources: readme.md:28-34, scripts/trie/README.md:10-12