speedy-entities 1.1.3 → 3.0.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Savva Mikhalevski
+Copyright (c) 2023 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,103 +1,79 @@
-# 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 🏎💨 [![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)
 
-[The fastest](#performance) XML/HTML entity decoder that supports customizable named character references.
+[The fastest](#performance) XML/HTML entity encoder/decoder in
+[23 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';
-
-decodeXml('ab<'); // → "ab&lt"
-decodeHtml('&ltfoo&AElig'); // → "<foo\u00c6"
-```
-
-By default, `decodeHtml` supports only legacy HTML entities. This allowed to reduce the bundle size to just
-[2.3 kB gzipped](https://bundlephobia.com/package/speedy-entities).
-
-<details>
-<summary>The list of legacy HTML entities</summary>
-<p>
+import { decodeXML, decodeHTML } from 'speedy-entities';
 
-> `aacute` `Aacute` `acirc` `Acirc` `acute` `aelig` `AElig` `agrave` `Agrave` `amp` `AMP` `aring` `Aring` `atilde`
-> `Atilde` `auml` `Auml` `brvbar` `ccedil` `Ccedil` `cedil` `cent` `copy` `COPY` `curren` `deg` `divide` `eacute`
-> `Eacute` `ecirc` `Ecirc` `egrave` `Egrave` `eth` `ETH` `euml` `Euml` `frac12` `frac14` `frac34` `gt` `GT` `iacute`
-> `Iacute` `icirc` `Icirc` `iexcl` `igrave` `Igrave` `iquest` `iuml` `Iuml` `laquo` `lt` `LT` `macr` `micro` `middot`
-> `nbsp` `not` `ntilde` `Ntilde` `oacute` `Oacute` `ocirc` `Ocirc` `ograve` `Ograve` `ordf` `ordm` `oslash` `Oslash`
-> `otilde` `Otilde` `ouml` `Ouml` `para` `plusmn` `pound` `quot` `QUOT` `raquo` `reg` `REG` `sect` `shy` `sup1` `sup2`
-> `sup3` `szlig` `thorn` `THORN` `times` `uacute` `Uacute` `ucirc` `Ucirc` `ugrave` `Ugrave` `uml` `uuml` `Uuml`
-> `yacute` `Yacute` `yen` `yuml`
+decodeXML('&#X61;&#98;&lt');
+// ⮕ 'ab&lt'
 
-</p>
-</details>
+decodeHTML('&ltfoo&AElig');
+// ⮕ '<foo\u00c6'
 
-To decode [all HTML entities](https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references)
-import from `speedy-entities/lib/full`. The size of this bundle is 12.5 kB gzipped.
-
-```ts
-import {decodeXml, decodeHtml} from 'speedy-entities/lib/full';
-
-decodeXml('&#X61;&#98;&lt;'); // → "ab&lt"
-decodeHtml('&NotNestedGreaterGreater;&CounterClockwiseContourIntegral;');
-// → "\u2aa2\u0338\u2233"
+decodeHTML('&NotNestedGreaterGreater;&CounterClockwiseContourIntegral;');
+// ⮕ '\u2aa2\u0338\u2233'
 ```
 
-You can manually add entities that `decodeXml` and `decodeHtml` would recognize:
+## Custom decoder
+
+You can create a decoder that decodes custom named entities:
 
 ```ts
-import {decodeXml, decodeHtml, xmlEntityManager, htmlEntityManager} from 'speedy-entities';
+import { arrayTrieEncode, trieCreate, trieSet } from '@smikhalevski/trie';
+import { createEntityDecoder } from 'speedy-entities';
 
-xmlEntityManager.set('foo', 'okay');
-decodeXml('&foo;'); // → "okay"
+// Create a trie that would hold entities
+const trie = trieCreate<string>();
 
-htmlEntityManager.set('bar', 'nope');
-decodeHtml('&bar;'); // → "nope"
-```
+// Register named entities
+trieSet('foo;', 'okay');
+trieSet('qux;', 'yeah');
 
-## Custom decoders
+// Encode a trie
+const entitiesTrie = arrayTrieEncode(trie);
 
-You can create a custom decoder that would recognize custom entities.
+// Create a decoder
+const decode = createEntityDecoder({
+  entitiesTrie,
+  numericReferenceSemicolonRequired: true,
+});
 
-```ts
-import {createEntityDecoder, createEntityManager} from 'speedy-entities';
+// Decode entities
+decode('&foo;');
+// ⮕ 'okay'
 
-// Create an entity manager
-const entityManager = createEntityManager();
+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
@@ -106,13 +82,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;"`        | 2.36 | 1.25 | 2.29 | 0.88 |
-| `"&#X61&#x62&#x63"`           | 4.61 | 3.00 | 2.39 | 0.72 |
-| `"&#97;&#98;&#99;"`           | 2.24 | 0.71 | 2.25 | 0.92 |
-| `"&#97&#98&#99"`              | 5.09 | 3.07 | 2.21 | 0.88 |
-| `"&amp;&lt;&gt;"`             | 3.98 | 1.28 | 3.34 | 1.06 |
-| `"&amp&lt&gt"`                | 4.08 | 3.10 | 3.46 | 1.02 |
-| `"&NotNestedGreaterGreater;"` | 6.47 | 1.84 | 3.80 | 1.64 |
-| `"&NotNestedGreaterGreater"`  | 6.44 | 2.74 | 4.00 | 2.41 |
+### Decode
+
+![Decode HTML performance chart](./images/perf-decode-html.svg)
+
+### Encode
+
+![Encode XML performance chart](./images/perf-encode-xml.svg)

package/lib/index.d.ts

@@ -1,4 +1,42 @@
-export * from './createEntityDecoder';
-export * from './createEntityManager';
-export * from './decodeHtml';
-export * from './decodeXml';
+import { ArrayTrie } from '@smikhalevski/trie';
+
+/**
+ * The options recognized by {@linkcode createEntityDecoder}.
+ */
+interface EntityDecoderOptions {
+    /**
+     * The trie of [character entity references](https://www.w3.org/TR/html4/charset.html#h-5.3.2).
+     */
+    entitiesTrie?: ArrayTrie<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
+     */
+    numericReferenceSemicolonRequired?: 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.
+ */
+declare function createEntityDecoder(options?: EntityDecoderOptions): (input: string) => string;
+
+/**
+ * Decodes all known HTML entities and numeric character references in the input.
+ */
+declare const decodeHTML: (input: string) => string;
+
+/**
+ * Decodes XML entities and numeric character references in the input.
+ */
+declare const decodeXML: (input: string) => string;
+
+declare function encodeXML(input: string): string;
+
+declare function escapeXML(input: string): string;
+
+export { EntityDecoderOptions, createEntityDecoder, decodeHTML, decodeXML, encodeXML, escapeXML };