Escaping API

Relevant source files

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

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

The Escaping API provides high-performance utility functions for converting special characters and non-ASCII characters into their corresponding XML or HTML entity representations. Its primary purpose is to ensure that data can be safely embedded within XML/HTML text nodes or attributes without breaking the document structure or introducing security vulnerabilities like XSS.

The API is highly configurable, offering specialized methods for UTF-8 environments, HTML attributes, and full XML compliance. It utilizes a hybrid optimization strategy combining manual bitset checks for performance in dense markup and regex-based jumps for long spans of clean text.

Sources: src/escape.ts:1-177, readme.md:1-40

Core Escaping Logic

The library implements two primary internal strategies for escaping characters: a specialized scan-and-replace loop for XML/Non-ASCII characters and a regex-driven dispatch for specific HTML contexts.

Optimized XML Encoding

The encodeXML function (aliased as escape) is the foundation for XML-compliant escaping. It handles the five standard XML entities (", &, ', <, >) and converts all non-ASCII characters into numeric decimal references (e.g., ü).

The diagram illustrates the hybrid scanning approach where characters are checked against a bitset (XML_BITSET_VALUE) before falling back to xmlEncodeRegex.
Sources: src/escape.ts:60-112, src/escape.spec.ts:35-50

Shared Regex Dispatch

For simpler HTML-specific tasks, the API uses escapeWithRegex. This internal helper resets the lastIndex of a provided global regex and performs a search-and-replace using a high-performance switch to map code units to entities.

Sources: src/escape.ts:127-154, src/escape.spec.ts:101-125

Primary API Methods

The API exposes several specialized functions tailored to specific document contexts and transport requirements.

Function	Scope	Escaped Characters
escapeUTF8	General XML/HTML	", &, ', <, >
escapeAttribute	HTML Attributes	", &, \u00A0 (Non-breaking space)
escapeText	HTML Text Nodes	&, <, >, \u00A0
encodeXML	Strict XML	XML Specials + all non-ASCII (e.g., emojis, accented chars)

Context-Specific HTML Escaping

escapeAttribute and escapeText follow the WHATWG HTML Specification for escaping strings. Notably, they handle the non-breaking space (\u{A0}) as  .

Sources: src/escape.ts:156-177, src/escape.spec.ts:5-15

Optimization Techniques

The Escaping API is architected for maximum throughput by minimizing allocations and leveraging native engine optimizations.

Bitset and Regex Synchronization

The API uses a bitset (XML_BITSET_VALUE) to identify escapable ASCII characters (indices 32-63). This is kept in sync with xmlEncodeRegex.

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

// src/escape.ts:40-46
function isXmlEscapable(code: number): boolean {
    return (
        code >= 0x80 ||
        (code >= 32 && code < 64 && ((XML_BITSET_VALUE >>> code) & 1) === 1)
    );
}

Sources: src/escape.ts:20-46, src/encode.ts:245-260

Multi-Path Scanning

To optimize for different input types:

1. Dense Markup: A 32-character inline window scans code units using the bitset. This avoids regex overhead when matches are frequent.
2. Clean Text: If the window finds no matches, it uses xmlEncodeRegex.exec() to skip large blocks of text in native code.
3. Surrogate Handling: Non-ASCII characters are processed using codePointAt to correctly identify astral plane characters (e.g., emojis) even when split across UTF-16 surrogate pairs.

Sources: src/escape.ts:74-95, src/escape.spec.ts:66-75

Usage with Configuration

The library provides a unified encode entry point that allows developers to select escaping modes via an EncodingOptions object.

Encoding Modes Summary

• EncodingMode.UTF8: Minimal escaping for UTF-8 compatible systems.
• EncodingMode.ASCII: Forces all non-ASCII characters to numeric entities.
• EncodingMode.Attribute: Strict HTML attribute escaping.
• EncodingMode.Text: Standard HTML text node escaping.

Sources: src/index.ts:20-49, src/index.spec.ts:58-69

Conclusion

The Escaping API is a critical component of the entities library, providing the necessary tools to sanitize data for web and XML environments. By combining context-aware methods with low-level bitwise and regex optimizations, it achieves high performance while strictly adhering to XML and HTML standards.

Sources: readme.md:43-65, SECURITY.md:21-31