speedy-entities 3.0.1 → 4.0.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 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 🏎💨 [![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)
+<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
-[20 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,30 +32,26 @@ 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
 
-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
@@ -60,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.
 
@@ -73,19 +148,59 @@ encodeXML('&😘❤️');
 // ⮕ '&amp;&#x1f618;&#x2764;&#xfe0f;'
 
 escapeXML('&😘❤️');
-// ⮕ '&amp;😘❤'
+// ⮕ '&amp;😘❤️'
 ```
 
 # Performance
 
-Clone this repo and use `npm ci && npm run perf` to run the performance testsuite.
+Results are in thousands of operations per second (kHz). The higher number is better.
 
-Results are in millions of operations per second. The higher number is better.
+|                                                                 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 |
 
-### Decode
+Tests were conducted using [TooFast](https://github.com/smikhalevski/toofast#readme) on Apple M1 with Node.js v26.11.1.
 
-![Decode HTML performance chart](./images/perf-decode-html.svg)
+To reproduce [the performance test suite](src/test/perf.ts) results, clone this repo and run:
+
+```shell
+npm ci
+npm run build
+GROUP_MEASURE=2 npm run perf
+```
 
-### Encode
+The inputs of each function are split into groups, such as short and long inputs. `GROUP_MEASURE` sets what a test
+covers:
 
-![Encode XML performance chart](./images/perf-encode-xml.svg)
+<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

@@ -0,0 +1,18 @@
+import { type EntityTrieDecoderOptions } from './createEntityTrieDecoder.ts';
+/**
+ * Options of {@linkcode createEntityDecoder}.
+ */
+export interface EntityDecoderOptions extends EntityTrieDecoderOptions {
+    /**
+     * 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.
+     *
+     * @default {}
+     */
+    entities?: Record<string, string> | readonly string[];
+}
+/**
+ * Creates a decoder for numeric references and the given named entities.
+ */
+export declare function createEntityDecoder(options?: EntityDecoderOptions): (input: string) => string;

package/createEntityDecoder.js

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

package/createEntityTrie.js

@@ -0,0 +1,69 @@
+import { createDoubleArrayEntityTrie } from "./createDoubleArrayEntityTrie.js";
+/**
+ * An optional "&", a name of ASCII letters, digits and "-.:_", and an optional ";".
+ */
+const entityRegExp = /^&?[a-zA-Z0-9.:_-]+;?$/;
+/**
+ * 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 function createEntityTrie(entities) {
+    if (Array.isArray(entities)) {
+        if (entities.length % 2 !== 0) {
+            throw new Error('entities must list references and values in turn');
+        }
+        return createEntityTrieFromArray(entities);
+    }
+    const uncheckedEntities = [];
+    for (const entity of Object.keys(entities)) {
+        uncheckedEntities.push(entity, entities[entity]);
+    }
+    return createEntityTrieFromArray(uncheckedEntities);
+}
+/**
+ * Builds a trie from references and values in turn. Lists are usually sorted and have no "&", so a list is copied only
+ * if a name has "&" or names aren't sorted.
+ */
+function createEntityTrieFromArray(uncheckedEntities) {
+    let checkedEntities = uncheckedEntities;
+    let isSorted = true;
+    let previousEntity = '';
+    for (let index = 0; index < uncheckedEntities.length; index += 2) {
+        let entity = uncheckedEntities[index];
+        if (typeof entity !== 'string' || !entityRegExp.test(entity)) {
+            throw new Error('Invalid entity reference: ' + JSON.stringify(entity));
+        }
+        if (typeof uncheckedEntities[index + 1] !== 'string') {
+            throw new Error('Value of entity reference must be a string: ' + JSON.stringify(entity));
+        }
+        if (entity.charCodeAt(0) === /* & */ 38) {
+            entity = entity.slice(1);
+            if (checkedEntities === uncheckedEntities) {
+                checkedEntities = uncheckedEntities.slice(0);
+            }
+            checkedEntities[index] = entity;
+        }
+        // Stripping "&" can change the order, so entities are compared without it
+        if (entity < previousEntity) {
+            isSorted = false;
+        }
+        previousEntity = entity;
+    }
+    return createDoubleArrayEntityTrie(isSorted ? checkedEntities : sortByEntityReference(checkedEntities));
+}
+// Sort is stable, so "&lt;" and "lt;" keep their order, and the value of the latter is used
+function sortByEntityReference(entities) {
+    const indexes = new Uint32Array(entities.length / 2);
+    for (let index = 0; index < indexes.length; ++index) {
+        indexes[index] = index * 2;
+    }
+    indexes.sort((a, b) => (entities[a] < entities[b] ? -1 : entities[a] > entities[b] ? 1 : 0));
+    const sortedEntities = [];
+    for (const index of indexes) {
+        sortedEntities.push(entities[index], entities[index + 1]);
+    }
+    return sortedEntities;
+}

package/createEntityTrieDecoder.d.ts

@@ -0,0 +1,33 @@
+import { type EntityTrie } from './createDoubleArrayEntityTrie.ts';
+/**
+ * Options of {@linkcode createEntityTrieDecoder}.
+ */
+export interface EntityTrieDecoderOptions {
+    /**
+     * If `true`, numeric references are decoded only if they end with ";", as XML requires.
+     *
+     * @default false
+     */
+    isNumericReferenceSemicolonRequired?: boolean;
+    /**
+     * If `true`, numeric references to C1 controls (U+0080 to U+009F) are decoded as Windows-1252 chars,
+     * [as HTML does](https://html.spec.whatwg.org/multipage/parsing.html#numeric-character-reference-end-state). For
+     * example, "€" is decoded as the euro sign instead of U+0080.
+     *
+     * @default true
+     */
+    areC1ControlsRemapped?: boolean;
+    /**
+     * If `true`, a named reference without ";" isn't decoded if "=" or an ASCII letter or digit follows it,
+     * [as HTML does in attribute values](https://html.spec.whatwg.org/multipage/parsing.html#named-character-reference-state).
+     * This keeps URL query strings like "?a=1&copy=2" intact.
+     *
+     * @default false
+     */
+    isAttributeValue?: boolean;
+}
+/**
+ * Creates a decoder that uses a trie from {@linkcode createEntityTrie}, so decoders that differ only in options can
+ * share a trie.
+ */
+export declare function createEntityTrieDecoder(entityTrie: EntityTrie, options?: EntityTrieDecoderOptions): (input: string) => string;