Configuration Options

Relevant source files

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

• src/index.ts
• src/decode.ts
• src/encode.ts
• src/escape.ts
• src/index.spec.ts
• readme.md

The entities library provides a highly configurable interface for encoding and decoding HTML and XML entities. The primary configuration mechanism revolves around two main enums—EntityLevel and EncodingMode—and a set of option interfaces that control how characters are transformed, which entity sets are recognized, and how strict the parser should be regarding specification compliance.

Users can interface with these options through high-level encode and decode functions, or via specialized functions for specific environments (e.g., attributes vs. text nodes). The configuration architecture is designed to balance performance, transportability, and specification adherence, such as supporting legacy HTML behavior while maintaining strict XML requirements.

Sources: src/index.ts:1-125, readme.md:12-20

Entity Levels

The EntityLevel configuration defines the scope of recognized named entities. This is the most fundamental setting, determining whether the system operates within the narrow constraints of XML or the broader requirements of HTML.

Level	Value	Description
XML	0	Supports only the five basic XML entities: ", &, ', <, and >.
HTML	1	Supports the full set of HTML5 entities, which is a superset of XML entities.

Sources: src/index.ts:10-16, src/decode.ts:880-975

Level Logic Flow

When calling the generic encode or decode functions, the EntityLevel dictates which internal trie or fast-path logic is utilized.

Decoding Configuration

Decoding behavior is managed via the DecodingOptions interface. This allows developers to toggle between strict compliance and "legacy" mode, which handles common web patterns like missing semicolons.

Decoding Modes

The DecodingMode enum determines how the parser treats named and numeric entities, especially regarding their termination.

Mode	Description
Legacy	Supports named entities not terminated with a semicolon (;). Standard for HTML text nodes.
Strict	Only allows entities that are properly terminated with a semicolon. Mandatory for XML.
Attribute	Applies specific HTML specification rules for entities inside attributes, ignoring potential matches followed by =, alphanumeric characters, or digits to prevent incorrect parsing.

Sources: src/decode.ts:94-106, src/index.ts:46-59

Error Handling Configuration

The EntityDecoder class can accept an optional EntityErrorProducer. This allows consumers to hook into the decoding process to receive notifications about specification violations, such as missing semicolons or invalid numeric references.

Encoding Configuration

Encoding is configured via the EncodingOptions interface, which primarily leverages the EncodingMode enum to define the output strategy.

Encoding Modes

The EncodingMode provides granular control over which characters are escaped and how they are represented (named vs. numeric).

Mode	Description	Relevant Function
UTF8	Only escapes characters necessary for XML/HTML structure.	escapeUTF8
ASCII	Ensures output contains only ASCII characters; non-ASCII are converted to numeric entities.	encodeNonAsciiHTML / encodeXML
Extensive	Encodes all characters that have an equivalent named entity.	encodeHTML / encodeXML
Attribute	Follows WHATWG rules for escaping strings in HTML attributes.	escapeAttribute
Text	Follows WHATWG rules for escaping strings in HTML text nodes.	escapeText

Sources: src/index.ts:21-41, src/index.ts:106-125, src/escape.ts:190-216

Internal Scanning Logic

The encoding configuration also influences the internal scanning strategy. The library uses a hybrid approach: an inline bitset scan for short windows and a RegExp fallback for long clean spans.

Configuration Data Structures

The configuration settings eventually map to specific binary tries and bitsets used for high-performance processing.

XML Bitset Definition

The XML bitset is a constant used to identify characters that must be escaped in XML contexts (codepoints 34, 38, 39, 60, and 62).

// src/escape.ts:24
export const XML_BITSET_VALUE = 0x50_00_00_c4; // 32..63 -> 34 ("),38 (&),39 ('),60 (<),62 (>)

Sources: src/escape.ts:24, src/encode.ts:172

HTML Encoding Bitset

For HTML, a Uint32Array covers the ASCII range to identify characters requiring encoding based on the selected mode.

// src/encode.ts:161-166
const HTML_BITSET = /* #__PURE__ */ new Uint32Array([
    0x16_00, // 09 (\t), 0A (\n), 0C (\f)
    0xfc_00_ff_fe, // 21-2D (!-.), 2E (.), 2F (/), 3A-3F (:;<=>?)
    0xf8_00_00_01, // 40 (@), 5B-5F ([\]^_)
    0x38_00_00_01, // 60 (`), 7B-7D ({|})
]);

Sources: src/encode.ts:161-166

Summary of Configuration Interaction

The configuration options provide a layered approach to entity processing. By selecting an EntityLevel, users define the vocabulary. By selecting a Mode (either DecodingMode or EncodingMode), users define the grammar and strictness. This architecture allows the library to serve as both a high-speed utility for standard web development and a compliant tool for strict XML processing.

Sources: src/index.ts:1-125, readme.md:65-75