AK-21/Graphite-Industrial-Intelligence
0
1# stringify-entities2 3[![Build Status][build-badge]][build]4[![Coverage Status][coverage-badge]][coverage]5[![Downloads][downloads-badge]][downloads]6[![Size][size-badge]][size]7 8Serialize (encode) HTML character references.9 10## Contents11 12* [What is this?](#what-is-this)13* [When should I use this?](#when-should-i-use-this)14* [Install](#install)15* [Use](#use)16* [API](#api)17 * [`stringifyEntities(value[, options])`](#stringifyentitiesvalue-options)18* [Algorithm](#algorithm)19* [Types](#types)20* [Compatibility](#compatibility)21* [Security](#security)22* [Related](#related)23* [Contribute](#contribute)24* [License](#license)25 26## What is this?27 28This is a small and powerful encoder of HTML character references (often called29entities).30This one has either all the options you need for a minifier/formatter, or a31tiny size when using `stringifyEntitiesLight`.32 33## When should I use this?34 35You can use this for spec-compliant encoding of character references.36It’s small and fast enough to do that well.37You can also use this when making an HTML formatter or minifier, because there38are different ways to produce pretty or tiny output.39This package is reliable: ``'`'`` characters are encoded to ensure no scripts40run in Internet Explorer 6 to 8.41Additionally, only named references recognized by HTML 4 are encoded, meaning42the infamous `'` (which people think is a [virus][]) won’t show up.43 44## Install45 46This package is [ESM only][esm].47In Node.js (version 14.14+, 16.0+), install with [npm][]:48 49```sh50npm install stringify-entities51```52 53In Deno with [`esm.sh`][esmsh]:54 55```js56import {stringifyEntities} from 'https://esm.sh/stringify-entities@4'57```58 59In browsers with [`esm.sh`][esmsh]:60 61```html62<script type="module">63 import {stringifyEntities} from 'https://esm.sh/stringify-entities@4?bundle'64</script>65```66 67## Use68 69```js70import {stringifyEntities} from 'stringify-entities'71 72stringifyEntities('alpha © bravo ≠ charlie 𝌆 delta')73// => 'alpha © bravo ≠ charlie 𝌆 delta'74 75stringifyEntities('alpha © bravo ≠ charlie 𝌆 delta', {useNamedReferences: true})76// => 'alpha © bravo ≠ charlie 𝌆 delta'77```78 79## API80 81This package exports the identifiers `stringifyEntities` and82`stringifyEntitiesLight`.83There is no default export.84 85### `stringifyEntities(value[, options])`86 87Encode special characters in `value`.88 89##### Core options90 91###### `options.escapeOnly`92 93Whether to only escape possibly dangerous characters (`boolean`, default:94`false`).95Those characters are `"`, `&`, `'`, `<`, `>`, and `` ` ``.96 97###### `options.subset`98 99Whether to only escape the given subset of characters (`Array<string>`).100Note that only BMP characters are supported here (so no emoji).101 102##### Formatting options103 104If you do not care about the following options, use `stringifyEntitiesLight`,105which always outputs hexadecimal character references.106 107###### `options.useNamedReferences`108 109Prefer named character references (`&`) where possible (`boolean?`, default:110`false`).111 112###### `options.useShortestReferences`113 114Prefer the shortest possible reference, if that results in less bytes115(`boolean?`, default: `false`).116 117> ⚠️ **Note**: `useNamedReferences` can be omitted when using118> `useShortestReferences`.119 120###### `options.omitOptionalSemicolons`121 122Whether to omit semicolons when possible (`boolean?`, default: `false`).123 124> ⚠️ **Note**: This creates what HTML calls “parse errors” but is otherwise125> still valid HTML — don’t use this except when building a minifier.126> Omitting semicolons is possible for certain named and numeric references in127> some cases.128 129###### `options.attribute`130 131Create character references which don’t fail in attributes (`boolean?`, default:132`false`).133 134> ⚠️ **Note**: `attribute` only applies when operating dangerously with135> `omitOptionalSemicolons: true`.136 137#### Returns138 139Encoded value (`string`).140 141## Algorithm142 143By default, all dangerous, non-ASCII, and non-printable ASCII characters are144encoded.145A [subset][] of characters can be given to encode just those characters.146Alternatively, pass [`escapeOnly`][escapeonly] to escape just the dangerous147characters (`"`, `'`, `<`, `>`, `&`, `` ` ``).148By default, hexadecimal character references are used.149Pass [`useNamedReferences`][named] to use named character references when150possible, or [`useShortestReferences`][short] to use whichever is shortest:151decimal, hexadecimal, or named.152There is also a `stringifyEntitiesLight` export, which works just like153`stringifyEntities` but without the formatting options: it’s much smaller but154always outputs hexadecimal character references.155 156## Types157 158This package is fully typed with [TypeScript][].159It exports the additional types `Options` and `LightOptions` types.160 161## Compatibility162 163This package is at least compatible with all maintained versions of Node.js.164As of now, that is Node.js 14.14+ and 16.0+.165It also works in Deno and modern browsers.166 167## Security168 169This package is safe.170 171## Related172 173* [`parse-entities`](https://github.com/wooorm/parse-entities)174 — parse (decode) HTML character references175* [`wooorm/character-entities`](https://github.com/wooorm/character-entities)176 — info on character references177* [`wooorm/character-entities-html4`](https://github.com/wooorm/character-entities-html4)178 — info on HTML 4 character references179* [`wooorm/character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)180 — info on legacy character references181* [`wooorm/character-reference-invalid`](https://github.com/wooorm/character-reference-invalid)182 — info on invalid numeric character references183 184## Contribute185 186Yes please!187See [How to Contribute to Open Source][contribute].188 189## License190 191[MIT][license] © [Titus Wormer][author]192 193<!-- Definitions -->194 195[build-badge]: https://github.com/wooorm/stringify-entities/workflows/main/badge.svg196 197[build]: https://github.com/wooorm/stringify-entities/actions198 199[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/stringify-entities.svg200 201[coverage]: https://codecov.io/github/wooorm/stringify-entities202 203[downloads-badge]: https://img.shields.io/npm/dm/stringify-entities.svg204 205[downloads]: https://www.npmjs.com/package/stringify-entities206 207[size-badge]: https://img.shields.io/bundlephobia/minzip/stringify-entities.svg208 209[size]: https://bundlephobia.com/result?p=stringify-entities210 211[npm]: https://docs.npmjs.com/cli/install212 213[esmsh]: https://esm.sh214 215[license]: license216 217[author]: https://wooorm.com218 219[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c220 221[typescript]: https://www.typescriptlang.org222 223[contribute]: https://opensource.guide/how-to-contribute/224 225[virus]: https://www.telegraph.co.uk/technology/advice/10516839/Why-do-some-apostrophes-get-replaced-with-andapos.html226 227[subset]: #optionssubset228 229[escapeonly]: #optionsescapeonly230 231[named]: #optionsusenamedreferences232 233[short]: #optionsuseshortestreferences234