Nine Pounds of Mayonnaise

    stringify-entities
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.3 • Public • Published

    stringify-entities

    Build Status Coverage Status Downloads Size

    Serialize (encode) HTML character references.

    Contents

    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 12.20+, 14.14+, or 16.0+), install with npm:

    npm install stringify-entities

    In Deno with esm.sh:

    import {stringifyEntities} from 'https://esm.sh/stringify-entities@4'

    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 &#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.

    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 the following options, use stringifyEntitiesLight, which always outputs hexadecimal character references.

    options.useNamedReferences

    Prefer named character references (&amp;) 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 certain named and numeric references in some cases.

    options.attribute

    Create character references which don’t fail in attributes (boolean?, default: false).

    ⚠️ Note: attribute only applies when operating dangerously with omitOptionalSemicolons: true.

    Returns

    string — encoded value.

    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.

    Types

    This package is fully typed with TypeScript. Additional Options and LightOptions types, that model their respective values, are exported.

    Compatibility

    This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. It also works in Deno and modern browsers.

    Security

    This package is safe.

    Related

    Contribute

    Yes please! See How to Contribute to Open Source.

    License

    MIT © Titus Wormer

    Install

    npm i stringify-entities

    DownloadsWeekly Downloads

    1,549,145

    Version

    4.0.3

    License

    MIT

    Unpacked Size

    23.5 kB

    Total Files

    21

    Last publish

    Collaborators

    • wooorm