Build System and Tooling

Relevant source files

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

• package.json
• tsconfig.json
• biome.json
• scripts/write-decode-map.ts
• scripts/write-encode-map.ts
• scripts/benchmark.ts
• tsconfig.eslint.json

The build system and tooling of the entities project are designed to provide a highly optimized, high-performance library for encoding and decoding HTML and XML entities. The architecture centers around generating compact, pre-compiled data structures (tries) from source entity maps to ensure minimal memory footprint and maximum execution speed.

The environment utilizes a modern TypeScript stack, employing tsc for compilation, vitest for testing, and biome for linting and formatting. A significant portion of the build process involves custom scripts that transform JSON entity definitions into binary-mapped tries and serialized encoding maps, which are then integrated into the final distribution.

Sources: package.json:1-85, scripts/write-decode-map.ts:1-207

Core Build Orchestration

The project uses standard npm scripts defined in package.json to manage the lifecycle of the application, from data generation to benchmarking.

Primary Build Scripts

Script Name	Command	Description
build	tsc	Compiles TypeScript source files into the dist directory.
build:trie	node --import=tsx scripts/write-decode-map.ts	Generates binary decode trie data from JSON maps.
build:encode-trie	node --import=tsx scripts/write-encode-map.ts	Generates serialized encoding trie data.
benchmark	node --import=tsx scripts/benchmark.ts	Runs performance comparisons against other libraries.
build:docs	typedoc --hideGenerator src/index.ts	Generates technical documentation using TypeDoc.

Sources: package.json:44-59

Build Pipeline Flow

The following diagram illustrates the data flow from source maps to the final compiled JavaScript package.

The build process relies on the tsx loader to execute TypeScript scripts directly during the generation phase.
Sources: package.json:47-49, scripts/write-decode-map.ts:200-207

Data Generation and Trie Compression

A critical component of the build system is the generation of optimized data structures for entity processing. This avoids the overhead of parsing JSON at runtime and reduces memory usage from megabytes to kilobytes.

Decoding Trie Generation

The scripts/write-decode-map.ts utility converts JSON maps into a Uint16Array representing a binary trie. It uses a custom encoding scheme to minimize size:

• Dictionary Encoding: Frequently occurring values are assigned 1-character or 2-character codes based on a safe ASCII base-91 set.
• Delta & RLE Encoding: Differences between values are stored, and consecutive identical deltas are compressed using Run-Length Encoding (RLE).
• Binary Mapping: The final result is a packed Uint16Array that the library traverses directly at runtime.

Sources: scripts/write-decode-map.ts:28-105, scripts/write-decode-map.ts:145-160

Encoding Map Serialization

The scripts/write-encode-map.ts utility builds a trie keyed by full Unicode code points rather than UTF-16 surrogate pairs. This structure is then serialized into a compact string format:

• Format: [gap]name;[{children}]
• Delta Encoding: Stores the gap between code points to reduce string size.
• Surrogate Handling: Astral characters are batch-inserted as surrogate-pair nodes during the hydration phase in the source code.

Sources: scripts/write-encode-map.ts:37-64, src/encode.ts:47-75

Code Quality and Linting

The project uses biome as its primary tool for linting, formatting, and code analysis, supplemented by eslint for TypeScript-specific rules.

Biome Configuration

The biome.json file configures a strict environment focusing on performance and code simplicity. Key rules include:

• Complexity: Errors on useless string concatenations and mandates simplified logic expressions.
• Performance: Mandates the use of top-level regular expressions to avoid repeated compilation.
• Style: Enforces consistent type definitions, array types, and numeric separators.

Sources: biome.json:1-92

TypeScript Configuration

The project utilizes two primary TypeScript configurations:

1. tsconfig.json: Configures the main build targeting es2022 and nodenext modules. It enforces strict type checking and excludes test files from the distribution build.
2. tsconfig.eslint.json: Extends the base config to include scripts in the scope for linting purposes without emitting code.

Sources: tsconfig.json:4-35, tsconfig.eslint.json:1-10

Benchmarking and Performance Validation

The build system includes a benchmarking suite in scripts/benchmark.ts to validate the library's performance claims.

The benchmark measures "Escaping", "Encoding", and "Decoding" operations, comparing entities against competitors like he, html-entities, and parse-entities.
Sources: package.json:45, scripts/benchmark.ts:1-95

Summary

The entities build system is a performance-first infrastructure. By moving complex trie generation and compression into pre-build scripts (write-decode-map.ts and write-encode-map.ts), the library achieves significant speed and size advantages. This is supported by a robust development environment utilizing biome for consistent code quality and tinybench for continuous performance validation.