Benchmarking Tool
Relevant source files
The following files were used as context for generating this wiki page:
The Benchmarking Tool is a performance analysis suite designed to measure the efficiency of the entities library against other popular HTML and XML entity processing libraries. Its primary purpose is to validate the library's claim of being the fastest for decoding and encoding tasks, providing high-precision metrics such as operations per second (ops/s) and average execution time in microseconds (μs).
Sources: scripts/benchmark.ts:1-12, readme.md:14-16
Architecture and Execution
The tool is implemented as a standalone TypeScript script that utilizes the tinybench library for high-resolution timing and statistical analysis. It operates by defining specific categories of tasks (Escaping, Encoding, Decoding) and running them across multiple competing implementations in a controlled environment.
Core Components
- Benchmark Runner (
runCategory): Initializes aBenchinstance with defined warmup and execution times. It iterates through provided tasks, adding them to the benchmark suite before asynchronous execution. - Competitor Registry: A collection of arrays (e.g.,
encoders,decoders,escapers) that map library names to their respective function calls. - Result Formatting (
printResults): Utilizingconsole.tableto output statistical data in a readable format once a category run is complete.
Sources: scripts/benchmark.ts:79-106
Execution Flow
The following diagram illustrates the lifecycle of a benchmark execution for a single category:
This flow describes the logic within the runCategory and printResults functions.
Sources: scripts/benchmark.ts:79-106
Comparison Targets
The tool benchmarks the entities library against several industry-standard alternatives to ensure comprehensive performance comparisons.
| Category | Library | Method/Options |
|---|---|---|
| Encoding | entities | encodeHTML |
he | he.encode (named references) | |
html-entities | html5 level, nonAsciiPrintable mode | |
| Decoding | entities | decodeHTML |
he | he.decode | |
parse-entities | parseEntities | |
html-entities | html5 level, body scope | |
| Escaping | entities | escapeUTF8 |
he | he.escape | |
html-entities | xml level, specialChars mode |
Sources: scripts/benchmark.ts:13-64
Performance Metrics and Reporting
The tool produces a detailed statistical breakdown for each library. The readme.md highlights typical results obtained using the tool (Node v24.6.0 on Apple M2), demonstrating the library's performance lead.
Key Metrics
- ops/s: Total operations performed per second.
- avg (μs): The mean time taken for a single operation.
- ±%: The margin of error in the measurements.
- slower: Percentage comparison relative to the fastest implementation.
Sources: readme.md:21-48, scripts/benchmark.ts:79-82
The sequence of interactions between the benchmark script, the timing engine, and the libraries being tested.
Sources: scripts/benchmark.ts:86-106
Integration and Usage
The tool is integrated into the project's development workflow via npm scripts. It is configured to run using tsx to handle TypeScript execution directly in Node.js.
Command Execution
To run the full suite of benchmarks:
npm run benchmark
This maps to the command: node --import=tsx scripts/benchmark.ts.
Sources: package.json:52, readme.md:21-23
Summary
The Benchmarking Tool serves as a critical validation component for the entities project. By leveraging tinybench and comparing against established libraries like he, html-entities, and parse-entities, it provides empirical data to support the project's focus on speed and efficiency in XML/HTML entity processing.
Sources: scripts/benchmark.ts:1-12, readme.md:58-62