UNPKG

entities

Version:

Encode & decode XML and HTML entities with ease & speed

github.com/fb55/entities

fb55/entities

132 lines (92 loc) • 5.22 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
# entities [![NPM version](https://img.shields.io/npm/v/entities.svg)](https://npmjs.org/package/entities) [![Downloads](https://img.shields.io/npm/dm/entities.svg)](https://npmjs.org/package/entities) [![Node.js CI](https://github.com/fb55/entities/actions/workflows/nodejs-test.yml/badge.svg)](https://github.com/fb55/entities/actions/workflows/nodejs-test.yml) Encode & decode HTML & XML entities with ease & speed. ## Features - 😇 Tried and true: `entities` is used by many popular libraries; eg. [`htmlparser2`](https://github.com/fb55/htmlparser2), the official [AWS SDK](https://github.com/aws/aws-sdk-js-v3) and [`commonmark`](https://github.com/commonmark/commonmark.js) use it to process HTML entities. - ⚡️ Fast: `entities` is the fastest library for decoding HTML entities (as of September 2025); see [performance](#performance). - 🎛 Configurable: Get an output tailored for your needs. You are fine with UTF8? That'll save you some bytes. Prefer to only have ASCII characters? We can do that as well! ## How to… ### …install `entities` npm install entities ### …use `entities` ```javascript import * as entities from "entities"; // Encoding entities.escapeUTF8("& ü"); // "& ü" entities.encodeXML("& ü"); // "& ü" entities.encodeHTML("& ü"); // "& ü" // Decoding entities.decodeXML("asdf & ÿ ü '"); // "asdf & ÿ ü '" entities.decodeHTML("asdf & ÿ ü '"); // "asdf & ÿ ü '" ``` ## Performance Benchmarked in September 2025 with Node v24.6.0 on Apple M2 using `tinybench`. Higher ops/s is better; `avg (μs)` is the mean time per operation. See `scripts/benchmark.ts` to reproduce. ### Decoding | Library | Version | ops/s | avg (μs) | ±% | slower | | -------------- | ------- | --------- | -------- | ---- | ------ | | entities | 7.0.0 | 5,838,416 | 175.57 | 0.06 | — | | html-entities | 2.6.0 | 2,919,637 | 347.77 | 0.33 | 50.0% | | he | 1.2.0 | 2,318,438 | 446.48 | 0.70 | 60.3% | | parse-entities | 4.0.2 | 852,855 | 1,199.51 | 0.36 | 85.4% | ### Encoding | Library | Version | ops/s | avg (μs) | ±% | slower | | -------------- | ------- | --------- | -------- | ---- | ------ | | entities | 7.0.0 | 2,770,115 | 368.09 | 0.11 | — | | html-entities | 2.6.0 | 1,491,963 | 679.96 | 0.58 | 46.2% | | he | 1.2.0 | 481,278 | 2,118.25 | 0.61 | 82.6% | ### Escaping | Library | Version | ops/s | avg (μs) | ±% | slower | | -------------- | ------- | --------- | -------- | ---- | ------ | | entities | 7.0.0 | 4,616,468 | 223.84 | 0.17 | — | | he | 1.2.0 | 3,659,301 | 280.76 | 0.58 | 20.7% | | html-entities | 2.6.0 | 3,555,301 | 296.63 | 0.84 | 23.0% | Note: Micro-benchmarks may vary across machines and Node versions. --- ## FAQ > What methods should I actually use to encode my documents? If your target supports UTF-8, the `escapeUTF8` method is going to be your best choice. Otherwise, use either `encodeHTML` or `encodeXML` based on whether you're dealing with an HTML or an XML document. You can have a look at the options for the `encode` and `decode` methods to see everything you can configure. > When should I use strict decoding? When strict decoding, entities not terminated with a semicolon will be ignored. This is helpful for decoding entities in legacy environments. > Why should I use `entities` instead of alternative modules? As of September 2025, `entities` is faster than other modules. Still, this is not a differentiated space and other modules can catch up. **More importantly**, you might already have `entities` in your dependency graph (as a dependency of eg. `cheerio`, or `htmlparser2`), and including it directly might not even increase your bundle size. The same is true for other entity libraries, so have a look through your `node_modules` directory! > Does `entities` support tree shaking? Yes! Note that for best results, you should not use the `encode` and `decode` functions, as they wrap around a number of other functions, all of which will remain in the bundle. Instead, use the functions that you need directly. --- ## Acknowledgements This library wouldn't be possible without the work of these individuals. Thanks to - [@mathiasbynens](https://github.com/mathiasbynens) for his explanations about character encodings, and his library `he`, which was one of the inspirations for `entities` - [@inikulin](https://github.com/inikulin) for his work on optimized tries for decoding HTML entities for the `parse5` project - [@mdevils](https://github.com/mdevils) for taking on the challenge of producing a quick entity library with his `html-entities` library. `entities` would be quite a bit slower if there wasn't any competition. Right now `entities` is on top, but we'll see how long that lasts! --- License: BSD-2-Clause ## Security contact information To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.