stringify-entities
Serialize (encode) HTML character references.
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Algorithm
- Compatibility
- Security
- Related
- Contribute
- License
What is this?
This is a small and powerful encoder of HTML character references
(often called entities).
This one has either all the options you need for a minifier/formatter,
or a tiny size when using
stringifyEntitiesLight.
When should I use this?
You can use this for spec-compliant encoding of character references.
It’s small and fast enough to do that well.
You can also use this when making an HTML formatter or minifier,
because there are different ways to produce pretty or tiny output.
This package is reliable:
'`' characters are encoded to ensure no scripts run in
Internet Explorer 6 to 8.
Additionally, only named references recognized by HTML 4 are encoded,
meaning the infamous '
(which people think is a virus)
won’t show up.
Install
This package is ESM only. In Node.js (version 14.14+), install with npm:
npm install stringify-entities
In browsers with esm.sh:
<script type="module">
import {stringifyEntities} from 'https://esm.sh/stringify-entities@4?bundle'
</script>
Use
import {stringifyEntities} from 'stringify-entities'
stringifyEntities('alpha © bravo ≠ charlie 𝌆 delta')
// => 'alpha © bravo ≠ charlie 𝌆 delta'
stringifyEntities('alpha © bravo ≠ charlie 𝌆 delta', {useNamedReferences: true})
// => 'alpha © bravo ≠ charlie 𝌆 delta'
API
This package exports the identifiers
stringifyEntities and
stringifyEntitiesLight.
There is no default export.
It exports the additional TypeScript types
LightOptions and
Options.
LightOptions
Configuration for stringifyEntitiesLight
(TypeScript type).
Fields
escapeOnly(boolean, default:false) — whether to only escape possibly dangerous characters; those characters are",&,',<,>, and`subset(ReadonlyArray<string>, optional) — whether to only escape the given subset of characters; only BMP characters are supported here (so no emoji)
Options
Configuration for stringifyEntities
(TypeScript type).
Includes the fields of LightOptions.
If you do not care about the following fields,
use stringifyEntitiesLight.
Fields
attribute(boolean, default:false) — create character references which don’t fail in attributes; only applies when operating dangerously withomitOptionalSemicolons: trueomitOptionalSemicolons(boolean, default:false) — whether to omit semicolons when possible; this creates what HTML calls “parse errors” but is otherwise still valid HTML, so don’t use this except when building a minifier; omitting semicolons is possible for certain named and numeric references in some casesuseNamedReferences(boolean, default:false) — prefer named character references (&) where possibleuseShortestReferences(boolean, default:false) — prefer the shortest possible reference, if that results in less bytes;useNamedReferencescan be omitted when usinguseShortestReferences
stringifyEntitiesLight(value[, options])
Encode special characters in value as hexadecimal character references.
Parameters
value(string, required) — value to encodeoptions(LightOptions, optional) — configuration
Returns
Encoded value (string).
stringifyEntities(value[, options])
Encode special characters in value.
Parameters
value(string, required) — value to encodeoptions(Options, optional) — configuration
Returns
Encoded value (string).
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 stringifyEntitiesLight,
which works just like stringifyEntities
but without the formatting options:
it’s much smaller but always outputs hexadecimal character references.
Compatibility
This package is compatible with maintained versions of Node.js.
When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
stringify-entities@4,
compatible with Node.js 14.14.
Security
By default,
", &, ', <, >, and ` are always encoded,
so the result is safe to use in HTML text and in quoted attribute values.
Spaces and other ASCII characters are not encoded,
so the result is not safe in unquoted attribute values.
When you pass subset,
only those characters are encoded.
Leaving out characters such as < or & can open you up to a
cross-site scripting (XSS) attack.
Related
wooorm/character-entities— info on character referenceswooorm/character-entities-html4— info on HTML 4 character referenceswooorm/character-entities-legacy— info on legacy character referenceswooorm/character-reference-invalid— info on invalid numeric character referenceswooorm/parse-entities— parse (decode) HTML character references
Contribute
Yes please! See How to Contribute to Open Source.