speedy-entities 2.0.0 → 3.0.1-next.2f4dd34

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Savva Mikhalevski
+Copyright (c) 2025 Savva Mikhalevski
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,77 +1,71 @@
-# speedy-entities 🏎💨 [![build](https://github.com/smikhalevski/speedy-entities/actions/workflows/master.yml/badge.svg?branch=master&event=push)](https://github.com/smikhalevski/speedy-entities/actions/workflows/master.yml)
+# Speedy Entities
 
-[The fastest](#performance) XML/HTML entity decoder that supports customizable named character references.
+[The fastest](#performance) XML/HTML entity encoder/decoder in
+[20 kB gzipped](https://bundlephobia.com/package/speedy-entities).
 
 ```shell
 npm install --save-prod speedy-entities
 ```
 
-# Usage
+# Decode
 
-[API documentation is available here.](https://smikhalevski.github.io/speedy-entities/)
-
-## Preconfigured decoders
-
-There are two preconfigured decoders: `decodeXml` and `decodeHtml`.
+There are two preconfigured decoders: `decodeXML` and `decodeHTML`.
 
 ```ts
-import {decodeXml, decodeHtml} from 'speedy-entities';
+import { decodeXML, decodeHTML } from 'speedy-entities';
 
-decodeXml('ab<'); // → "ab&lt"
+decodeXML('ab&lt');
+// ⮕ 'ab&lt'
 
-decodeHtml('&ltfoo&AElig'); // → "<foo\u00c6"
+decodeHTML('&ltfoo&AElig');
+// ⮕ '<foo\u00c6'
 
-decodeHtml('&NotNestedGreaterGreater;&CounterClockwiseContourIntegral;');
-// → "\u2aa2\u0338\u2233"
+decodeHTML('&NotNestedGreaterGreater;&CounterClockwiseContourIntegral;');
+// ⮕ '\u2aa2\u0338\u2233'
 ```
 
-You can add custom entities that `decodeXml` and `decodeHtml` would recognize:
-
-```ts
-import {decodeXml, decodeHtml, xmlEntityManager, htmlEntityManager} from 'speedy-entities';
-
-xmlEntityManager.set('foo', 'okay');
-decodeXml('&foo;'); // → "okay"
+## Custom decoder
 
-htmlEntityManager.set('bar', 'nope');
-decodeHtml('&bar;'); // → "nope"
-```
+You can create a decoder that decodes custom named entities:
 
-## Custom decoders
+```ts
+import { createEntityDecoder } from 'speedy-entities';
 
-You can create a custom decoder that would recognize numeric and custom entities.
+// Create a decoder
+const decode = createEntityDecoder({
+  entities: {
+    'foo;': 'okay',
+    'qux;': 'yeah',
+  },
+  isNumericReferenceSemicolonRequired: true,
+});
 
-```ts
-import {createEntityDecoder, EntityManager} from 'speedy-entities';
+// Decode entities
+decode('&foo;');
+// ⮕ 'okay'
 
-// Create an entity manager
-const entityManager = new EntityManager();
+decode('&foo');
+// ⮕ '&foo'
 
-// Register a new entity
-entityManager.set('foo', 'okay');
+// Decode numeric character references
+decode('&#X61;&#x62;&#x63;');
+// ⮕ 'abc'
+```
 
-// Register a new legacy entity
-entityManager.set('bar', 'nope', true);
+# Encode
 
-// Register a batch of entities
-entityManager.set({
-  foo: 'okay',
-  qux: 'yeah',
-});
+`encodeXML` encodes non-ASCII characters as named XML entities or as numeric references.
 
-// Create a decoder
-const decode = createEntityDecoder(entityManager);
+`escapeXML` escapes only `"&'<>` characters.
 
-// Decode non-legacy entities
-decode('&foo'); // → "&foo"
-decode('&foo;'); // → "okay"
+```ts
+import { encodeXML, escapeXML } from 'speedy-entities';
 
-// Decode legacy entities
-decode('&bar'); // → "nope"
-decode('&bar;'); // → "nope"
+encodeXML('&😘❤️');
+// ⮕ '&amp;&#x1f618;&#x2764;&#xfe0f;'
 
-// Decode numeric character references
-decode('&#X61;&#x62;&#x63;'); // → "abc"
+escapeXML('&😘❤️');
+// ⮕ '&amp;😘❤'
 ```
 
 # Performance
@@ -80,13 +74,10 @@ Clone this repo and use `npm ci && npm run perf` to run the performance testsuit
 
 Results are in millions of operations per second. The higher number is better.
 
-|                               | speedy-entities <br/>`decodeXml` | [fb55/entities](https://github.com/fb55/entities) <br/>`decodeXML` | speedy-entities <br/>`decodeHtml` | [fb55/entities](https://github.com/fb55/entities) <br/>`decodeHTML` |
-|-------------------------------|---------------------------------:| ---: | ---: | ---: |
-| `"&#X61;&#x62;&#x63;"`        | 3.9 | 2.5 | 4.3 | 2.5 |
-| `"&#X61&#x62&#x63"`           | 5.1 | 2.7 | 4.3 | 2.4 |
-| `"&#97;&#98;&#99;"`           | 4.5 | 2.4 | 4.5 | 2.4 |
-| `"&#97&#98&#99"`              | 5.5 | 2.4 | 4.2 | 2.3 |
-| `"&amp;&lt;&gt;"`             | 3.8 | 3.3 | 3.7 | 3.1 |
-| `"&amp&lt&gt"`                | 3.6 | 3.4 | 3.6 | 3.3 |
-| `"&NotNestedGreaterGreater;"` | 5.3 | 4.6 | 3.9 | 3.2 |
-| `"&NotNestedGreaterGreater"`  | 5.3 | 4.6 | 3.9 | 3.3 |
+### Decode
+
+![Decode HTML performance chart](./images/perf-decode-html.svg)
+
+### Encode
+
+![Encode XML performance chart](./images/perf-encode-xml.svg)

package/createEntityDecoder.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The options recognized by {@linkcode createEntityDecoder}.
+ */
+export interface EntityDecoderOptions {
+    /**
+     * Mapping from an [character entity reference](https://www.w3.org/TR/html4/charset.html#h-5.3.2) to its decoded value.
+     *
+     * Keys may optionally start with an ampersand "&" character. If an key ends with a semicolon ";" then
+     * a character entity reference must end with a semicolon as well in decoded strings.
+     *
+     * @example
+     * {
+     *   'Δ': '\u0394',
+     *   'LongRightArrow;': '\u27F6'
+     * }
+     */
+    entities?: Record<string, string>;
+    /**
+     * If `true` then [numeric character references](https://www.w3.org/TR/html4/charset.html#h-5.3.1) must be terminated
+     * with a semicolon to be decoded. Otherwise, numeric character references are recognized even if they aren't
+     * terminated with a semicolon.
+     *
+     * @default false
+     */
+    isNumericReferenceSemicolonRequired?: boolean;
+}
+/**
+ * Creates an entity decoder that rewrites numeric and named entities found in input to their respective values.
+ *
+ * @param options The decoder options.
+ * @returns A function that decodes entities in the string.
+ */
+export declare function createEntityDecoder(options?: EntityDecoderOptions): (input: string) => string;

package/createEntityDecoder.js

@@ -0,0 +1,170 @@
+const fromCharCode = String.fromCharCode;
+/**
+ * Creates an entity decoder that rewrites numeric and named entities found in input to their respective values.
+ *
+ * @param options The decoder options.
+ * @returns A function that decodes entities in the string.
+ */
+export function createEntityDecoder(options = {}) {
+    const { entities, isNumericReferenceSemicolonRequired = false } = options;
+    let entitiesMap;
+    let maximumNamedReferenceLength = 0;
+    if (entities !== undefined) {
+        entitiesMap = new Map();
+        for (let key in entities) {
+            key = key.charCodeAt(0) === /* & */ 38 ? key.substring(1) : key;
+            maximumNamedReferenceLength = Math.max(maximumNamedReferenceLength, key.length);
+            entitiesMap.set(getHashCode(key), entities[key]);
+        }
+    }
+    return input => {
+        let output = '';
+        let textIndex = 0;
+        let charIndex = 0;
+        const inputLength = input.length;
+        while (charIndex < inputLength - 1) {
+            let startIndex = input.indexOf('&', charIndex);
+            if (startIndex === -1) {
+                break;
+            }
+            charIndex = startIndex++;
+            let value;
+            let endIndex = startIndex;
+            let charCode = 0;
+            if (startIndex < inputLength - 2 && input.charCodeAt(startIndex) === /* # */ 35) {
+                // Numeric character reference
+                let codePoint = 0;
+                if ((input.charCodeAt(++startIndex) | 32) === /* x */ 120) {
+                    endIndex = ++startIndex;
+                    // parseInt of a hexadecimal number
+                    while (endIndex - startIndex < 6 && endIndex < inputLength) {
+                        // Convert alpha to lower case
+                        charCode = input.charCodeAt(endIndex) | 32;
+                        if ((charCode >= /* 0 */ 48 && charCode <= /* 9 */ 57) ||
+                            (charCode >= /* a */ 97 && charCode <= /* f */ 102)) {
+                            // Convert "0" → 0 and "f" → 15
+                            codePoint = codePoint * 16 + charCode - (charCode & 112) + (charCode >> 6) * 9;
+                            ++endIndex;
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                }
+                else {
+                    endIndex = startIndex;
+                    // parseInt of a decimal number
+                    while (endIndex - startIndex < 6 && endIndex < inputLength) {
+                        charCode = input.charCodeAt(endIndex) | 32;
+                        if (charCode >= /* 0 */ 48 && charCode <= /* 9 */ 57) {
+                            codePoint = codePoint * 10 + charCode - (charCode & 112);
+                            ++endIndex;
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                }
+                if (endIndex !== startIndex) {
+                    // At least one digit must present
+                    const isTerminated = endIndex < inputLength && input.charCodeAt(endIndex) === /* ; */ 59;
+                    if (isTerminated || !isNumericReferenceSemicolonRequired) {
+                        // Convert a code point to a string
+                        // https://github.com/mathiasbynens/he/blob/master/src/he.js#L106-L134
+                        if (codePoint === 0 || (codePoint >= 0xd800 && codePoint <= 0xdfff) || codePoint > 0x10ffff) {
+                            // Null char code, or character reference is outside the permissible Unicode range
+                            value = '\uFFFD';
+                        }
+                        else if (codePoint >= 128 &&
+                            codePoint <= 195 &&
+                            codePoint !== 129 &&
+                            codePoint !== 141 &&
+                            codePoint !== 143 &&
+                            codePoint !== 144 &&
+                            codePoint !== 157) {
+                            // Overridden char code
+                            value = entityOverrides[codePoint];
+                        }
+                        else if (codePoint > 0xffff) {
+                            // Surrogate pair
+                            codePoint -= 0x10000;
+                            value = fromCharCode(((codePoint >>> 10) & 0x3ff) | 0xd800, 0xdc00 | (codePoint & 0x3ff));
+                        }
+                        else {
+                            // Char code
+                            value = fromCharCode(codePoint);
+                        }
+                    }
+                    if (isTerminated) {
+                        ++endIndex;
+                    }
+                }
+            }
+            else if (entitiesMap !== undefined) {
+                // Named character reference
+                for (let index = startIndex, hashCode = 0, nextValue; index < inputLength; ++index) {
+                    charCode = input.charCodeAt(index);
+                    if (charCode !== /* ; */ 59 &&
+                        (charCode < /* a */ 97 || charCode > /* z */ 122) &&
+                        (charCode < /* A */ 65 || charCode > /* Z */ 90)) {
+                        break;
+                    }
+                    hashCode = (hashCode << 5) - hashCode + charCode;
+                    nextValue = entitiesMap.get(hashCode);
+                    if (nextValue !== undefined) {
+                        value = nextValue;
+                        endIndex = index + 1;
+                    }
+                    if (charCode === /* ; */ 59 || index - startIndex >= maximumNamedReferenceLength) {
+                        break;
+                    }
+                }
+            }
+            // Concat decoded entity and preceding substring
+            if (value !== undefined) {
+                output += textIndex === charIndex ? value : input.slice(textIndex, charIndex) + value;
+                textIndex = endIndex;
+            }
+            charIndex = endIndex;
+        }
+        return textIndex === 0 ? input : textIndex === inputLength ? output : output + input.slice(textIndex);
+    };
+}
+// Standing on the shoulders of giants
+// https://github.com/mathiasbynens/he/blob/master/data/decode-map-overrides.json
+const entityOverrides = {
+    128: '\u20AC',
+    130: '\u201A',
+    131: '\u0192',
+    132: '\u201E',
+    133: '\u2026',
+    134: '\u2020',
+    135: '\u2021',
+    136: '\u02C6',
+    137: '\u2030',
+    138: '\u0160',
+    139: '\u2039',
+    140: '\u0152',
+    142: '\u017D',
+    145: '\u2018',
+    146: '\u2019',
+    147: '\u201C',
+    148: '\u201D',
+    149: '\u2022',
+    150: '\u2013',
+    151: '\u2014',
+    152: '\u02DC',
+    153: '\u2122',
+    154: '\u0161',
+    155: '\u203A',
+    156: '\u0153',
+    158: '\u017E',
+    159: '\u0178',
+};
+function getHashCode(str) {
+    let hashCode = 0;
+    for (let i = 0; i < str.length; ++i) {
+        hashCode = (hashCode << 5) - hashCode + str.charCodeAt(i);
+    }
+    return hashCode;
+}

package/decodeHTML.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Decodes all known HTML entities and numeric character references in the input.
+ */
+export declare const decodeHTML: (input: string) => string;

package/decodeHTML.js

@@ -0,0 +1,9 @@
+import { createEntityDecoder } from './createEntityDecoder.js';
+import htmlEntities from './html-entities.js';
+/**
+ * Decodes all known HTML entities and numeric character references in the input.
+ */
+export const decodeHTML = createEntityDecoder({
+    entities: htmlEntities,
+    isNumericReferenceSemicolonRequired: false,
+});

package/decodeXML.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Decodes XML entities and numeric character references in the input.
+ */
+export declare const decodeXML: (input: string) => string;

package/decodeXML.js

@@ -0,0 +1,9 @@
+import { createEntityDecoder } from './createEntityDecoder.js';
+import xmlEntities from './xml-entities.js';
+/**
+ * Decodes XML entities and numeric character references in the input.
+ */
+export const decodeXML = createEntityDecoder({
+    entities: xmlEntities,
+    isNumericReferenceSemicolonRequired: true,
+});

package/encodeXML.d.ts

@@ -0,0 +1 @@
+export declare function encodeXML(input: string): string;

package/encodeXML.js

@@ -0,0 +1,38 @@
+const re = /["&'<>\u0080-\uffff]/g;
+export function encodeXML(input) {
+    let output = '';
+    let textIndex = 0;
+    while (re.test(input)) {
+        let lastIndex = re.lastIndex;
+        const startIndex = lastIndex - 1;
+        const charCode = input.charCodeAt(startIndex);
+        let entity;
+        if (charCode >= 0x80 && charCode <= 0xffff) {
+            let codePoint = charCode;
+            if ((charCode & 0xfc00) === 0xd800) {
+                // Surrogate pair
+                codePoint = charCode * 0x400 + input.charCodeAt(lastIndex) - 0x35fdc00;
+                re.lastIndex = ++lastIndex;
+            }
+            entity = '&#x' + codePoint.toString(16) + ';';
+        }
+        else if (charCode === 34) {
+            entity = '&quot;';
+        }
+        else if (charCode === 38) {
+            entity = '&amp;';
+        }
+        else if (charCode === 39) {
+            entity = '&apos;';
+        }
+        else if (charCode === 60) {
+            entity = '&lt;';
+        }
+        else {
+            entity = '&gt;';
+        }
+        output += textIndex === startIndex ? entity : input.slice(textIndex, startIndex) + entity;
+        textIndex = lastIndex;
+    }
+    return textIndex === 0 ? input : textIndex === input.length ? output : output + input.slice(textIndex);
+}

package/escapeXML.d.ts

@@ -0,0 +1 @@
+export declare function escapeXML(input: string): string;

package/escapeXML.js

@@ -0,0 +1,29 @@
+const re = /["&'<>]/g;
+export function escapeXML(input) {
+    let output = '';
+    let textIndex = 0;
+    while (re.test(input)) {
+        const lastIndex = re.lastIndex;
+        const startIndex = lastIndex - 1;
+        const charCode = input.charCodeAt(startIndex);
+        let entity;
+        if (charCode === 34) {
+            entity = '&quot;';
+        }
+        else if (charCode === 38) {
+            entity = '&amp;';
+        }
+        else if (charCode === 39) {
+            entity = '&apos;';
+        }
+        else if (charCode === 60) {
+            entity = '&lt;';
+        }
+        else {
+            entity = '&gt;';
+        }
+        output += textIndex === startIndex ? entity : input.slice(textIndex, startIndex) + entity;
+        textIndex = lastIndex;
+    }
+    return textIndex === 0 ? input : textIndex === input.length ? output : output + input.slice(textIndex);
+}