Tree Shaking and Modular Imports

Relevant source files

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

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

Tree shaking is a critical optimization feature of the entities library, designed to minimize bundle sizes by allowing modern bundlers to remove unused code. The project is structured as a native ES module (type: "module"), ensuring compatibility with modern build pipelines that support dead-code elimination. Sources: package.json:28, readme.md:105-110

To achieve optimal results, users are encouraged to import specific functions directly rather than using the primary encode and decode wrappers. These wrappers reference multiple internal utilities, which can prevent the bundler from stripping out unused logic. Sources: readme.md:107-110

Package Architecture for Tree Shaking

The library facilitates tree shaking through two primary mechanisms: the use of distinct entry points via the exports field in package.json and a strictly modular internal file structure. The project explicitly declares sideEffects: false, signaling to bundlers that any module in the package can be safely removed if its exports are not used. Sources: package.json:27-41

Entry Points and Subpath Exports

The library exposes specialized subpaths that allow consumers to import only the logic they need (e.g., only decoding or only escaping).

Export Subpath	Type Definition	Runtime Implementation	Description
.	./dist/index.d.ts	./dist/index.js	Main entry point containing all features.
./decode	./dist/decode.d.ts	./dist/decode.js	Focused entry for entity decoding.
./escape	./dist/escape.d.ts	./dist/escape.js	Focused entry for basic escaping.

Sources: package.json:29-41

Module Dependency Flow

The following diagram illustrates how direct imports bypass the heavy wrapper logic in the main index file, enabling better tree shaking.

This flow shows that importing from the decode subpath directly targets src/decode.ts, avoiding the overhead of the encode wrappers found in the main index. Sources: src/index.ts, readme.md:107-110

Optimization Techniques

The library employs several internal strategies to maintain a small footprint while providing high-performance entity processing.

Data-Driven Code Generation

Large datasets like the HTML entity trie are not stored as large JSON objects, which are inefficient for tree shaking and memory. Instead, they are pre-processed into Uint16Array formats. The scripts/write-decode-map.ts utility generates these arrays, using the /* #__PURE__ */ annotation to ensure that the creation of these arrays can be tree-shaken if the specific tree is not referenced. Sources: scripts/write-decode-map.ts:192-211

Fast Path vs. Trie Dispatch

For common operations like decodeXML, the library implements hand-coded fast paths to avoid loading the larger trie-based decoding logic required for HTML5.

• XML Decoding: Uses a targeted switch/if-else logic for the five core XML entities (&, <, >, ", '). Sources: src/decode.ts:634-697
• HTML Decoding: Utilizes a complex binary trie (htmlDecodeTree) generated during the build process. Sources: src/decode.ts:599-608

Regex and Bitset Scans

For escaping operations in src/escape.ts, the library uses a combination of inline window scans (checking 32 characters at a time) and specialized regexes (xmlEncodeRegex). This modularity allows the escape functions to remain lightweight compared to the full encode logic. Sources: src/escape.ts:46-95

Usage Recommendations

Strategy	Recommended Action	Result
Optimal	import { decodeHTML } from "entities/decode";	Smallest bundle; only HTML decoding logic included.
Balanced	import { decodeXML } from "entities";	Includes XML fast-path; HTML trie may be shaken out.
Sub-optimal	import { decode } from "entities";	Prevents tree shaking; includes both XML and HTML logic.

Sources: readme.md:105-115, src/index.ts

Summary

The entities library is architected for maximum efficiency in modern web development. By leveraging native ES modules, subpath exports, and /* #__PURE__ */ annotations, it allows developers to include only the necessary logic for their specific use case, significantly reducing the final application bundle size when only basic escaping or specific entity sets are required.