1 | html-entities
|
2 | =============
|
3 |
|
4 | Fastest HTML entities library.
|
5 |
|
6 | Comes with both TypeScript and Flow types.
|
7 |
|
8 | Installation
|
9 | ------------
|
10 |
|
11 | ```bash
|
12 | $ npm install html-entities
|
13 | ```
|
14 |
|
15 | Usage
|
16 | -----
|
17 |
|
18 | ### encode(text, options)
|
19 |
|
20 | Encodes text replacing HTML special characters (`<>&"'`) plus other character ranges depending on `mode` option value.
|
21 |
|
22 | ```js
|
23 | import {encode} from 'html-entities';
|
24 |
|
25 | encode('< > " \' & © ∆');
|
26 | // -> '< > " ' & © ∆'
|
27 |
|
28 | encode('< ©', {mode: 'nonAsciiPrintable'});
|
29 | // -> '< ©'
|
30 |
|
31 | encode('< ©', {mode: 'nonAsciiPrintable', level: 'xml'});
|
32 | // -> '< ©'
|
33 | ```
|
34 |
|
35 | Options:
|
36 |
|
37 | #### level
|
38 |
|
39 | * `all` alias to `html5` (default).
|
40 | * `html5` uses `HTML5` named references.
|
41 | * `html4` uses `HTML4` named references.
|
42 | * `xml` uses `XML` named references.
|
43 |
|
44 | #### mode
|
45 |
|
46 | * `specialChars` encodes only HTML special characters (default).
|
47 | * `nonAscii` encodes HTML special characters and everything outside of the [ASCII character range](https://en.wikipedia.org/wiki/ASCII).
|
48 | * `nonAsciiPrintable` encodes HTML special characters and everything outiside of the [ASCII printable characters](https://en.wikipedia.org/wiki/ASCII#Printable_characters).
|
49 | * `extensive` encodes all non-printable characters, non-ASCII characters and all characters with named references.
|
50 |
|
51 | #### numeric
|
52 |
|
53 | * `decimal` uses decimal numbers when encoding html entities. i.e. `©` (default).
|
54 | * `hexadecimal` uses hexadecimal numbers when encoding html entities. i.e. `©`.
|
55 |
|
56 |
|
57 | ### decode(text, options)
|
58 |
|
59 | Decodes text replacing entities to characters. Unknown entities are left as is.
|
60 |
|
61 | ```js
|
62 | import {decode} from 'html-entities';
|
63 |
|
64 | decode('< > " ' & © ∆');
|
65 | // -> '< > " \' & © ∆'
|
66 |
|
67 | decode('©', {level: 'html5'});
|
68 | // -> '©'
|
69 |
|
70 | decode('©', {level: 'xml'});
|
71 | // -> '©'
|
72 | ```
|
73 |
|
74 | Options:
|
75 |
|
76 | #### level
|
77 |
|
78 | * `all` alias to `html5` (default).
|
79 | * `html5` uses `HTML5` named references.
|
80 | * `html4` uses `HTML4` named references.
|
81 | * `xml` uses `XML` named references.
|
82 |
|
83 | #### scope
|
84 |
|
85 | * `body` emulates behavior of browser when parsing tag bodies: entities without semicolon are also replaced (default).
|
86 | * `attribute` emulates behavior of browser when parsing tag attributes: entities without semicolon are replaced when not followed by equality sign `=`.
|
87 | * `strict` ignores entities without semicolon.
|
88 |
|
89 | ### decodeEntity(text, options)
|
90 |
|
91 | Decodes a single HTML entity. Unknown entitiy is left as is.
|
92 |
|
93 | ```js
|
94 | import {decodeEntity} from 'html-entities';
|
95 |
|
96 | decodeEntity('<');
|
97 | // -> '<'
|
98 |
|
99 | decodeEntity('©', {level: 'html5'});
|
100 | // -> '©'
|
101 |
|
102 | decodeEntity('©', {level: 'xml'});
|
103 | // -> '©'
|
104 | ```
|
105 |
|
106 | Options:
|
107 |
|
108 | #### level
|
109 |
|
110 | * `all` alias to `html5` (default).
|
111 | * `html5` uses `HTML5` named references.
|
112 | * `html4` uses `HTML4` named references.
|
113 | * `xml` uses `XML` named references.
|
114 |
|
115 | Performance
|
116 | -----------
|
117 |
|
118 | Statistically significant comparison with other libraries using `benchmark.js`.
|
119 | Results by this library are marked with `*`.
|
120 | The source code of the benchmark is available at `benchmark/benchmark.ts`.
|
121 |
|
122 | ```
|
123 | Common
|
124 |
|
125 | Initialization / Load speed
|
126 |
|
127 | * #1: html-entities x 2,544,400 ops/sec ±4.52% (77 runs sampled)
|
128 | #2: entities x 1,757,526 ops/sec ±3.99% (81 runs sampled)
|
129 | #3: he x 1,281,542 ops/sec ±9.31% (74 runs sampled)
|
130 |
|
131 | HTML5
|
132 |
|
133 | Encode test
|
134 |
|
135 | * #1: html-entities.encode - html5, nonAscii x 402,711 ops/sec ±0.61% (92 runs sampled)
|
136 | * #2: html-entities.encode - html5, nonAsciiPrintable x 402,631 ops/sec ±2.99% (92 runs sampled)
|
137 | * #3: html-entities.encode - html5, extensive x 269,162 ops/sec ±0.26% (97 runs sampled)
|
138 | #4: entities.encodeNonAsciiHTML x 260,447 ops/sec ±2.53% (95 runs sampled)
|
139 | #5: entities.encodeHTML x 101,059 ops/sec ±3.99% (91 runs sampled)
|
140 | #6: he.encode x 93,180 ops/sec ±3.17% (92 runs sampled)
|
141 |
|
142 | Decode test
|
143 |
|
144 | * #1: html-entities.decode - html5, attribute x 340,043 ops/sec ±2.82% (92 runs sampled)
|
145 | * #2: html-entities.decode - html5, body x 330,002 ops/sec ±1.52% (87 runs sampled)
|
146 | * #3: html-entities.decode - html5, strict x 320,582 ops/sec ±5.34% (88 runs sampled)
|
147 | #4: entities.decodeHTMLStrict x 286,294 ops/sec ±3.14% (89 runs sampled)
|
148 | #5: entities.decodeHTML x 232,856 ops/sec ±3.05% (90 runs sampled)
|
149 | #6: he.decode x 163,300 ops/sec ±0.62% (92 runs sampled)
|
150 |
|
151 | HTML4
|
152 |
|
153 | Encode test
|
154 |
|
155 | * #1: html-entities.encode - html4, nonAsciiPrintable x 391,885 ops/sec ±0.27% (95 runs sampled)
|
156 | * #2: html-entities.encode - html4, nonAscii x 400,086 ops/sec ±2.54% (94 runs sampled)
|
157 | * #3: html-entities.encode - html4, extensive x 193,623 ops/sec ±2.70% (92 runs sampled)
|
158 |
|
159 | Decode test
|
160 |
|
161 | * #1: html-entities.decode - html4, attribute x 356,174 ops/sec ±0.49% (96 runs sampled)
|
162 | * #2: html-entities.decode - html4, body x 342,666 ops/sec ±2.38% (91 runs sampled)
|
163 | * #3: html-entities.decode - html4, strict x 341,667 ops/sec ±4.46% (87 runs sampled)
|
164 |
|
165 | XML
|
166 |
|
167 | Encode test
|
168 |
|
169 | * #1: html-entities.encode - xml, nonAscii x 450,968 ops/sec ±2.73% (92 runs sampled)
|
170 | * #2: html-entities.encode - xml, nonAsciiPrintable x 432,058 ops/sec ±4.12% (93 runs sampled)
|
171 | * #3: html-entities.encode - xml, extensive x 265,336 ops/sec ±3.41% (93 runs sampled)
|
172 | #4: entities.encodeXML x 254,862 ops/sec ±3.01% (95 runs sampled)
|
173 |
|
174 | Decode test
|
175 |
|
176 | * #1: html-entities.decode - xml, strict x 432,820 ops/sec ±0.53% (89 runs sampled)
|
177 | * #2: html-entities.decode - xml, attribute x 426,037 ops/sec ±0.75% (94 runs sampled)
|
178 | * #3: html-entities.decode - xml, body x 424,618 ops/sec ±3.47% (93 runs sampled)
|
179 | #4: entities.decodeXML x 378,536 ops/sec ±2.48% (93 runs sampled)
|
180 |
|
181 | Escaping
|
182 |
|
183 | Escape test
|
184 |
|
185 | * #1: html-entities.encode - xml, specialChars x 1,424,362 ops/sec ±0.55% (95 runs sampled)
|
186 | #2: he.escape x 962,420 ops/sec ±3.12% (94 runs sampled)
|
187 | #3: entities.escapeUTF8 x 443,138 ops/sec ±1.06% (90 runs sampled)
|
188 | #4: entities.escape x 197,515 ops/sec ±2.73% (91 runs sampled)
|
189 | ```
|
190 |
|
191 | License
|
192 | -------
|
193 |
|
194 | MIT
|
195 |
|
196 | Security contact information
|
197 | ----------------------------
|
198 |
|
199 | To report a security vulnerability, please use the
|
200 | [Tidelift security contact](https://tidelift.com/security). Tidelift will
|
201 | coordinate the fix and disclosure.
|
202 |
|
203 | `html-entities` for enterprise
|
204 | ------------------------------
|
205 |
|
206 | Available as part of the Tidelift Subscription
|
207 |
|
208 | The maintainers of `html-entities` and thousands of other packages are working with
|
209 | Tidelift to deliver commercial support and maintenance for the open source
|
210 | dependencies you use to build your applications. Save time, reduce risk, and
|
211 | improve code health, while paying the maintainers of the exact dependencies you
|
212 | use.
|
213 | [Learn more.](https://tidelift.com/subscription/pkg/npm-html-entities?utm_source=npm-html-entities&utm_medium=referral&utm_campaign=enterprise)
|