Repository Structure

Relevant source files

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

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

The entities repository is a high-performance TypeScript library designed for encoding and decoding HTML and XML entities. The architecture leverages pre-generated binary tries (radix trees) to achieve significant speed improvements and reduced memory footprint compared to traditional object-based trie implementations. The project is structured as a modern Node.js module supporting tree shaking and multiple export entry points.

Sources: package.json:1-40, readme.md:1-25, scripts/trie/README.md:1-15

Project Layout and Module Exports

The repository follows a standard TypeScript project structure with source files in src/ and build artifacts directed to dist/. It utilizes a multi-entry point configuration to allow consumers to import specific functionality, which facilitates tree shaking and reduces bundle sizes for specific use cases.

Key Directories and Files

Directory/File	Description
src/	Primary TypeScript source code for decoding, encoding, and escaping logic.
src/generated/	Contains binary trie data generated by build scripts.
scripts/	Tooling for generating trie data, benchmarks, and maintenance tasks.
maps/	JSON definition files for XML and HTML entity mappings used during the build process.
dist/	Compiled JavaScript and type definitions (generated by tsc).

Sources: package.json:23-45, tsconfig.json:8-9, scripts/write-decode-map.ts:250-265

Entry Points

The package exports three primary modules:

• .: The main entry point providing all functionality via index.js.
• ./decode: Specific logic for decoding entities using EntityDecoder.
• ./escape: Functions for escaping characters for XML/HTML text and attributes.

Sources: package.json:28-40

Core Architecture: Trie-Based Processing

The project's performance is derived from its use of a Uint16Array mapped trie. This structure represents named character references as a radix tree collapsed into a single typed array, avoiding the overhead of JavaScript object allocation for every node.

Trie Component Relationships

The diagram shows how static entity maps are transformed into binary data that powers the decoding logic.
Sources: scripts/write-decode-map.ts:1-15, scripts/trie/README.md:20-40, src/decode.ts:1-50

Node Layout in Binary Trie

Every node in the binary trie is represented by a 16-bit header word that defines its value length, flags, and branching information.

Bits	Purpose
15..14	Value length field: Encoded length of the entity value (0-3).
13	Dual-use flag: Semicolon-required flag (if value) or Compact run flag (if no value).
12..7	Branch data: Length or span of branches.
6..0	Jump table / Char: Offset or first character code.

Sources: scripts/trie/README.md:52-65

Logic Flow: Decoding System

The EntityDecoder class handles the stateful parsing of entities. It supports both full string decoding and streaming inputs, where partial entities can be written across multiple chunks.

Decoding State Machine

This state machine illustrates how the EntityDecoder transitions between numeric and named entity parsing.
Sources: src/decode.ts:60-75, src/decode.ts:130-180

Decoding Modes

The library supports three distinct DecodingMode configurations that alter how the parser handles trailing characters and semicolons:

• Legacy: Allows entities to end without a semicolon (text node behavior).
• Strict: Requires a trailing semicolon for all entities.
• Attribute: Specifically handles entities inside HTML attributes, rejecting legacy matches if followed by =, alpha, or numeric characters to match the WHATWG spec.

Sources: src/decode.ts:79-88, src/decode.ts:255-275

Escaping Implementation

The escaping logic in src/escape.ts uses a hybrid approach to maximize performance. It first scans a 32-character window for escapable ASCII characters (like &, <, >) using a bitset. If no match is found, it falls back to a global regex to skip clean spans of text.

Escaping Flow

The flow shows the optimized path selection used during string escaping.
Sources: src/escape.ts:65-100, src/escape.ts:125-150

Build and Generation Pipeline

The repository includes a robust set of scripts in the scripts/ directory to generate the optimized trie data.

1. Map Parsing: scripts/write-decode-map.ts reads entity maps from maps/*.json.
2. Trie Compression: Logic in scripts/trie/ converts these maps into a compressed radix tree.
3. Data Packing: The scripts use a custom base-91 encoding to store the Uint16Array data as strings within generated .ts files to reduce bundle size and initialization time.
4. Serialization: scripts/write-encode-map.ts generates specialized tries for the encoding path.

Sources: scripts/write-decode-map.ts:20-60, scripts/write-encode-map.ts:40-70, package.json:48-52

Summary

The entities repository is architected for extreme performance, utilizing a binary trie structure to handle complex HTML and XML entity sets. By separating the trie generation into a build-time process and providing specialized, tree-shakable entry points, the project serves as a lightweight yet powerful utility for web-standard compliant entity processing.

Sources: readme.md:10-30, src/decode.ts:90-110