stringify-entities

Encode HTML character references.

[x] Very fast
[x] Just the encoding part
[x] Has either all the options you need for a minifier/prettifier, or a tiny size w/ stringifyEntitiesLight
[x] Reliable: '`' characters are escaped to ensure no scripts run in Internet Explorer 6 to 8. Additionally, only named references recognized by HTML4 are encoded, meaning the infamous ' (which people think is a virus) won’t show up

Algorithm

By default, all dangerous, non-ASCII, and non-printable ASCII characters are encoded. A subset of characters can be given to encode just those characters. Alternatively, pass escapeOnly to escape just the dangerous characters (", ', <, >, &, `). By default, hexadecimal character references are used. Pass useNamedReferences to use named character references when possible, or useShortestReferences to use whichever is shortest: decimal, hexadecimal, or named. There is also a stringifyEntitiesLight export, which works just like stringifyEntities but without the formatting options: it’s much smaller but always outputs hexadecimal character references.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install stringify-entities

Use

import {stringifyEntities} from 'stringify-entities'

stringifyEntities('alpha © bravo ≠ charlie ???? delta')
// => 'alpha &#xA9; bravo &#x2260; charlie &#x1D306; delta'

stringifyEntities('alpha © bravo ≠ charlie ???? delta', {useNamedReferences: true})
// => 'alpha &copy; bravo &ne; charlie &#x1D306; delta'

API

This package exports the following identifiers: stringifyEntities, stringifyEntitiesLight. There is no default export.

`stringifyEntities(value[, options])`

Encode special characters in value.

`options`

Core options

`options.escapeOnly`

Whether to only escape possibly dangerous characters (boolean, default: false). Those characters are ", &, ', <, >, and `.

`options.subset`

Whether to only escape the given subset of characters (Array.<string>). Note that only BMP characters are supported here (so no emoji).

Formatting options

If you do not care about these, use stringifyEntitiesLight, which always outputs hexadecimal character references.

`options.useNamedReferences`

Prefer named character references (&) where possible (boolean?, default: false).

`options.useShortestReferences`

Prefer the shortest possible reference, if that results in less bytes (boolean?, default: false). Note: useNamedReferences can be omitted when using useShortestReferences.

`options.omitOptionalSemicolons`

Whether to omit semicolons when possible (boolean?, default: false). Note: This creates what HTML calls “parse errors” but is otherwise still valid HTML — don’t use this except when building a minifier.

Omitting semicolons is possible for legacy named references in certain cases, and numeric references in some cases.

`options.attribute`

Only needed when operating dangerously with omitOptionalSemicolons: true. Create character references which don’t fail in attributes (boolean?, default: false).

parse-entities — Parse HTML character references
character-entities — Info on character entities
character-entities-html4 — Info on HTML 4 character entities
character-entities-legacy — Info on legacy character entities
character-reference-invalid — Info on invalid numeric character references