html-entities

html-entities is a small, dependency-free TypeScript library that encodes and decodes HTML entities across the HTML5, HTML4, and XML standards. It exposes a handful of pure functions — encode, decode, and decodeEntity — built around precomputed named-reference tables and regex-based scanners, so there’s no DOM or parser dependency to pull in just to escape or unescape text.

The library is explicitly built for speed and small footprint: it ships its own benchmark suite comparing directly against the two most common alternatives, he and entities, and documents package-size comparisons in its README. It ships as dual ESM/CJS builds via tshy, with full TypeScript types and generated Flow types for legacy typed codebases.

Because entity handling has real security implications (output encoding is a standard XSS mitigation), the library gives fine-grained control over exactly which character ranges get escaped — from HTML’s four special characters up to full non-ASCII and non-printable coverage — plus a choice between decimal and hexadecimal numeric references, and a decode scope that mirrors how browsers parse entities differently inside tag bodies versus attributes.

What You Get

• encode() for escaping special characters, non-ASCII characters, or the full extensive set, with configurable HTML5/HTML4/XML entity levels
• decode() for unescaping named and numeric entities, with a scope option that emulates browser parsing rules for tag bodies vs. attributes
• decodeEntity() for decoding a single entity string in isolation
• Zero runtime dependencies — the package.json test suite explicitly asserts this stays true
• Dual ESM and CommonJS builds published from one TypeScript source via tshy, plus generated Flow type definitions
• Support for decimal or hexadecimal numeric character references on encode

Common Use Cases

• Escaping user-submitted text before rendering it into HTML templates to prevent injection
• Decoding entity-encoded content pulled from scraped web pages, RSS/Atom feeds, or CMS exports
• Normalizing HTML4/XML entity differences when processing content from mixed legacy sources
• Server-side rendering pipelines that need fast, allocation-light encode/decode without a full HTML parser

Under The Hood

Architecture The library is a flat functional core rather than a layered system: src/index.ts composes lookup tables from named-references.ts (precomputed HTML5/HTML4/XML entity maps), numeric-unicode-map.ts (legacy numeric character-reference remapping), and surrogate-pairs.ts (UTF-16 surrogate-pair handling for codepoints outside the BMP). encode() and decode() dispatch through mode/level/scope-keyed regex tables (encodeRegExps, decodeRegExps) into a shared getDecodedEntity() helper, so all three decode scopes (strict/body/attribute) stay consistent by construction. There is no class hierarchy, no global mutable state, and no I/O — every function is pure, which keeps the surface easy to reason about but means any change to the core scanning strategy (e.g. moving off regex to a stateful tokenizer) would need to preserve behavior across all scope/level combinations simultaneously.

Tech Stack Written in TypeScript 5.8 with zero runtime dependencies, verified by an explicit test assertion against package.json. Builds are produced via tshy, publishing matching ESM and CommonJS output from a single source tree, with Flow type definitions generated afterward via flowgen for legacy typed-JS consumers. Tests run under Jest with ts-jest, and the repo maintains its own benchmark.js suite that compares directly against the two closest competing packages, he and entities, tracked in the README’s performance tables.

Code Quality The test suite spans unit coverage of encode/decode/decodeEntity plus integration checks that exercise the built ESM, CommonJS, and TypeScript-consumer output under test/test-apps/, run through test:dist:commonjs and test:dist:esm scripts. A Husky pre-commit hook enforces lint && test before any commit, and commitlint enforces Conventional Commits. ESLint with typescript-eslint and Prettier keep style consistent. Exported types (Level, EncodeMode, DecodeOptions, etc.) give callers full compile-time safety over the option surface.

API Design The public API is deliberately small: three functions (encode, decode, decodeEntity) cover the entire feature set, each with sensible defaults (level: 'all', mode: 'specialChars') so a caller can start with a single-argument call and opt into finer control only when needed. The README documents every option as a table with concrete before/after examples, and the dual-package exports map means consumers get correct types and module resolution automatically regardless of whether they’re on ESM or CommonJS.