Frequently Asked Questions (FAQ)

The entities library provides a high-performance solution for encoding and decoding HTML and XML character entities. This FAQ serves as a technical guide for developers to understand the architectural choices, performance characteristics, and security model of the library. It covers common usage patterns, configuration options, and the underlying data structures used to achieve its industry-leading speed.

Sources: readme.md:1-15, SECURITY.md:19-25

General Usage and Configuration

What methods should I use to encode my documents?

For documents targeting UTF-8, escapeUTF8 is the recommended choice as it is the most efficient. If the target environment requires strictly ASCII output or specific document compliance, use encodeHTML or encodeXML accordingly. The library also provides a generic encode function that accepts EncodingOptions to fine-tune the output.

Sources: readme.md:73-80, src/index.ts:107-133

When should I use strict decoding?

Strict decoding should be used when you want to ignore entities that are not terminated with a semicolon (;). This is particularly useful for avoiding ambiguity in legacy environments or when adhering strictly to XML standards. In contrast, Legacy mode supports non-semicolon terminated entities, which is common in older HTML content.

Sources: readme.md:82-84, src/decode.ts:84-90

Does the library support tree shaking?

Yes. The library is designed to be tree-shakeable. To achieve the best bundle size, developers should import specific functions (e.g., decodeHTMLStrict, escapeUTF8) directly rather than using the wrapper encode and decode functions, which may pull in unnecessary logic for different levels and modes.

Sources: readme.md:94-98, src/index.ts:135-154

Architecture and Performance

Why is entities faster than other modules?

The library utilizes a highly optimized Uint16Array trie (radix tree) structure for decoding. This structure reduces memory consumption (from ~8.5Mb to ~250Kb compared to object-based tries) while maintaining extremely fast traversal speeds. The trie includes optimizations such as "compact runs" to collapse linear paths and "jump tables" for dense character ranges.

Sources: readme.md:86-92, scripts/trie/README.md:1-20

How is the trie traversed during decoding?

The EntityDecoder class implements a state machine that navigates the trie based on input characters. It handles numeric entities (decimal and hexadecimal) and named entities through distinct states.

The diagram shows the internal state transitions within the EntityDecoder when processing an entity.
Sources: src/decode.ts:114-165

Component Summary

Sources: src/decode.ts:98-106, src/decode.ts:503-514, src/escape.ts:43-50

Security and Compliance

What is the threat model for entities?

The library is a pure-JavaScript implementation with no I/O or subprocesses. It treats input strings as untrusted. Security concerns focus on preventing Denial of Service (DoS) via crafted inputs and ensuring that incorrect decoding does not enable downstream Cross-Site Scripting (XSS) by misrepresenting markup.

Sources: SECURITY.md:19-33

How are character reference errors handled?

The library allows for custom error production through the EntityErrorProducer interface. This enables consumers to hook into specific HTML spec violations, such as missing semicolons or the absence of digits in numeric references.

The relationship between the decoder and the error handling interface defined in the source.
Sources: src/decode.ts:91-106, src/decode.ts:143-152

Configuration Options

Sources: src/index.ts:10-54, src/index.ts:74-95

The entities library prioritizes accuracy and speed by utilizing a sophisticated radix tree implementation and offering granular control over encoding and decoding behaviors to meet both legacy and modern web standards.

Sources: readme.md:9-15, scripts/trie/README.md:100-110