speedy-entities 3.0.1-next.bb17de5 → 3.1.0

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,25 +26,17 @@ 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,
+  entities: {
+    '&foo;': 'okay',
+    '&qux;': 'yeah',
+  },
   isNumericReferenceSemicolonRequired: true,
 });
 
@@ -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

@@ -2,8 +2,19 @@
  * The options recognized by {@linkcode createEntityDecoder}.
  */
 export interface EntityDecoderOptions {
-    entities?: Map<number, string>;
-    maximumNamedReferenceLength?: number;
+    /**
+     * 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
+     * {
+     *   "&Delta;": "\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

package/createEntityDecoder.js

@@ -1,4 +1,3 @@
-const fromCharCode = String.fromCharCode;
 /**
  * Creates an entity decoder that rewrites numeric and named entities found in input to their respective values.
  *
@@ -6,7 +5,20 @@ const fromCharCode = String.fromCharCode;
  * @returns A function that decodes entities in the string.
  */
 export function createEntityDecoder(options = {}) {
-    const { entities, maximumNamedReferenceLength = 32, isNumericReferenceSemicolonRequired = false } = 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;
@@ -90,23 +102,21 @@ export function createEntityDecoder(options = {}) {
                     }
                 }
             }
-            else if (entities !== 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;
-                    }
+            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;
-                    nextValue = entities.get(hashCode >>> 0);
-                    if (nextValue !== undefined) {
-                        value = nextValue;
-                        endIndex = index + 1;
-                    }
-                    if (charCode === /* ; */ 59 || index - startIndex >= maximumNamedReferenceLength) {
-                        break;
+                    referencedValue = entityDereferenceMap.get(hashCode);
+                    if (referencedValue !== undefined) {
+                        value = referencedValue;
+                        endIndex = index;
                     }
                 }
             }
@@ -151,3 +161,22 @@ const entityOverrides = {
     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.js

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

package/decodeXML.js

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