speedy-entities 3.0.1 → 3.1.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 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,7 +1,7 @@
-# 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 encoder/decoder in
-[20 kB gzipped](https://bundlephobia.com/package/speedy-entities).
+[13 kB gzipped](https://bundlephobia.com/package/speedy-entities).
 
 ```shell
 npm install --save-prod speedy-entities
@@ -26,26 +26,18 @@ decodeHTML('⪢̸&CounterClockwiseContourIntegral;');
 
 ## Custom decoder
 
-You can create a decoder that decodes custom named entities:
+You can create a decoder that decodes your custom character entity references:
 
 ```ts
-import { arrayTrieEncode, trieCreate, trieSet } from '@smikhalevski/trie';
 import { createEntityDecoder } from 'speedy-entities';
 
-// Create a trie that would hold entities
-const trie = trieCreate<string>();
-
-// Register named entities
-trieSet('foo;', 'okay');
-trieSet('qux;', 'yeah');
-
-// Encode a trie
-const entitiesTrie = arrayTrieEncode(trie);
-
 // Create a decoder
 const decode = createEntityDecoder({
-  entitiesTrie,
-  numericReferenceSemicolonRequired: true,
+  entities: {
+    '&foo;': 'okay',
+    '&qux;': 'yeah',
+  },
+  isNumericReferenceSemicolonRequired: true,
 });
 
 // Decode entities
@@ -78,14 +70,21 @@ escapeXML('&😘❤️');
 
 # Performance
 
-Clone this repo and use `npm ci && npm run perf` to run the performance testsuite.
+Results are in millions of operations per second (MHz). The higher number is better.
 
-Results are in millions of operations per second. The higher number is better.
+|                           Library | Decode HTML | Decode XML | Encode XML | Escape XML |
+| --------------------------------: | ----------: | ---------: | ---------: | ---------: |
+| **speedy-entities**&#x200B;@3.1.0 |     **4.9** |    **5.2** |    **5.3** |    **7.2** |
+|        **entities**&#x200B;@6.0.1 |         3.4 |        3.6 |        4.5 |        6.1 |
+|   **html-entities**&#x200B;@2.6.0 |         2.2 |        2.3 |        3.3 |        5.1 |
+|              **he**&#x200B;@1.2.0 |         1.9 |        1.8 |        2.2 |        5.2 |
 
-### Decode
+Tests were conducted using [TooFast](https://github.com/smikhalevski/toofast#readme) on Apple M1 with Node.js v23.11.1.
 
-![Decode HTML performance chart](./images/perf-decode-html.svg)
+To reproduce [the performance test suite](./src/test/perf/overall.perf.js) results, clone this repo and run:
 
-### Encode
-
-![Encode XML performance chart](./images/perf-encode-xml.svg)
+```shell
+npm ci
+npm run build
+npm run perf
+```

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.
+     * Entity references should contain only [a-zA-Z] and may optionally start with an ampersand "&" and end with
+     * a semicolon ";".
+     *
+     * ```json
+     * {
+     *   "Δ": "\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,182 @@
+/**
+ * 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;
+    const fromCharCode = String.fromCharCode;
+    let entityDereferenceMap;
+    let maximumEntityReferenceLength = 32;
+    if (entities !== undefined) {
+        entityDereferenceMap = new Map();
+        for (const entity in entities) {
+            const hashCode = getEntityReferenceHashCode(entity);
+            if (hashCode !== 0) {
+                maximumEntityReferenceLength = Math.max(maximumEntityReferenceLength, entity.length);
+                entityDereferenceMap.set(hashCode, entities[entity]);
+            }
+        }
+    }
+    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 (entityDereferenceMap !== undefined) {
+                // Character entity reference
+                let index = startIndex;
+                let hashCode = 0;
+                let referencedValue;
+                while (charCode !== /* ; */ 59 &&
+                    index < inputLength &&
+                    index - startIndex < maximumEntityReferenceLength &&
+                    ((charCode = input.charCodeAt(index) | 0), isEntityReferenceChar(charCode))) {
+                    ++index;
+                    hashCode = (hashCode << 5) - hashCode + charCode;
+                    referencedValue = entityDereferenceMap.get(hashCode);
+                    if (referencedValue !== undefined) {
+                        value = referencedValue;
+                        endIndex = index;
+                    }
+                }
+            }
+            // 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 getEntityReferenceHashCode(entity) {
+    if (entity.length === 0) {
+        return 0;
+    }
+    let hashCode = 0;
+    for (let index = entity.charCodeAt(0) === /* & */ 38 ? 1 : 0; index < entity.length; ++index) {
+        const charCode = entity.charCodeAt(index);
+        if (!isEntityReferenceChar(charCode)) {
+            return 0;
+        }
+        hashCode = (hashCode << 5) - hashCode + entity.charCodeAt(index);
+    }
+    return hashCode;
+}
+function isEntityReferenceChar(charCode) {
+    return ((charCode >= /* a */ 97 && charCode <= /* z */ 122) ||
+        (charCode >= /* A */ 65 && charCode <= /* Z */ 90) ||
+        charCode === /* ; */ 59);
+}

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);
+}