speedy-entities 3.1.0 → 4.0.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Savva Mikhalevski
+Copyright (c) 2026 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,17 @@
-# speedy-entities 🏎💨
+<p align="center">
+  <a href="#readme"><img alt="Speedy Entities" src="./assets/logo.png" width="350" /></a>
+</p>
 
 [The fastest](#performance) XML/HTML entity encoder/decoder in
-[13 kB gzipped](https://bundlephobia.com/package/speedy-entities).
+[15 kB gzipped](https://bundlephobia.com/package/speedy-entities).
+
+- Keeps all HTML entities in about 120 kB of RAM.
+- [15 kB gzipped](https://bundlephobia.com/package/speedy-entities), including all HTML entities.
+- Decodes HTML exactly like browsers do.
+- Decodes your own entities with [custom decoders](#custom-decoder).
+- Zero dependencies.
+
+<br>
 
 ```shell
 npm install --save-prod speedy-entities
@@ -9,10 +19,10 @@ npm install --save-prod speedy-entities
 
 # Decode
 
-There are two preconfigured decoders: `decodeXML` and `decodeHTML`.
+There are three preconfigured decoders: `decodeXML`, `decodeHTML` and `decodeHTMLAttribute`.
 
 ```ts
-import { decodeXML, decodeHTML } from 'speedy-entities';
+import { decodeXML, decodeHTML, decodeHTMLAttribute } from 'speedy-entities';
 
 decodeXML('&#X61;&#98;&lt');
 // ⮕ 'ab&lt'
@@ -22,6 +32,10 @@ decodeHTML('&ltfoo&AElig');
 
 decodeHTML('&NotNestedGreaterGreater;&CounterClockwiseContourIntegral;');
 // ⮕ '\u2aa2\u0338\u2233'
+
+// Like browsers, preserves unterminated entities followed by "=" or an alphanumeric char
+decodeHTMLAttribute('/search?a=1&copy=2&reg');
+// ⮕ '/search?a=1&copy=2\u00ae'
 ```
 
 ## Custom decoder
@@ -52,9 +66,78 @@ decode('&#X61;&#x62;&#x63;');
 // ⮕ 'abc'
 ```
 
+`createEntityDecoder` accepts these options:
+
+<dl>
+<dt><code>entities</code></dt>
+<dd>
+
+Entity references mapped to their values, or a list of references and values in turn, like `['&foo;', 'okay']`. A
+reference is an optional `&`, a name of ASCII letters, digits and `-.:_`, and an optional `;`. If a reference has the
+`;`, the input needs it too.
+
+`createEntityDecoder` throws an error if a reference doesn't match this format.
+
+Defaults to `{}`.
+
+</dd>
+<dt><code>isNumericReferenceSemicolonRequired</code></dt>
+<dd>
+
+If `true`, numeric references are decoded only if they end with `;`, as XML requires.
+
+Defaults to `false`.
+
+</dd>
+<dt><code>areC1ControlsRemapped</code></dt>
+<dd>
+
+If `true`, `&#128;` to `&#159;` are decoded as Windows-1252 characters, as HTML does. For example, `&#128;` is decoded
+as `€`.
+
+Defaults to `true`.
+
+</dd>
+<dt><code>isAttributeValue</code></dt>
+<dd>
+
+If `true`, a named reference without `;` that is followed by `=` or an ASCII letter or digit isn't decoded, as HTML does
+in attribute values.
+
+Defaults to `false`.
+
+</dd>
+</dl>
+
+## Sharing a trie
+
+`createEntityDecoder` builds a trie of entity names on every call. To create several decoders for the same entities,
+build the trie once with `createEntityTrie` and pass it to `createEntityTrieDecoder`, which accepts the same options
+except `entities`. This is how `decodeHTML` and `decodeHTMLAttribute` share one trie of HTML entities.
+
+```ts
+import { createEntityTrie, createEntityTrieDecoder } from 'speedy-entities';
+
+const entityTrie = createEntityTrie({
+  '&foo;': 'okay',
+  '&qux': 'yeah',
+});
+
+const decodeText = createEntityTrieDecoder(entityTrie);
+
+const decodeAttribute = createEntityTrieDecoder(entityTrie, { isAttributeValue: true });
+
+decodeText('&foo;&qux=1');
+// ⮕ 'okayyeah=1'
+
+decodeAttribute('&foo;&qux=1');
+// ⮕ 'okay&qux=1'
+```
+
 # Encode
 
-`encodeXML` encodes non-ASCII characters as named XML entities or as numeric references.
+`encodeXML` replaces `"&'<>` with XML entities and non-ASCII characters with numeric character references, so the output
+is ASCII-only. A lone surrogate is encoded as `&#xfffd;`.
 
 `escapeXML` escapes only `"&'<>` characters.
 
@@ -65,26 +148,59 @@ encodeXML('&😘❤️');
 // ⮕ '&amp;&#x1f618;&#x2764;&#xfe0f;'
 
 escapeXML('&😘❤️');
-// ⮕ '&amp;😘❤'
+// ⮕ '&amp;😘❤️'
 ```
 
 # Performance
 
-Results are in millions of operations per second (MHz). The higher number is better.
+Results are in thousands of operations per second (kHz). 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 |
+|                                                                 Library |                                                      Library Size |   Decode HTML |    Decode XML |   Encode XML |    Escape XML |
+| ----------------------------------------------------------------------: | ----------------------------------------------------------------: | ------------: | ------------: | -----------: | ------------: |
+|                                           speedy-&#xFEFF;entities@4.0.0 | [14.9 kB](https://bundlephobia.com/package/speedy-entities@3.1.0) | 🥇 **161.74** | 🥇 **224.97** | 🥇 **85.43** | 🥇 **216.82** |
+|                      [entities](https://github.com/fb55/entities)@9.0.0 |        [21.7 kB](https://bundlephobia.com/package/entities@6.0.1) |        150.36 |        202.38 |        66.02 |        198.83 |
+| [html-&#xFEFF;entities](https://github.com/mdevils/html-entities)@2.6.0 |   [13.3 kB](https://bundlephobia.com/package/html-entities@2.6.0) |         39.64 |         49.36 |        33.76 |        127.65 |
+|                         [he](https://github.com/mathiasbynens/he)@2.0.0 |              [29.9 kB](https://bundlephobia.com/package/he@1.2.0) |         30.52 |         30.92 |        21.78 |        129.98 |
 
-Tests were conducted using [TooFast](https://github.com/smikhalevski/toofast#readme) on Apple M1 with Node.js v23.11.1.
+Tests were conducted using [TooFast](https://github.com/smikhalevski/toofast#readme) on Apple M1 with Node.js v26.11.1.
 
-To reproduce [the performance test suite](./src/test/perf/overall.perf.js) results, clone this repo and run:
+To reproduce [the performance test suite](src/test/perf.ts) results, clone this repo and run:
 
 ```shell
 npm ci
 npm run build
-npm run perf
+GROUP_MEASURE=2 npm run perf
+```
+
+The inputs of each function are split into groups, such as short and long inputs. `GROUP_MEASURE` sets what a test
+covers:
+
+<dl>
+<dt>Unset</dt>
+<dd>
+
+Each input is one test per library.
+
+</dd>
+<dt><code>GROUP_MEASURE=1</code></dt>
+<dd>
+
+Each group of inputs is one test per library.
+
+</dd>
+<dt><code>GROUP_MEASURE=2</code></dt>
+<dd>
+
+Each function is one test per library.
+
+</dd>
+</dl>
+
+A grouped test measures each of its inputs separately and combines the results, so its margin of error includes the
+spread between inputs.
+
+Pass a name pattern to run some of the tests:
+
+```shell
+GROUP_MEASURE=1 npm run perf -- 'decodeHTML*'
 ```

package/createDoubleArrayEntityTrie.d.ts

@@ -0,0 +1,49 @@
+declare const OPAQUE_BRAND: unique symbol;
+/**
+ * A trie of entity names, see {@linkcode createEntityTrie}. Its contents are internal, so they can change in any
+ * release.
+ */
+export interface EntityTrie {
+    /**
+     * Marks objects that {@linkcode createEntityTrie} returns. {@linkcode createEntityTrieDecoder} checks it at runtime,
+     * so it doesn't read a trie of an unknown layout.
+     *
+     * @internal
+     */
+    readonly [OPAQUE_BRAND]: never;
+}
+/**
+ * The contents of an {@linkcode EntityTrie}, see {@linkcode createEntityTrie}. The package doesn't export this module,
+ * so the layout can change in any release.
+ */
+export interface DoubleArrayEntityTrie extends EntityTrie {
+    /**
+     * The child of a node for a char is at `nodeBases[node] + charCode`.
+     */
+    nodeBases: Int32Array;
+    /**
+     * `nodeChecks[node] >> 1` is the parent of a node, and the low bit is set if an entity name ends at the node. -1
+     * marks an unused index.
+     */
+    nodeChecks: Int32Array;
+    /**
+     * The index in `values` of the value of the entity name that ends at a node. Most nodes have no value, so values
+     * aren't stored per node.
+     */
+    nodeValueIndexes: Uint16Array | Int32Array;
+    /**
+     * The values of entity names, see `nodeValueIndexes`.
+     */
+    values: string[];
+}
+/**
+ * Builds a trie from entity names and their values in turn, like `['amp', '&', 'amp;', '&']`. Names must be sorted,
+ * valid, and have no leading "&", see {@linkcode createEntityTrie}. If a name is listed several times, its last value
+ * is used.
+ *
+ * Nodes are visited depth first, and the children of a node are placed when it's visited. In sorted order, the names
+ * that go through a child of a node are next to each other, so they are found without lookups. The rest of a name that
+ * no other name goes through is a chain of single children, which is placed in one go.
+ */
+export declare function createDoubleArrayEntityTrie(entities: readonly string[]): DoubleArrayEntityTrie;
+export {};

package/createDoubleArrayEntityTrie.js

@@ -0,0 +1,159 @@
+/**
+ * Builds a trie from entity names and their values in turn, like `['amp', '&', 'amp;', '&']`. Names must be sorted,
+ * valid, and have no leading "&", see {@linkcode createEntityTrie}. If a name is listed several times, its last value
+ * is used.
+ *
+ * Nodes are visited depth first, and the children of a node are placed when it's visited. In sorted order, the names
+ * that go through a child of a node are next to each other, so they are found without lookups. The rest of a name that
+ * no other name goes through is a chain of single children, which is placed in one go.
+ */
+export function createDoubleArrayEntityTrie(entities) {
+    let charCount = 0;
+    for (let index = 0; index < entities.length; index += 2) {
+        charCount += entities[index].length;
+    }
+    // Each char adds at most one node, and arrays grow if nodes don't pack tightly
+    let size = charCount + 512;
+    let nodeBases = new Int32Array(size);
+    let nodeChecks = new Int32Array(size).fill(-1);
+    // The index in values of the value of the entity name that ends at a node
+    let valueIndexes = new Int32Array(size);
+    const values = [];
+    // Indexes below 128 stay unused, so a base is never negative and base + charCode is in bounds for any ASCII char
+    let firstUnusedIndex = 128;
+    // The largest index placed by a node with several children, other children are placed before firstUnusedIndex
+    let maxIndex = 128;
+    // The index where the search for a base of a node with several children starts, see below
+    let searchStartIndex = 128;
+    // The chars of the children of a node, and the names that go through each of them
+    const childChars = new Int32Array(128);
+    const childNameStarts = new Int32Array(128);
+    const childNameEnds = new Int32Array(128);
+    // Nodes to visit, four numbers each: the index of a node, the start and the end of the names in entityList that go
+    // through it, and its depth
+    const stack = [0, 0, entities.length, 0];
+    let stackLength = stack.length;
+    while (stackLength !== 0) {
+        stackLength -= 4;
+        const nodeIndex = stack[stackLength];
+        const nameEnd = stack[stackLength + 2];
+        const depth = stack[stackLength + 3];
+        let nameStart = stack[stackLength + 1];
+        if (nameStart !== nameEnd && entities[nameStart].length === depth) {
+            // A name ends at the node, it sorts before longer names, and copies of it follow it
+            do {
+                nameStart += 2;
+            } while (nameStart !== nameEnd && entities[nameStart].length === depth);
+            valueIndexes[nodeIndex] = values.length;
+            values.push(entities[nameStart - 1]);
+        }
+        if (nameStart === nameEnd) {
+            continue;
+        }
+        if (nameStart + 2 === nameEnd) {
+            // No other name goes through the rest of this name, so each of its chars is a single child
+            const name = entities[nameStart];
+            let parentIndex = nodeIndex;
+            for (let charIndex = depth; charIndex < name.length; ++charIndex) {
+                if (firstUnusedIndex + 128 > size) {
+                    size <<= 1;
+                    nodeBases = growInt32Array(nodeBases, size, 0);
+                    nodeChecks = growInt32Array(nodeChecks, size, -1);
+                    valueIndexes = growInt32Array(valueIndexes, size, 0);
+                }
+                nodeBases[parentIndex] = firstUnusedIndex - name.charCodeAt(charIndex);
+                nodeChecks[firstUnusedIndex] = (parentIndex << 1) | (charIndex === name.length - 1 ? 1 : 0);
+                parentIndex = firstUnusedIndex;
+                while (firstUnusedIndex < size && nodeChecks[firstUnusedIndex] !== -1) {
+                    ++firstUnusedIndex;
+                }
+            }
+            valueIndexes[parentIndex] = values.length;
+            values.push(entities[nameStart + 1]);
+            continue;
+        }
+        // The names that go through a child have the same char at this depth
+        let childCount = 0;
+        for (let index = nameStart; index !== nameEnd; ++childCount) {
+            const charCode = entities[index].charCodeAt(depth);
+            childChars[childCount] = charCode;
+            childNameStarts[childCount] = index;
+            do {
+                index += 2;
+            } while (index !== nameEnd && entities[index].charCodeAt(depth) === charCode);
+            childNameEnds[childCount] = index;
+        }
+        const isOnlyChild = childCount === 1;
+        // Children are sorted by char, so the first child lands on the first unused index, or on searchStartIndex if
+        // several children can't be placed before it
+        const startBase = (!isOnlyChild && searchStartIndex > firstUnusedIndex ? searchStartIndex : firstUnusedIndex) - childChars[0];
+        let base = startBase;
+        // Find a base that puts all children on unused indexes
+        while (true) {
+            if (base + 128 > size) {
+                size <<= 1;
+                nodeBases = growInt32Array(nodeBases, size, 0);
+                nodeChecks = growInt32Array(nodeChecks, size, -1);
+                valueIndexes = growInt32Array(valueIndexes, size, 0);
+            }
+            if (isOnlyChild) {
+                break;
+            }
+            let isUnused = true;
+            for (let childIndex = 0; childIndex < childCount; ++childIndex) {
+                if (nodeChecks[base + childChars[childIndex]] !== -1) {
+                    isUnused = false;
+                    break;
+                }
+            }
+            if (isUnused) {
+                break;
+            }
+            ++base;
+        }
+        if (base - startBase > 256) {
+            // The holes that a long search passed rarely fit several children. Later searches skip them, since passing the
+            // same holes for each node would make building a table with many such nodes take quadratic time.
+            searchStartIndex = base + childChars[0];
+        }
+        nodeBases[nodeIndex] = base;
+        for (let childIndex = 0; childIndex < childCount; ++childIndex) {
+            const index = base + childChars[childIndex];
+            // An entity name ends at a child if the first name that goes through it ends there
+            nodeChecks[index] = (nodeIndex << 1) | (entities[childNameStarts[childIndex]].length === depth + 1 ? 1 : 0);
+            if (!isOnlyChild && index > maxIndex) {
+                maxIndex = index;
+            }
+        }
+        while (firstUnusedIndex < size && nodeChecks[firstUnusedIndex] !== -1) {
+            ++firstUnusedIndex;
+        }
+        // Pushed in reverse, so children are visited in char order, and nodes are placed in preorder
+        for (let childIndex = childCount - 1; childIndex >= 0; --childIndex) {
+            stack[stackLength] = base + childChars[childIndex];
+            stack[stackLength + 1] = childNameStarts[childIndex];
+            stack[stackLength + 2] = childNameEnds[childIndex];
+            stack[stackLength + 3] = depth + 1;
+            stackLength += 4;
+        }
+    }
+    if (maxIndex < firstUnusedIndex) {
+        maxIndex = firstUnusedIndex;
+    }
+    // Keep base + charCode in bounds for any ASCII char
+    const finalSize = maxIndex + 128;
+    // 2-byte indexes take half the memory and are enough for most tables
+    const nodeValueIndexes = values.length <= 0x10000 ? new Uint16Array(finalSize) : new Int32Array(finalSize);
+    nodeValueIndexes.set(valueIndexes.subarray(0, finalSize));
+    return {
+        nodeBases: nodeBases.slice(0, finalSize),
+        nodeChecks: nodeChecks.slice(0, finalSize),
+        nodeValueIndexes,
+        values,
+    };
+}
+function growInt32Array(array, size, fillValue) {
+    const grownArray = new Int32Array(size).fill(fillValue, array.length);
+    grownArray.set(array);
+    return grownArray;
+}

package/createEntityDecoder.d.ts

@@ -1,33 +1,18 @@
+import { type EntityTrieDecoderOptions } from './createEntityTrieDecoder.ts';
 /**
- * The options recognized by {@linkcode createEntityDecoder}.
+ * Options of {@linkcode createEntityDecoder}.
  */
-export interface EntityDecoderOptions {
+export interface EntityDecoderOptions extends EntityTrieDecoderOptions {
     /**
-     * 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 ";".
+     * Entity references mapped to their values, for example `{ '&amp;': '&', 'lt;': '<' }`, or a list of references and
+     * values in turn, for example `['&amp;', '&', 'lt;', '<']`. A reference is an optional "&", a name of ASCII letters,
+     * digits and "-.:_", and an optional ";". If the reference has the ";", the input needs it too.
      *
-     * ```json
-     * {
-     *   "&Delta;": "\u0394",
-     *   "LongRightArrow;": "\u27F6"
-     * }
-     * ```
+     * @default {}
      */
-    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;
+    entities?: Record<string, string> | readonly string[];
 }
 /**
- * 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.
+ * Creates a decoder for numeric references and the given named entities.
  */
 export declare function createEntityDecoder(options?: EntityDecoderOptions): (input: string) => string;

package/createEntityDecoder.js

@@ -1,182 +1,9 @@
+import { createEntityTrie } from "./createEntityTrie.js";
+import { createEntityTrieDecoder } from "./createEntityTrieDecoder.js";
 /**
- * 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.
+ * Creates a decoder for numeric references and the given named entities.
  */
 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);
+    const { entities = {} } = options;
+    return createEntityTrieDecoder(createEntityTrie(entities), options);
 }

package/createEntityTrie.d.ts

@@ -0,0 +1,9 @@
+import { type EntityTrie } from './createDoubleArrayEntityTrie.ts';
+/**
+ * Builds a trie of entity names. Pass it to {@linkcode createEntityTrieDecoder} to create decoders that share it,
+ * since building a trie takes time and memory.
+ *
+ * @param entities Entity references mapped to their values, or a list of references and values in turn, see
+ * {@linkcode EntityDecoderOptions.entities}.
+ */
+export declare function createEntityTrie(entities: Record<string, string> | readonly string[]): EntityTrie;