[57e58a3] | 1 | # entities [](https://npmjs.org/package/entities) [](https://npmjs.org/package/entities) [](https://github.com/fb55/entities/actions/workflows/nodejs-test.yml)
|
---|
| 2 |
|
---|
| 3 | Encode & decode HTML & XML entities with ease & speed.
|
---|
| 4 |
|
---|
| 5 | ## Features
|
---|
| 6 |
|
---|
| 7 | - 😇 Tried and true: `entities` is used by many popular libraries; eg.
|
---|
| 8 | [`htmlparser2`](https://github.com/fb55/htmlparser2), the official
|
---|
| 9 | [AWS SDK](https://github.com/aws/aws-sdk-js-v3) and
|
---|
| 10 | [`commonmark`](https://github.com/commonmark/commonmark.js) use it to
|
---|
| 11 | process HTML entities.
|
---|
| 12 | - ⚡️ Fast: `entities` is the fastest library for decoding HTML entities (as
|
---|
| 13 | of April 2022); see [performance](#performance).
|
---|
| 14 | - 🎛 Configurable: Get an output tailored for your needs. You are fine with
|
---|
| 15 | UTF8? That'll save you some bytes. Prefer to only have ASCII characters? We
|
---|
| 16 | can do that as well!
|
---|
| 17 |
|
---|
| 18 | ## How to…
|
---|
| 19 |
|
---|
| 20 | ### …install `entities`
|
---|
| 21 |
|
---|
| 22 | npm install entities
|
---|
| 23 |
|
---|
| 24 | ### …use `entities`
|
---|
| 25 |
|
---|
| 26 | ```javascript
|
---|
| 27 | const entities = require("entities");
|
---|
| 28 |
|
---|
| 29 | // Encoding
|
---|
| 30 | entities.escapeUTF8("& ü"); // "& ü"
|
---|
| 31 | entities.encodeXML("& ü"); // "& ü"
|
---|
| 32 | entities.encodeHTML("& ü"); // "& ü"
|
---|
| 33 |
|
---|
| 34 | // Decoding
|
---|
| 35 | entities.decodeXML("asdf & ÿ ü '"); // "asdf & ÿ ü '"
|
---|
| 36 | entities.decodeHTML("asdf & ÿ ü '"); // "asdf & ÿ ü '"
|
---|
| 37 | ```
|
---|
| 38 |
|
---|
| 39 | ## Performance
|
---|
| 40 |
|
---|
| 41 | This is how `entities` compares to other libraries on a very basic benchmark
|
---|
| 42 | (see `scripts/benchmark.ts`, for 10,000,000 iterations; **lower is better**):
|
---|
| 43 |
|
---|
| 44 | | Library | Version | `decode` perf | `encode` perf | `escape` perf |
|
---|
| 45 | | -------------- | ------- | ------------- | ------------- | ------------- |
|
---|
| 46 | | entities | `3.0.1` | 1.418s | 6.786s | 2.196s |
|
---|
| 47 | | html-entities | `2.3.2` | 2.530s | 6.829s | 2.415s |
|
---|
| 48 | | he | `1.2.0` | 5.800s | 24.237s | 3.624s |
|
---|
| 49 | | parse-entities | `3.0.0` | 9.660s | N/A | N/A |
|
---|
| 50 |
|
---|
| 51 | ---
|
---|
| 52 |
|
---|
| 53 | ## FAQ
|
---|
| 54 |
|
---|
| 55 | > What methods should I actually use to encode my documents?
|
---|
| 56 |
|
---|
| 57 | If your target supports UTF-8, the `escapeUTF8` method is going to be your best
|
---|
| 58 | choice. Otherwise, use either `encodeHTML` or `encodeXML` based on whether
|
---|
| 59 | you're dealing with an HTML or an XML document.
|
---|
| 60 |
|
---|
| 61 | You can have a look at the options for the `encode` and `decode` methods to see
|
---|
| 62 | everything you can configure.
|
---|
| 63 |
|
---|
| 64 | > When should I use strict decoding?
|
---|
| 65 |
|
---|
| 66 | When strict decoding, entities not terminated with a semicolon will be ignored.
|
---|
| 67 | This is helpful for decoding entities in legacy environments.
|
---|
| 68 |
|
---|
| 69 | > Why should I use `entities` instead of alternative modules?
|
---|
| 70 |
|
---|
| 71 | As of April 2022, `entities` is a bit faster than other modules. Still, this is
|
---|
| 72 | not a very differentiated space and other modules can catch up.
|
---|
| 73 |
|
---|
| 74 | **More importantly**, you might already have `entities` in your dependency graph
|
---|
| 75 | (as a dependency of eg. `cheerio`, or `htmlparser2`), and including it directly
|
---|
| 76 | might not even increase your bundle size. The same is true for other entity
|
---|
| 77 | libraries, so have a look through your `node_modules` directory!
|
---|
| 78 |
|
---|
| 79 | > Does `entities` support tree shaking?
|
---|
| 80 |
|
---|
| 81 | Yes! `entities` ships as both a CommonJS and a ES module. Note that for best
|
---|
| 82 | results, you should not use the `encode` and `decode` functions, as they wrap
|
---|
| 83 | around a number of other functions, all of which will remain in the bundle.
|
---|
| 84 | Instead, use the functions that you need directly.
|
---|
| 85 |
|
---|
| 86 | ---
|
---|
| 87 |
|
---|
| 88 | ## Acknowledgements
|
---|
| 89 |
|
---|
| 90 | This library wouldn't be possible without the work of these individuals. Thanks
|
---|
| 91 | to
|
---|
| 92 |
|
---|
| 93 | - [@mathiasbynens](https://github.com/mathiasbynens) for his explanations
|
---|
| 94 | about character encodings, and his library `he`, which was one of the
|
---|
| 95 | inspirations for `entities`
|
---|
| 96 | - [@inikulin](https://github.com/inikulin) for his work on optimized tries for
|
---|
| 97 | decoding HTML entities for the `parse5` project
|
---|
| 98 | - [@mdevils](https://github.com/mdevils) for taking on the challenge of
|
---|
| 99 | producing a quick entity library with his `html-entities` library.
|
---|
| 100 | `entities` would be quite a bit slower if there wasn't any competition.
|
---|
| 101 | Right now `entities` is on top, but we'll see how long that lasts!
|
---|
| 102 |
|
---|
| 103 | ---
|
---|
| 104 |
|
---|
| 105 | License: BSD-2-Clause
|
---|
| 106 |
|
---|
| 107 | ## Security contact information
|
---|
| 108 |
|
---|
| 109 | To report a security vulnerability, please use the
|
---|
| 110 | [Tidelift security contact](https://tidelift.com/security). Tidelift will
|
---|
| 111 | coordinate the fix and disclosure.
|
---|
| 112 |
|
---|
| 113 | ## `entities` for enterprise
|
---|
| 114 |
|
---|
| 115 | Available as part of the Tidelift Subscription
|
---|
| 116 |
|
---|
| 117 | The maintainers of `entities` and thousands of other packages are working with
|
---|
| 118 | Tidelift to deliver commercial support and maintenance for the open source
|
---|
| 119 | dependencies you use to build your applications. Save time, reduce risk, and
|
---|
| 120 | improve code health, while paying the maintainers of the exact dependencies you
|
---|
| 121 | use.
|
---|
| 122 | [Learn more.](https://tidelift.com/subscription/pkg/npm-entities?utm_source=npm-entities&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
|
---|