cmpstr 2.0.2 → 3.0.0

package/dist/CmpStr.esm.js

@@ -0,0 +1,4863 @@
+/**
+ * CmpStr v3.0.0 dev-1a82e20-250612
+ * This is a lightweight, fast and well performing library for calculating string similarity.
+ * (c) 2023-2025 Paul Köhler @komed3 / MIT License
+ * Visit https://github.com/komed3/cmpstr and https://npmjs.org/package/cmpstr
+ */
+/**
+ * Deep Merge Utility
+ * src/utils/DeepMerge.ts
+ *
+ * This module provides utility functions for deep merging objects, getting values by path,
+ * and setting values by path in a deeply nested object structure.
+ *
+ * It supports dot and bracket notation (e.g. `a.b[0].c`) as well as escaped keys.
+ *
+ * Included functions:
+ *  - `get`:   Retrieve a deeply nested value by path
+ *  - `set`:   Assign a value to a nested path
+ *  - `merge`: Deeply merge two objects
+ *  - `has`:   Check whether a path exists
+ *  - `rmv`:   Delete a value at a path
+ *
+ * @module Utils/DeepMerge
+ * @author Paul Köhler
+ * @license MIT
+ */
+/**
+ * Parse a path string into an array of keys.
+ *
+ * @param {string} p - The path string, e.g. `a.b.c` or `a[0].b`
+ * @returns {(string|number)[]} - An array of keys, e.g. `['a', 'b', 'c']` or `['a', 0, 'b']`
+ */
+const parse = (p) => (p.replace(/\[(\d+)]/g, '.$1').split('.').map(s => /^\d+$/.test(s) ? +s : s));
+/**
+ * Deeply get a value from an object by a path string.
+ *
+ * @template T - The type of the object to get the value from
+ * @param {T} t - The object to get the value from
+ * @param {string} path - The path string, e.g. `a.b.c`
+ * @param {any} fallback - The default value to return if the path does not exist
+ * @returns {T|R|undefined} - The value at the specified path, otherwise the default value
+ */
+function get(t, path, fallback) {
+    return parse(path).reduce((o, k) => o?.[k] ?? fallback, t);
+}
+/**
+ * Deeply set a value in an object by a path string.
+ *
+ * @template T - The type of the object to get the value from
+ * @param {T} t - The object to set the value in
+ * @param {string} path - The path string, e.g. `a.b.c`
+ * @param {any} value - The value to set at the specified path
+ * @returns {T} - The modified object with the value set at the specified path
+ * @throws {Error} - Throws an error if the key is not a valid identifier
+ */
+function set(t, path, value) {
+    // If the path is empty, return the value
+    if (path === '')
+        return value;
+    // Split the path into the first key and the rest of the path
+    const [k, ...r] = parse(path);
+    // Throw an error if the key is not a valid identifier
+    if (t !== undefined && (typeof t !== 'object' || t === null))
+        throw Error(`cannot set property <${k}> of <${JSON.stringify(t)}>`);
+    // Assign the value to the specified key in the object
+    return Object.assign(t ?? (typeof k === 'number' ? [] : Object.create(null)), {
+        [k]: set(t?.[k], r.join('.'), value)
+    });
+}
+/**
+ * Deeply merge two objects, where the second object overrides the first.
+ *
+ * @template T - The type of the object to get the value from
+ * @param {T} t - The target object to merge into
+ * @param {T} o - The source object to merge from
+ * @param {boolean} [mergeUndefined=false] - Whether to merge undefined values
+ * @returns {T} - The merged object
+ */
+function merge(t = Object.create(null), o = Object.create(null), mergeUndefined = false) {
+    // Iterate over the keys of the source object and merge them into the target object
+    return Object.keys(o).forEach(k => {
+        const val = o[k];
+        // If the value is undefined and mergeUndefined is false, skip it
+        if (!mergeUndefined && val === undefined)
+            return;
+        // Skip dangerous property names to prevent prototype pollution
+        if (k === '__proto__' || k === 'constructor')
+            return;
+        // If the value is an object and not an array, recursively merge it
+        t[k] = typeof val === 'object' && !Array.isArray(val)
+            ? merge(typeof t[k] === 'object' && !Array.isArray(t[k])
+                ? t[k] : Object.create(null), val)
+            : val;
+    }), t;
+}
+/**
+ * Delete a value at a specified path in an object.
+ *
+ * @template T - The type of the object to get the value from
+ * @param {T} t - The object to delete the value from
+ * @param {string} path - The path string, e.g. `a.b.c`
+ * @param {boolean} [preserveEmpty=false] - Whether to preserve empty objects/arrays
+ * @returns {T} - The modified object with the value deleted at the specified path
+ */
+function rmv(t, path, preserveEmpty = false) {
+    const r = (o, k, i = 0) => {
+        const key = k[i];
+        // Delete the key if it is not an object or if it is the last key in the path
+        if (!o || typeof o !== 'object')
+            return false;
+        if (i === k.length - 1)
+            return delete o[key];
+        if (!r(o[key], k, i + 1))
+            return false;
+        // If preserveEmpty is false, check if the object or array is empty
+        if (!preserveEmpty) {
+            const val = o[key];
+            // If the value is an empty array or object, delete the key
+            if (typeof val === 'object' && ((Array.isArray(val) && val.every(v => v == null)) ||
+                (!Array.isArray(val) && Object.keys(val).length === 0)))
+                delete o[key];
+        }
+        return true;
+    };
+    r(t, parse(path));
+    return t;
+}
+
+/**
+ * Profiler Utility
+ * src/utils/profiler.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Profiling_(computer_programming)
+ *
+ * This class provides methods to run synchronous and asynchronous functions, capturing
+ * their execution time and memory usage, and storing the results in a set of profiler
+ * entries. It supports both Node.js and browser environments, detecting the environment
+ * automatically.
+ *
+ * The class is optimized for minimal overhead and can be used for fine-grained
+ * performance profiling.
+ *
+ * @module Utils/Profiler
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * Profiler class for measuring execution time and memory usage of functions.
+ */
+class Profiler {
+    // Environment detection
+    static ENV;
+    // Singleton instance
+    static instance;
+    // Store for profiler entries
+    store = new Set();
+    // Total time and memory consumption
+    totalTime = 0;
+    totalMem = 0;
+    // The Profiler active state
+    active;
+    /**
+     * Sets the environment based on the available global objects.
+     * Detects if running in Node.js or browser and sets the ENV property accordingly.
+     */
+    static detectEnv() {
+        // Check for Node.js environment
+        if (typeof process !== 'undefined')
+            Profiler.ENV = 'nodejs';
+        // Check for browser environment
+        else if (typeof performance !== 'undefined')
+            Profiler.ENV = 'browser';
+        // If neither, set ENV to unknown
+        else
+            Profiler.ENV = 'unknown';
+    }
+    /**
+     * Returns the singleton instance of the Perf class.
+     * If the instance does not exist, it creates a new one.
+     *
+     * @param {boolean} [enable=false] - Optional parameter to enable the profiler upon instantiation
+     * @returns {Profiler} - Singleton Profiler instance
+     */
+    static getInstance(enable) {
+        // Ensure the environment is detected
+        if (!Profiler.ENV)
+            Profiler.detectEnv();
+        // If instance does not exist, create a new one
+        if (!Profiler.instance)
+            Profiler.instance = new Profiler(enable);
+        // Return singleton instance
+        return Profiler.instance;
+    }
+    /**
+     * Private constructor to enforce singleton pattern.
+     * Initializes the store for profiler entries.
+     *
+     * @param {boolean} [enable=false] - Optional parameter to enable the profiler
+     */
+    constructor(enable) { this.active = enable ?? false; }
+    /**
+     * Gets the current time based on the environment.
+     *
+     * Uses process.hrtime.bigint() for Node.js, performance.now() for browsers,
+     * and Date.now() as a fallback.
+     *
+     * @returns {number} - Current time in milliseconds
+     */
+    now() {
+        switch (Profiler.ENV) {
+            // Node.js environment
+            case 'nodejs': return Number(process.hrtime.bigint()) / 1e6;
+            // Browser environment
+            case 'browser': return performance.now();
+            // Fallback
+            default: return Date.now();
+        }
+    }
+    /**
+     * Gets the current memory usage based on the environment.
+     *
+     * Uses process.memoryUsage().heapUsed for Node.js, performance.memory.usedJSHeapSize
+     * for browsers, and returns 0 as a fallback.
+     *
+     * @returns {number} - Current memory usage in bytes
+     */
+    mem() {
+        switch (Profiler.ENV) {
+            // Node.js environment
+            case 'nodejs': return process.memoryUsage().heapUsed;
+            // Browser environment
+            case 'browser': return performance.memory?.usedJSHeapSize ?? 0;
+            // Fallback
+            default: return 0;
+        }
+    }
+    /**
+     * Enables the profiler.
+     * Sets the active state to true, allowing profiling to occur.
+     */
+    enable() { this.active = true; }
+    /**
+     * Disables the profiler.
+     * Sets the active state to false, preventing further profiling.
+     */
+    disable() { this.active = false; }
+    /**
+     * Resets the profiler by clearing the store, total time and memory consumption.
+     * This method is useful for starting a new profiling session.
+     */
+    clear() {
+        this.store.clear();
+        this.totalTime = 0;
+        this.totalMem = 0;
+    }
+    /**
+     * Runs a synchronous function and profiles its execution time and memory usage.
+     * If the profiler is not active, it simply executes the function without profiling.
+     *
+     * @param {() => T} fn - Function to be executed and profiled
+     * @param {Record<string, any>} meta - Metadata to be associated with the profiling entry
+     * @returns {T} - The result of the executed function
+     */
+    run(fn, meta = {}) {
+        // If the profiler is not active, simply execute the function without profiling
+        if (!this.active)
+            return fn();
+        // Capture the start time and memory usage
+        const startTime = this.now(), startMem = this.mem();
+        // Execute the function and capture the result
+        const res = fn();
+        // Calculate the time and memory consumption
+        const deltaTime = this.now() - startTime;
+        const deltaMem = this.mem() - startMem;
+        // Add the profiling entry to the store
+        this.store.add({ time: deltaTime, mem: deltaMem, res, meta });
+        this.totalTime += deltaTime, this.totalMem += deltaMem;
+        // Return the result of the function
+        return res;
+    }
+    /**
+     * Runs an asynchronous function and profiles its execution time and memory usage.
+     * If the profiler is not active, it simply executes the function without profiling.
+     *
+     * @param {() => Promise<T>} fn - Asynchronous function to be executed and profiled
+     * @param {Record<string, any>} meta - Metadata to be associated with the profiling entry
+     * @returns {Promise<T>} - A promise that resolves to the result of the executed function
+     */
+    async runAsync(fn, meta = {}) {
+        // If the profiler is not active, simply execute the function without profiling
+        if (!this.active)
+            return await fn();
+        // Capture the start time and memory usage
+        const startTime = this.now(), startMem = this.mem();
+        // Execute the asynchronous function and wait for its result
+        const res = await fn();
+        // Calculate the time and memory consumption
+        const deltaTime = this.now() - startTime;
+        const deltaMem = this.mem() - startMem;
+        // Add the profiling entry to the store
+        this.store.add({ time: deltaTime, mem: deltaMem, res, meta });
+        this.totalTime += deltaTime, this.totalMem += deltaMem;
+        // Return the result of the function
+        return res;
+    }
+    /**
+     * Retrieves all profiler entries stored in the profiler.
+     *
+     * @returns {ProfilerEntry<any>[]} - An array of profiler entries
+     */
+    getAll() { return [...this.store]; }
+    /**
+     * Retrieves the last profiler entry stored in the profiler.
+     *
+     * @returns {ProfilerEntry<any> | undefined} - The last profiler entry or undefined if no entries exist
+     */
+    getLast() { return this.getAll().pop(); }
+    /**
+     * Retrieves the total time and memory consumption recorded by the profiler.
+     *
+     * @returns {{ time: number, mem: number }} - An object containing total time and memory usage
+     */
+    getTotal() {
+        return {
+            time: this.totalTime, mem: this.totalMem
+        };
+    }
+    /**
+     * Returns the services provided by the Profiler class.
+     * This allows for easy access to the profiler's methods.
+     *
+     * @returns {ProfilerService<any>} - An object containing methods to control the profiler
+     */
+    services = {
+        enable: this.enable.bind(this),
+        disable: this.disable.bind(this),
+        clear: this.clear.bind(this),
+        report: this.getAll.bind(this),
+        last: this.getLast.bind(this),
+        total: this.getTotal.bind(this)
+    };
+}
+
+/**
+ * TextAnalyzer Utility
+ * src/utils/TextAnalyzer.ts
+ *
+ * The TextAnalyzer class provides a comprehensive set of methods for analyzing and
+ * extracting statistics from a given text. It supports word and sentence tokenization,
+ * character and word frequency analysis, syllable estimation, readability metrics
+ * (Flesch, Kincaid, LIX, WSTF), and various ratios and histograms. Designed for
+ * efficiency and flexibility, it is suitable for linguistic research, readability
+ * scoring, and text preprocessing tasks.
+ *
+ * @module Utils/TextAnalyzer
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+class TextAnalyzer {
+    // The original text to analyze
+    text;
+    // Tokenized words and sentences
+    words = [];
+    sentences = [];
+    // Frequency maps for characters and words
+    charFrequency = new Map();
+    wordHistogram = new Map();
+    syllableCache = new Map();
+    /**
+     * Constructs a new TextAnalyzer instance with the provided input text.
+     *
+     * @param {string} input - The text to analyze
+     */
+    constructor(input) {
+        this.text = input.trim();
+        this.tokenize();
+        this.computeFrequencies();
+    }
+    /**
+     * Tokenizes the input text into words and sentences.
+     */
+    tokenize() {
+        this.words = [], this.sentences = [];
+        const text = this.text;
+        const wordRegex = /\p{L}+/gu;
+        let match;
+        // Tokenize words using Unicode property escapes for letters
+        while ((match = wordRegex.exec(text)) !== null) {
+            this.words.push(match[0].toLowerCase());
+        }
+        // Tokenize sentences using punctuation marks as delimiters
+        this.sentences = text.split(/(?<=[.!?])\s+/).filter(Boolean);
+    }
+    /**
+     * Computes character and word frequencies from the tokenized text.
+     */
+    computeFrequencies() {
+        // Compute character frequencies
+        for (const char of this.text)
+            this.charFrequency.set(char, (this.charFrequency.get(char) ?? 0) + 1);
+        // Compute word frequencies
+        for (const word of this.words)
+            this.wordHistogram.set(word, (this.wordHistogram.get(word) ?? 0) + 1);
+    }
+    /**
+     * Estimates the number of syllables in a word using a simple heuristic.
+     *
+     * @param {string} word - The word to estimate syllables for
+     * @returns {number} - Estimated syllable count
+     */
+    estimateSyllables(word) {
+        // Check cache first to avoid redundant calculations
+        if (this.syllableCache.has(word))
+            return this.syllableCache.get(word);
+        // Normalize the word: lowercase and remove non-letter characters
+        const clean = word.toLowerCase().replace(/[^a-zäöüß]/g, '');
+        const matches = clean.match(/[aeiouyäöü]+/g);
+        // Count syllables based on vowel groups
+        const count = matches ? matches.length : 1;
+        this.syllableCache.set(word, count);
+        return count;
+    }
+    /**
+     * Gets the original text length in characters.
+     *
+     * @return {number} - Length of the text
+     */
+    getLength() { return this.text.length; }
+    /**
+     * Gets the number of words in the text.
+     *
+     * @return {number} - Count of words
+     */
+    getWordCount() { return this.words.length; }
+    /**
+     * Gets the number of sentences in the text.
+     *
+     * @return {number} - Count of sentences
+     */
+    getSentenceCount() { return this.sentences.length; }
+    /**
+     * Gets the average word length in the text.
+     *
+     * @return {number} - Average length of words
+     */
+    getAvgWordLength() {
+        let totalLen = 0;
+        for (const w of this.words)
+            totalLen += w.length;
+        return this.words.length ? totalLen / this.words.length : 0;
+    }
+    /**
+     * Gets the average sentence length in words.
+     *
+     * @return {number} - Average length of sentences
+     */
+    getAvgSentenceLength() {
+        return this.sentences.length ? this.words.length / this.sentences.length : 0;
+    }
+    /**
+     * Gets a histogram of word frequencies in the text.
+     *
+     * @returns {Record<string, number>} - A histogram of word frequencies
+     */
+    getWordHistogram() {
+        return Object.fromEntries(this.wordHistogram);
+    }
+    /**
+     * Gets the most common words in the text, limited to a specified number.
+     *
+     * @param {number} [limit=5] - Maximum number of common words to return
+     * @returns {string[]} - Array of the most common words
+     */
+    getMostCommonWords(limit = 5) {
+        return [...this.wordHistogram.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, limit).map(e => e[0]);
+    }
+    /**
+     * Gets the least common words (hapax legomena) in the text.
+     *
+     * Hapax legomena are words that occur only once in the text.
+     *
+     * @returns {string[]} - Array of hapax legomena
+     */
+    getHapaxLegomena() {
+        return [...this.wordHistogram.entries()]
+            .filter(([, c]) => c === 1)
+            .map(e => e[0]);
+    }
+    /**
+     * Checks if the text contains any numbers.
+     *
+     * @returns {boolean} - True if numbers are present, false otherwise
+     */
+    hasNumbers() { return /\d/.test(this.text); }
+    /**
+     * Calculates the ratio of uppercase letters to total letters in the text.
+     *
+     * @return {number} - Ratio of uppercase letters to total letters
+     */
+    getUpperCaseRatio() {
+        let upper = 0, letters = 0;
+        for (let i = 0, len = this.text.length; i < len; i++) {
+            const c = this.text[i];
+            if (/[A-Za-zÄÖÜäöüß]/.test(c)) {
+                letters++;
+                if (/[A-ZÄÖÜ]/.test(c))
+                    upper++;
+            }
+        }
+        return letters ? upper / letters : 0;
+    }
+    /**
+     * Gets the frequency of each character in the text.
+     *
+     * @returns {Record<string, number>} - A record of character frequencies
+     */
+    getCharFrequency() {
+        return Object.fromEntries(this.charFrequency);
+    }
+    /**
+     * Gets the frequency of each Unicode block in the text.
+     *
+     * @returns {Record<string, number>} - A record of Unicode block frequencies
+     */
+    getUnicodeStats() {
+        const result = {};
+        for (const [char, count] of this.charFrequency) {
+            // Get the Unicode block for the character
+            const block = char
+                .charCodeAt(0).toString(16)
+                .padStart(4, '0').toUpperCase();
+            // Increment the count for the block
+            result[block] = (result[block] ?? 0) + count;
+        }
+        return result;
+    }
+    /**
+     * Gets the ratio of long words (words with length >= len) to total words.
+     *
+     * @param {number} [len=7] - Minimum length for a word to be considered long
+     * @returns {number} - Ratio of long words to total words
+     */
+    getLongWordRatio(len = 7) {
+        let long = 0;
+        for (const w of this.words)
+            if (w.length >= len)
+                long++;
+        return this.words.length ? long / this.words.length : 0;
+    }
+    /**
+     * Gets the ratio of short words (words with length <= len) to total words.
+     *
+     * @param {number} [len=3] - Maximum length for a word to be considered short
+     * @returns {number} - Ratio of short words to total words
+     */
+    getShortWordRatio(len = 3) {
+        let short = 0;
+        for (const w of this.words)
+            if (w.length <= len)
+                short++;
+        return this.words.length ? short / this.words.length : 0;
+    }
+    /**
+     * Estimates the number of syllables in the text.
+     *
+     * @returns {number} - Total estimated syllable count
+     */
+    getSyllablesCount() {
+        let count = 0;
+        for (const w of this.words)
+            count += this.estimateSyllables(w);
+        return count;
+    }
+    /**
+     * Gets the number of monosyllabic words (words with exactly one syllable).
+     *
+     * @returns {number} - Count of monosyllabic words
+     */
+    getMonosyllabicWordCount() {
+        let count = 0;
+        for (const w of this.words)
+            if (this.estimateSyllables(w) === 1)
+                count++;
+        return count;
+    }
+    /**
+     * Gets the number of words with at least a specified minimum syllable count.
+     *
+     * @param {number} min - Minimum syllable count for a word to be included
+     * @returns {number} - Count of words meeting the syllable criteria
+     */
+    getMinSyllablesWordCount(min) {
+        let count = 0;
+        for (const w of this.words)
+            if (this.estimateSyllables(w) >= min)
+                count++;
+        return count;
+    }
+    /**
+     * Gets the number of words with at most a specified maximum syllable count.
+     *
+     * @param {number} max - Maximum syllable count for a word to be included
+     * @returns {number} - Count of words meeting the syllable criteria
+     */
+    getMaxSyllablesWordCount(max) {
+        let count = 0;
+        for (const w of this.words)
+            if (this.estimateSyllables(w) <= max)
+                count++;
+        return count;
+    }
+    /**
+     * Calculates the Honore's R statistic for the text as a measure of lexical richness.
+     *
+     * @returns {number} - The Honore's R statistic
+     */
+    getHonoresR() {
+        return (100 * Math.log(this.words.length)) / (1 - (this.getHapaxLegomena().length / (this.wordHistogram.size ?? 1)));
+    }
+    /**
+     * Estimates the reading time for the text based on words per minute (WPM).
+     *
+     * @param {number} [wpm=200] - Words per minute for the calculation
+     * @returns {number} - Estimated reading time in minutes
+     */
+    getReadingTime(wpm = 200) {
+        return Math.max(1, this.words.length / (wpm ?? 1));
+    }
+    /**
+     * Calculates various readability scores based on the text.
+     *
+     * This method supports multiple readability metrics:
+     *  - Flesch Reading Ease
+     *  - Flesch-Kincaid Grade Level
+     *
+     * @param {'flesch'|'fleschde'|'kincaid'} [metric='flesch'] - The readability metric to calculate
+     * @returns {number} - The calculated readability score
+     */
+    getReadabilityScore(metric = 'flesch') {
+        const w = this.words.length || 1;
+        const s = this.sentences.length || 1;
+        const y = this.getSyllablesCount() || 1;
+        const asl = w / s;
+        const asw = y / w;
+        switch (metric) {
+            // Flesch Reading Ease formula
+            case 'flesch': return 206.835 - (1.015 * asl) - (84.6 * asw);
+            // Flesch Reading Ease formula for German texts
+            case 'fleschde': return 180 - asl - (58.5 * asw);
+            // Flesch-Kincaid Grade Level formula
+            case 'kincaid': return (0.39 * asl) + (11.8 * asw) - 15.59;
+        }
+    }
+    /**
+     * Calculates the LIX (Lesbarhetsindex) score for the text.
+     *
+     * The LIX score is a readability index that combines average word length and sentence length.
+     *
+     * @returns {number} - The LIX score
+     */
+    getLIXScore() {
+        const w = this.words.length || 1;
+        const s = this.sentences.length || 1;
+        const l = this.getLongWordRatio() * w;
+        return (w / s) + (l / w * 100);
+    }
+    /**
+     * Calculates the Wiener Sachtextformel (WSTF) scores for the text.
+     *
+     * The WSTF scores are a set of readability metrics based on word and sentence characteristics.
+     *
+     * @returns {[number, number, number, number]} - An array of WSTF scores
+     */
+    getWSTFScore() {
+        const w = this.words.length || 1;
+        const h = this.getMinSyllablesWordCount(3) / w * 100;
+        const s = this.getAvgSentenceLength();
+        const l = this.getLongWordRatio() * 100;
+        const m = this.getMonosyllabicWordCount() / w * 100;
+        return [
+            0.1935 * h + 0.1672 * s + 0.1297 * l - 0.0327 * m - 0.8750,
+            0.2007 * h + 0.1682 * s + 0.1373 * l - 2.7790,
+            0.2963 * h + 0.1905 * s - 1.1144,
+            0.2744 * h + 0.2656 * s - 1.6930
+        ];
+    }
+}
+
+/**
+ * DiffChecker Utility
+ * src/utils/DiffChecker.ts
+ *
+ * The DiffChecker class provides a robust and efficient utility for comparing two
+ * texts and extracting their differences (full lines or word mode). It supports
+ * context-aware grouping of changes, unified diff output (with CLI color or ASCII
+ * markup), and detailed change magnitude metrics. The class is highly configurable,
+ * allowing users to choose the diff granularity, case sensitivity, context lines,
+ * grouping, and output style. It is suitable for text comparison, code review
+ * tools, document versioning, and any application requiring precise and human-
+ * readable difference reporting.
+ *
+ * Features:
+ *  - Line and word-based diffing
+ *  - Case-insensitive comparison option
+ *  - Context lines and grouping of adjacent changes
+ *  - Unified diff output (ASCII or colored CLI)
+ *  - Highlighting of changed segments within lines
+ *  - Change magnitude calculation (relative to group or line)
+ *  - Expand-all mode for full file context
+ *
+ * @module Utils/DiffChecker
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * The DiffChecker class provides methods to compare two texts and generate
+ * structured diffs, grouped diffs, and unified diff outputs.
+ */
+class DiffChecker {
+    // Original input texts and options
+    a;
+    b;
+    options;
+    // Computed diff entries and groups
+    entries = [];
+    grouped = [];
+    // Flag to indicate if the diff has already been computed
+    diffRun = false;
+    /**
+     * Constructs a new DiffChecker instance for comparing two texts.
+     *
+     * @param {string} a - The first (original) text
+     * @param {string} b - The second (modified) text
+     * @param {DiffOptions} [opt] - Optional diff configuration
+     */
+    constructor(a, b, opt = {}) {
+        // Set the two texts to compare
+        this.a = a, this.b = b;
+        // Merge default with user-provided options
+        this.options = { ...{
+                mode: 'word',
+                caseInsensitive: false,
+                contextLines: 1,
+                groupedLines: true,
+                expandLines: false,
+                showChangeMagnitude: true,
+                maxMagnitudeSymbols: 5,
+                lineBreak: '\n'
+            }, ...opt };
+        // Run the diff computation immediately
+        this.computeDiff();
+    }
+    /**
+     * Splits both input texts into arrays of lines and returns them
+     * with the maximum line count.
+     *
+     * @returns { linesA: string[], linesB: string[], maxLen: number }
+     */
+    text2lines() {
+        // Trim and split the input texts into lines
+        const linesA = this.a.trim().split(/\r?\n/);
+        const linesB = this.b.trim().split(/\r?\n/);
+        return { linesA, linesB, maxLen: Math.max(linesA.length, linesB.length) };
+    }
+    /**
+     * Tokenizes a string according to the current diff mode (line or word).
+     *
+     * @param {string} input - The string to tokenize
+     * @returns {string[]} - Array of tokens
+     */
+    tokenize(input) {
+        const { mode } = this.options;
+        switch (mode) {
+            // Tokenize by lines
+            case 'line': return [input];
+            // Tokenize by words
+            case 'word': return input.split(/\s+/);
+        }
+    }
+    /**
+     * Concatenates an array of tokens back into a string, respecting the diff mode.
+     *
+     * @param {string[]} input - Array of tokens
+     * @returns {string} - Concatenated string
+     */
+    concat(input) {
+        const { mode } = this.options;
+        return input.join(mode === 'word' ? ' ' : '');
+    }
+    /**
+     * Computes the diff between the two input texts and populates the
+     * entries and grouped arrays.
+     */
+    computeDiff() {
+        if (!this.diffRun) {
+            // Get the lines from both texts
+            const { linesA, linesB, maxLen } = this.text2lines();
+            // Loop through each line and compare them
+            for (let i = 0; i < maxLen; i++) {
+                const a = linesA[i] || '';
+                const b = linesB[i] || '';
+                // Perform line diffing
+                this.lineDiff(a, b, i);
+            }
+            // Find groups of adjacent changes
+            this.findGroups();
+            // Set the diff run flag to true
+            this.diffRun = true;
+        }
+    }
+    /**
+     * Compares two lines and records their differences at the configured granularity.
+     *
+     * @param {string} a - Line from the first text
+     * @param {string} b - Line from the second text
+     * @param {number} line - Line number
+     */
+    lineDiff(a, b, line) {
+        const { mode, caseInsensitive } = this.options;
+        const baseLen = Math.max(a.length, b.length);
+        let A = a, B = b;
+        // If case-insensitive mode is enabled, convert both lines to lowercase
+        if (caseInsensitive)
+            A = a.toLowerCase(), B = b.toLowerCase();
+        let diffs = [];
+        let delSize = 0, insSize = 0;
+        if (mode === 'line') {
+            // For line mode, compare the entire lines directly
+            if (A !== B) {
+                diffs.push({
+                    posA: 0, posB: 0,
+                    del: a, ins: b,
+                    size: b.length - a.length
+                });
+                delSize = a.length;
+                insSize = b.length;
+            }
+        }
+        else {
+            // For word mode, find precise diffs between tokenized lines
+            diffs = this.preciseDiff(a, A, b, B);
+            // Calculate total sizes of deletions and insertions
+            for (const d of diffs)
+                delSize += d.del.length, insSize += d.ins.length;
+        }
+        if (diffs.length) {
+            // Add the diff entry for this line
+            this.entries.push({
+                line, diffs, delSize, insSize, baseLen,
+                totalSize: insSize - delSize,
+                magnitude: this.magnitude(delSize, insSize, baseLen)
+            });
+        }
+    }
+    /**
+     * Finds all minimal diff blocks between two tokenized strings,
+     * returning original text and positions.
+     *
+     * @param {string} a - Original line (case preserved)
+     * @param {string} A - Original line (possibly lowercased)
+     * @param {string} b - Modified line (case preserved)
+     * @param {string} B - Modified line (possibly lowercased)
+     * @returns {DiffEntry[]} - Array of diff entries for this line
+     */
+    preciseDiff(a, A, b, B) {
+        // Helper function to calculate positions of tokens in the original text
+        const posIndex = (t) => t.reduce((p, _, i) => (p.push(i ? p[i - 1] + t[i - 1].length + 1 : 0), p), []);
+        // Original and tokenized arrays, their lengths and position arrays
+        const origA = this.tokenize(a);
+        const origB = this.tokenize(b);
+        const tokenA = this.tokenize(A);
+        const tokenB = this.tokenize(B);
+        const lenA = tokenA.length;
+        const lenB = tokenB.length;
+        const posArrA = posIndex(origA);
+        const posArrB = posIndex(origB);
+        // Find all matching blocks (LCS)
+        const matches = [];
+        let ai = 0, bi = 0;
+        while (ai < lenA && bi < lenB) {
+            // If tokens match, find the length of the match
+            if (tokenA[ai] === tokenB[bi]) {
+                let len = 1;
+                // Extend the match as long as tokens continue to match
+                while (ai + len < lenA && bi + len < lenB &&
+                    tokenA[ai + len] === tokenB[bi + len])
+                    len++;
+                matches.push({ ai, bi, len });
+                ai += len, bi += len;
+            }
+            else {
+                let found = false;
+                // Look ahead for next sync point (greedy, but avoids long tails)
+                for (let offset = 1; offset <= 3 && !found; offset++) {
+                    // Check if the next token in A matches the current token in B
+                    if (ai + offset < lenA && tokenA[ai + offset] === tokenB[bi]) {
+                        matches.push({ ai: ai + offset, bi, len: 1 });
+                        ai += offset + 1, bi += 1, found = true;
+                    }
+                    // Check if the next token in B matches the current token in A
+                    else if (bi + offset < lenB && tokenA[ai] === tokenB[bi + offset]) {
+                        matches.push({ ai, bi: bi + offset, len: 1 });
+                        ai += 1, bi += offset + 1, found = true;
+                    }
+                }
+                // If no match was found, advance both pointers by one
+                if (!found)
+                    ai++, bi++;
+            }
+        }
+        // Walk through tokens and emit diffs between matches
+        const diffs = [];
+        let i = 0, j = 0;
+        for (const m of matches) {
+            // If there are unmatched tokens before the match, record them
+            if (i < m.ai || j < m.bi) {
+                // Slice the original arrays to get the unmatched tokens
+                const delArr = origA.slice(i, m.ai);
+                const insArr = origB.slice(j, m.bi);
+                // Push the diff entry for unmatched tokens
+                diffs.push({
+                    posA: posArrA[i] ?? 0,
+                    posB: posArrB[j] ?? 0,
+                    del: this.concat(delArr),
+                    ins: this.concat(insArr),
+                    size: insArr.join('').length - delArr.join('').length
+                });
+            }
+            // Advance to after the match
+            i = m.ai + m.len, j = m.bi + m.len;
+        }
+        // Tail diffs after the last match
+        if (i < lenA || j < lenB) {
+            // Slice the original arrays to get the unmatched tokens
+            const delArr = origA.slice(i);
+            const insArr = origB.slice(j);
+            // Push the diff entry for unmatched tokens at the end
+            diffs.push({
+                posA: posArrA[i] ?? 0,
+                posB: posArrB[j] ?? 0,
+                del: this.concat(delArr),
+                ins: this.concat(insArr),
+                size: insArr.join('').length - delArr.join('').length
+            });
+        }
+        // Remove empty diffs
+        return diffs.filter(d => d.del.length > 0 || d.ins.length > 0);
+    }
+    /**
+     * Groups adjacent changed lines together, including context lines,
+     * and calculates group metrics.
+     */
+    findGroups() {
+        const { contextLines } = this.options;
+        // Helper function to add a group to the grouped array
+        const addGroup = (group, start, end) => {
+            // Calculate total sizes and base length for the group
+            const [delSize, insSize, totalSize, baseLen] = [
+                'delSize', 'insSize', 'totalSize', 'baseLen'
+            ].map(k => group.reduce((sum, e) => sum + e[k], 0));
+            // Push the group to the grouped array
+            this.grouped.push({
+                start, end, delSize, insSize, totalSize,
+                line: group[0].line, entries: group,
+                magnitude: this.magnitude(delSize, insSize, baseLen)
+            });
+        };
+        let group = [];
+        let start = 0, end = 0;
+        // Iterate through each diff entry to find groups
+        for (const entry of this.entries) {
+            const s = Math.max(0, entry.line - contextLines);
+            const e = entry.line + contextLines;
+            // If the group is empty or the current entry is adjacent to the last one
+            if (!group.length || s <= end + 1) {
+                // If this is the first entry, set the start position
+                if (!group.length)
+                    start = s;
+                end = Math.max(end, e);
+                group.push(entry);
+            }
+            else {
+                // If the group is not empty, finalize it and start a new one
+                addGroup(group, start, end);
+                group = [entry], start = s, end = e;
+            }
+        }
+        // If there is a remaining group, finalize it
+        if (group.length)
+            addGroup(group, start, end);
+    }
+    /**
+     * Calculates the change magnitude string for a group or line.
+     *
+     * @param {number} del - Number of deleted characters
+     * @param {number} ins - Number of inserted characters
+     * @param {number} baseLen - Base length for normalization
+     * @returns {string} - Magnitude string (e.g. "++-")
+     */
+    magnitude(del, ins, baseLen) {
+        const { maxMagnitudeSymbols } = this.options;
+        const total = del + ins;
+        // If there are no changes or base length is zero, return empty string
+        if (total === 0 || baseLen === 0)
+            return '';
+        // Calculate the length of the magnitude string based on the full length
+        const magLen = Math.min(maxMagnitudeSymbols, Math.max(Math.round(total / baseLen * maxMagnitudeSymbols), 1));
+        // Calculate the number of plus and minus symbols
+        const plus = Math.round((ins / total) * magLen);
+        const minus = magLen - plus;
+        // Return the magnitude string with plus and minus symbols
+        return '+'.repeat(plus) + '-'.repeat(minus);
+    }
+    /**
+     * Generates a unified diff output as a string, with optional CLI coloring.
+     *
+     * @param {boolean} cli - If true, use CLI colors; otherwise, ASCII markup
+     * @returns {string} - Unified diff output
+     */
+    output(cli) {
+        const { mode, contextLines, groupedLines, expandLines, showChangeMagnitude, lineBreak } = this.options;
+        // Get the lines and maximum length from the input texts
+        const { linesA, linesB, maxLen } = this.text2lines();
+        const linePad = Math.max(4, maxLen.toString().length);
+        // Helper functions for coloring and formatting (ASCII or CLI colored)
+        const highlight = (s, ansi) => cli ? `\x1b[${ansi}m${s}\x1b[0m` : s;
+        const cy = (s) => highlight(s, '36');
+        const gy = (s) => highlight(s, '90');
+        const gn = (s) => highlight(s, '32');
+        const rd = (s) => highlight(s, '31');
+        const ye = (s) => highlight(s, '33');
+        const del = (s) => cli ? `\x1b[37;41m${s}\x1b[31;49m` : `-[${s}]`;
+        const ins = (s) => cli ? `\x1b[37;42m${s}\x1b[32;49m` : `+[${s}]`;
+        // Function to output a block of lines with optional header
+        const block = (start, end, forced, headerEntry) => {
+            // If there is a header entry, output the header
+            if (headerEntry)
+                header(headerEntry);
+            // Loop through the range and output lines
+            for (let i = start; i <= end; i++)
+                line(i, forced ?? i);
+            out.push('');
+        };
+        // Function to output a header for a group or line
+        const header = (e) => {
+            out.push(`${(' '.repeat(linePad))}   ${(cy(`@@ -${(e.line + 1)},${e.delSize} +${(e.line + 1)},${e.insSize} @@`))} ${(showChangeMagnitude ? ye(e.magnitude) : '')}`);
+        };
+        // Function to output a single line with optional diff highlighting
+        const line = (i, forced) => {
+            // If the line exists in either text, output it
+            if (linesA[i] || linesB[i]) {
+                // Find the diff entry for this line, if it exists
+                const entry = this.entries.find(e => e.line === i);
+                // Format the line number with padding
+                const lineNo = (i + 1).toString().padStart(linePad, ' ');
+                if (entry && forced === i) {
+                    // If there is an entry, output the line with diff highlighting
+                    out.push(`${lineNo} ${rd(`- ${mark(linesA[i], entry.diffs, 'del')}`)}`);
+                    out.push(`${' '.repeat(linePad)} ${gn(`+ ${mark(linesB[i], entry.diffs, 'ins')}`)}`);
+                }
+                else {
+                    // If no entry, just output the line without diff (context lines)
+                    out.push(`${lineNo}   ${gy(linesA[i])}`);
+                }
+            }
+        };
+        // Function to mark changes in a line based on the diffs
+        const mark = (line, diffs, type) => {
+            // If there are no diffs or the mode is line, return the line as is
+            if (!diffs.length || mode === 'line')
+                return line;
+            let res = '', idx = 0;
+            // Loop through each diff entry and apply the changes
+            for (const d of diffs) {
+                // Get the position and value based on the type
+                const pos = type === 'del' ? d.posA : d.posB;
+                const val = type === 'del' ? d.del : d.ins;
+                // If the value is empty, skip it
+                if (!val)
+                    continue;
+                // Add the unchanged part of the line before the change
+                if (pos > idx)
+                    res += line.slice(idx, pos);
+                // Add the changed part of the line with appropriate formatting
+                res += (type === 'del' ? del(val) : ins(val));
+                idx = pos + val.length;
+            }
+            // Return the marked line with any remaining unchanged part
+            return res + line.slice(idx);
+        };
+        let out = [''];
+        switch (true) {
+            // For expandLines, output the entire file context
+            case expandLines:
+                block(0, maxLen);
+                break;
+            // For groupedLines, output each group with its start and end
+            case groupedLines:
+                for (const group of this.grouped)
+                    block(group.start, group.end, undefined, group);
+                break;
+            // For individual lines, output each entry with context lines
+            default:
+                for (const entry of this.entries)
+                    block(entry.line - contextLines, entry.line + contextLines, entry.line, entry);
+                break;
+        }
+        // Output the final diff as a string (ASCII or CLI colored)
+        return out.join(lineBreak);
+    }
+    /**
+     * Returns the structured diff as an array of DiffLine objects.
+     *
+     * @returns {DiffLine[]} - Array of line-level diffs
+     */
+    getStructuredDiff() { return this.entries; }
+    /**
+     * Returns the grouped diff as an array of DiffGroup objects.
+     *
+     * @returns {DiffGroup[]} - Array of grouped diffs
+     */
+    getGroupedDiff() { return this.grouped; }
+    /**
+     * Returns the unified diff as a plain ASCII string.
+     *
+     * @returns {string} - Unified diff (ASCII)
+     */
+    getASCIIDiff() { return this.output(false); }
+    /**
+     * Returns the unified diff as a CLI-colored string.
+     *
+     * @returns {string} - Unified diff (CLI colors)
+     */
+    getCLIDiff() { return this.output(true); }
+}
+
+/**
+ * Hash Table Utility
+ * src/utils/HashTable.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Fowler–Noll–Vo_hash_function
+ * @see https://en.wikipedia.org/wiki/Hash_table
+ *
+ * This module implements an instantiable hash table/cache using the FNV-1a hash algorithm.
+ * It allows for multiple independent caches (e.g. for metrics, normalization, etc.) with
+ * type safety and high performance. The FNV-1a algorithm is factored out into its own
+ * static utility class to avoid code duplication and memory overhead.
+ *
+ * The key() method supports any number of string arguments, enabling flexible cache keys
+ * for different use cases (e.g. normalization, metrics, etc.).
+ *
+ * @module Utils/HashTable
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * Hasher Utility
+ * Static class for FNV-1a hash calculation.
+ */
+class Hasher {
+    // Constants for the FNV-1a hash algorithm
+    static FNV_PRIME = 0x01000193;
+    static HASH_OFFSET = 0x811c9dc5;
+    /**
+     * Computes a hash value for a given string using the FNV-1a algorithm.
+     * Processes the string in chunks of 4 characters for better performance.
+     *
+     * @param {string} str - The string to hash
+     * @return {number} - The computed hash value as an unsigned 32-bit integer
+     */
+    static fnv1a(str) {
+        const len = str.length;
+        let hash = this.HASH_OFFSET;
+        // Process 4 characters at a time for better performance
+        const chunks = Math.floor(len / 4);
+        for (let i = 0; i < chunks; i++) {
+            const pos = i * 4;
+            // Combine 4 chars into a single number for faster processing
+            const chunk = ((str.charCodeAt(pos)) |
+                (str.charCodeAt(pos + 1) << 8) |
+                (str.charCodeAt(pos + 2) << 16) |
+                (str.charCodeAt(pos + 3) << 24));
+            hash ^= chunk;
+            hash *= this.FNV_PRIME;
+        }
+        // Handle remaining characters
+        const remaining = len % 4;
+        if (remaining > 0) {
+            const pos = chunks * 4;
+            for (let i = 0; i < remaining; i++) {
+                hash ^= str.charCodeAt(pos + i);
+                hash *= this.FNV_PRIME;
+            }
+        }
+        // Final mixing to improve distribution
+        hash ^= hash >>> 16;
+        hash *= 0x85ebca6b;
+        hash ^= hash >>> 13;
+        hash *= 0xc2b2ae35;
+        hash ^= hash >>> 16;
+        // Convert to unsigned 32-bit integer
+        return hash >>> 0;
+    }
+}
+/**
+ * HashTable class implements an instantiable hash table/cache.
+ * Allows for multiple independent caches with type safety and high performance.
+ *
+ * @template K - The type of the label for the key (e.g. string, MetricName, …)
+ * @template T - The type of value to be stored in the hash table (e.g. MetricCompute, string, …)
+ */
+class HashTable {
+    // The max. length of a string to hash, which is set to 2048 characters.
+    static MAX_LEN = 2048;
+    // The max. size of the hash table, which is set to 10,000.
+    static TABLE_SIZE = 10_000;
+    /**
+     * The internal map to store entries.
+     * The key is a string generated from the label and any number of hashed strings.
+     * The value is of type T.
+     */
+    table = new Map();
+    /**
+     * Generates a unique hash key for any number of string arguments.
+     * The key is in the format "label-H1-H2-H3-..."
+     *
+     * @param {K} label - Label for this key (e.g. metric name, normalization flags, …)
+     * @param {string[]} strs - Array of strings to hash (e.g. input, params, …)
+     * @param {boolean} [sorted=false] - Whether to sort the hashes before creating the key
+     * @returns {string|false} - A unique hash key or false if any string is too long
+     */
+    key(label, strs, sorted = false) {
+        // Return false if any string exceeds the maximum length
+        for (const str of strs) {
+            if (str.length > HashTable.MAX_LEN)
+                return false;
+        }
+        // Hash all strings
+        const hashes = strs.map(s => Hasher.fnv1a(s));
+        // Sort them in ascending order
+        if (sorted)
+            hashes.sort();
+        // Build key: label-H1-H2-H3-...
+        return [label, ...hashes].join('-');
+    }
+    /**
+     * Checks if a key exists in the hash table.
+     *
+     * @param {string} key - The key to check
+     * @returns {boolean} - True if the key exists, false otherwise
+     */
+    has(key) { return this.table.has(key); }
+    /**
+     * Retrieves the entry from the hash table by its key.
+     *
+     * @param {string} key - The key to look up
+     * @returns {T|undefined} - The entry if found, undefined otherwise
+     */
+    get(key) { return this.table.get(key); }
+    /**
+     * Adds an entry to the hash table.
+     *
+     * @param {string} key - The hashed key for the entry
+     * @param {T} entry - The entry itself to add
+     * @param {boolean} [update=true] - Whether to update the entry if it already exists
+     * @returns {boolean} - True if added successfully, false if the table is full
+     */
+    set(key, entry, update = true) {
+        // If the table is not full and the key does not exist or update is true, add the entry
+        if (this.table.size < HashTable.TABLE_SIZE && (update || !this.table.has(key))) {
+            this.table.set(key, entry);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Deletes an entry from the hash table by its key.
+     *
+     * @param {string} key - The key of the entry to delete
+     */
+    delete(key) { this.table.delete(key); }
+    /**
+     * Clears the hash table.
+     * This method removes all entries from the hash table.
+     */
+    clear() { this.table.clear(); }
+    /**
+     * Returns the current size of the hash table.
+     *
+     * @returns {number} - The number of entries in the hash table
+     */
+    size() { return this.table.size; }
+}
+
+/**
+ * Normalizer Utility
+ * src/utils/Normalizer.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Text_normalization
+ * @see https://en.wikipedia.org/wiki/Unicode_equivalence
+ *
+ * This module provides a Normalizer class that allows for string normalization based
+ * on various flags. It uses a pipeline of normalization functions that can be reused
+ * and cached for efficiency. The Normalizer can handle both single strings and arrays
+ * of strings, and supports synchronous and asynchronous normalization.
+ *
+ * Supported flags:
+ *  'd' :: Normalize to NFD (Normalization Form Decomposed)
+ *  'u' :: Normalize to NFC (Normalization Form Composed)
+ *  'x' :: Normalize to NFKC (Normalization Form Compatibility Composed)
+ *  'w' :: Collapse whitespace
+ *  't' :: Remove leading and trailing whitespace
+ *  'r' :: Remove double characters
+ *  's' :: Remove punctuation / special characters
+ *  'k' :: Remove non-letter characters
+ *  'n' :: Remove non-number characters
+ *  'i' :: Case insensitive (convert to lowercase)
+ *
+ * @module Utils/Normalizer
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * The Normalizer class providing methods to normalize strings based on various flags.
+ */
+class Normalizer {
+    /**
+     * A map that holds normalization functions based on the flags.
+     * This allows for reusing normalization logic without recomputing it.
+     */
+    static pipeline = new Map();
+    /**
+     * A cache to store normalized strings based on the flags and input.
+     * This helps avoid recomputing normalization for the same input and flags.
+     */
+    static cache = new HashTable();
+    /**
+     * Returns a normalization function based on the provided flags.
+     * The flags are a string of characters that define the normalization steps.
+     *
+     * @param {NormalizeFlags} flags - A string of characters representing the normalization steps
+     * @returns {NormalizerFn} - A function that normalizes a string based on the provided flags
+     */
+    static getPipeline(flags) {
+        // Return the cached pipeline if it exists
+        if (Normalizer.pipeline.has(flags))
+            return Normalizer.pipeline.get(flags);
+        // Define the normalization steps based on the flags
+        const steps = [];
+        // Normalize to NFD (Normalization Form Decomposed)
+        if (flags.includes('d'))
+            steps.push(str => str.normalize('NFD'));
+        // Normalize to NFC (Normalization Form Composed)
+        if (flags.includes('u'))
+            steps.push(str => str.normalize('NFC'));
+        // Normalize to NFKC (Normalization Form Compatibility Composed)
+        if (flags.includes('x'))
+            steps.push(str => str.normalize('NFKC'));
+        // Collapse whitespace
+        if (flags.includes('w'))
+            steps.push(str => str.replace(/\s+/g, ' '));
+        // Remove leading and trailing whitespace
+        if (flags.includes('t'))
+            steps.push(str => str.trim());
+        // Remove double characters
+        if (flags.includes('r'))
+            steps.push(str => str.replace(/(.)\1+/g, '$1'));
+        // Remove punctuation / special characters
+        if (flags.includes('s'))
+            steps.push(str => str.replace(/[^\p{L}\p{N}\s]/gu, ''));
+        // Remove non-letter characters
+        if (flags.includes('k'))
+            steps.push(str => str.replace(/[^\p{L}]/gu, ''));
+        // Remove non-number characters
+        if (flags.includes('n'))
+            steps.push(str => str.replace(/\p{N}/gu, ''));
+        // Case insensitive
+        if (flags.includes('i'))
+            steps.push(str => str.toLowerCase());
+        // Build the normalization function from the steps
+        const compiled = (input) => {
+            let res = input;
+            for (const step of steps)
+                res = step(res);
+            return res;
+        };
+        // Cache the compiled function for the given flags
+        Normalizer.pipeline.set(flags, compiled);
+        // Return the compiled normalization function
+        return compiled;
+    }
+    /**
+     * Normalizes the input string or array of strings based on the provided flags.
+     * The flags are a string of characters that define the normalization steps.
+     *
+     * @param {string|string[]} input - The string or array of strings to normalize
+     * @param {NormalizeFlags} flags - A string of characters representing the normalization steps
+     * @returns {string|string[]} - The normalized string(s)
+     */
+    static normalize(input, flags) {
+        // If input is an array, normalize each string in the array
+        if (Array.isArray(input))
+            return input.map(s => Normalizer.normalize(s, flags));
+        // If input or flags are not provided, return the input as is
+        if (!flags || typeof flags !== 'string' || !input)
+            return input;
+        // Generate a cache key based on the flags and input
+        const key = Normalizer.cache.key(flags, [input]);
+        // If the key exists in the cache, return the cached result
+        if (key && Normalizer.cache.has(key))
+            return Normalizer.cache.get(key);
+        // Normalize the input using the pipeline for the given flags
+        const res = Normalizer.getPipeline(flags)(input);
+        // If a key was generated, store the result in the cache
+        if (key)
+            Normalizer.cache.set(key, res);
+        // Return the normalized result
+        return res;
+    }
+    /**
+     * Asynchronously normalizes the input string or array of strings based on the
+     * provided flags. This method is useful for handling large inputs or when
+     * normalization needs to be done in a non-blocking way.
+     *
+     * @param {string|string[]} input - The string or array of strings to normalize
+     * @param {NormalizeFlags} flags - A string of characters representing the normalization steps
+     * @returns {Promise<string|string[]>} - A promise that resolves to the normalized string(s)
+     */
+    static async normalizeAsync(input, flags) {
+        return await (Array.isArray(input)
+            // If input is an array, normalize each string in the array asynchronously
+            ? Promise.all(input.map(s => Normalizer.normalize(s, flags)))
+            // If input is a single string, normalize it asynchronously
+            : Promise.resolve(Normalizer.normalize(input, flags)));
+    }
+    /**
+     * Clears the normalization pipeline and cache.
+     * This is useful for resetting the state of the Normalizer.
+     */
+    static clear() {
+        Normalizer.pipeline.clear();
+        Normalizer.cache.clear();
+    }
+}
+
+/**
+ * Filter Utility
+ * src/utils/Filter.ts
+ *
+ * This module provides a Filter class that allows for the management and application of
+ * filters to strings based on hooks. Filters can be added, removed, paused, resumed, and
+ * applied to input strings. Each filter has an id, a function, a priority, and options
+ * for activation and overrideability.
+ *
+ * @module Utils/Filter
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * The Filter class provides a way to manage and apply filters to strings based on hooks.
+ */
+class Filter {
+    /**
+     * A static map to hold all filters.
+     * The key is the hook name, and the value is an array of FilterEntry objects.
+     */
+    static filters = new Map();
+    /**
+     * Finds a filter by its hook and id.
+     *
+     * @param {string} hook - The name of the hook
+     * @param {string} id - The id of the filter
+     * @returns {FilterEntry|undefined} - The FilterEntry if found, otherwise undefined
+     */
+    static find(hook, id) {
+        return Filter.filters.get(hook)?.find(f => f.id === id);
+    }
+    /**
+     * Adds a filter to the specified hook.
+     *
+     * @param {string} hook - The name of the hook
+     * @param {string} id - The id of the filter
+     * @param {FilterFn} fn - The filter function
+     * @param {FilterOptions} [opt] - Additional options for the filter
+     * @returns {boolean} - Returns true if the filter was added, false if it was not added due to override restrictions
+     */
+    static add(hook, id, fn, opt = {}) {
+        const { priority = 10, active = true, overrideable = true } = opt;
+        // Check if the filter already exists
+        const filter = Filter.filters.get(hook) ?? [];
+        const index = filter.findIndex(f => f.id === id);
+        // If the filter already exists and is not overrideable, return false
+        if (index >= 0) {
+            const f = filter[index];
+            if (!f.overrideable)
+                return false;
+            filter.splice(index, 1);
+        }
+        // Add the new filter entry
+        filter.push({ id, fn, priority, active, overrideable });
+        // Sort the filters by priority
+        filter.sort((a, b) => a.priority - b.priority);
+        // Update the filters map
+        Filter.filters.set(hook, filter);
+        return true;
+    }
+    /**
+     * Removes a filter by its hook and id.
+     *
+     * @param {string} hook - The name of the hook
+     * @param {string} id - The id of the filter
+     * @returns {boolean} - Returns true if the filter was removed, false if it was not found
+     */
+    static remove(hook, id) {
+        // Get the filter array for the specified hook
+        const filter = Filter.filters.get(hook);
+        // If the filter array does not exist, return false
+        if (!filter)
+            return false;
+        // Find the index of the filter with the specified id
+        const index = filter.findIndex(f => f.id === id);
+        // If the filter is found, remove it and return true
+        if (index >= 0) {
+            filter.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Pauses a filter by its hook and id.
+     *
+     * @param {string} hook - The name of the hook
+     * @param {string} id - The id of the filter
+     * @returns {boolean} - Returns true if the filter was paused, false if it was not found
+     */
+    static pause(hook, id) {
+        // Find the filter entry by hook and id
+        const f = Filter.find(hook, id);
+        if (!f)
+            return false;
+        // Set the active property to false to pause the filter
+        f.active = false;
+        return true;
+    }
+    /**
+     * Resumes a filter by its hook and id.
+     *
+     * @param {string} hook - The name of the hook
+     * @param {string} id - The id of the filter
+     * @returns {boolean} - Returns true if the filter was resumed, false if it was not found
+     */
+    static resume(hook, id) {
+        // Find the filter entry by hook and id
+        const f = Filter.find(hook, id);
+        if (!f)
+            return false;
+        // Set the active property to true to resume the filter
+        f.active = true;
+        return true;
+    }
+    /**
+     * Lists all filters for a given hook.
+     *
+     * @param {string} hook - The name of the hook
+     * @param {boolean} active - If true, only list active filters
+     * @returns {string[]} - An array of filter ids
+     */
+    static list(hook, active = false) {
+        // Get the filter array for the specified hook
+        const filter = Filter.filters.get(hook) ?? [];
+        const list = [];
+        // If active is true, filter the entries based on their active status
+        for (const f of filter)
+            if (!active || f.active)
+                list.push(f.id);
+        return list;
+    }
+    /**
+     * Applies all active filters for a given hook to the input string(s).
+     *
+     * @param {string} hook - The name of the hook
+     * @param {string|string[]} input - The input string(s) to be filtered
+     * @returns {string|string[]} - The filtered string(s)
+     */
+    static apply(hook, input) {
+        // Get the filter array for the specified hook
+        const filter = Filter.filters.get(hook);
+        // If no filters are found for the hook or if no filters are active, return the input unchanged
+        if (!filter || filter.every(f => !f.active))
+            return input;
+        // Apply each active filter function to the given string
+        const applyOne = (s) => {
+            for (const f of filter)
+                if (f.active)
+                    s = f.fn(s);
+            return s;
+        };
+        // If the input is an array, apply the filter to each element, otherwise just once
+        return Array.isArray(input) ? input.map(applyOne) : applyOne(input);
+    }
+    /**
+     * Applies all active filters for a given hook to the input string(s) asynchronously.
+     * Each filter function may return a Promise or a plain string; all are awaited in order.
+     *
+     * @param {string} hook - The name of the hook
+     * @param {string|string[]} input - The input string(s) to be filtered
+     * @returns {Promise<string|string[]>} - The filtered string(s)
+     */
+    static async applyAsync(hook, input) {
+        // Get the filter array for the specified hook
+        const filter = Filter.filters.get(hook);
+        // If no filters are found for the hook or if no filters are active, return the input unchanged
+        if (!filter || filter.every(f => !f.active))
+            return input;
+        // Apply each active filter function to the given string
+        // Support both sync and async filter functions
+        const applyOne = async (s) => {
+            for (const f of filter)
+                if (f.active)
+                    s = await Promise.resolve(f.fn(s));
+            return s;
+        };
+        // If the input is an array, apply the filter to each element, otherwise just once
+        // Use Promise.all to handle multiple promises if input is an array
+        return Array.isArray(input) ? Promise.all(input.map(applyOne)) : applyOne(input);
+    }
+    /**
+     * Clears all filters or filters for a specific hook.
+     *
+     * @param {string} [hook] - Optional name of the hook to clear filters for
+     */
+    static clear(hook) {
+        // If a specific hook is provided, delete its filters
+        if (hook)
+            Filter.filters.delete(hook);
+        // If no hook is provided, clear all filters
+        else
+            Filter.filters.clear();
+    }
+}
+
+/**
+ * Registry Utility
+ * src/utils/Registry.ts
+ *
+ * This module provides a Registry function that allows for registering,
+ * removing, checking, getting, and listing class constructors.
+ *
+ * It is designed to manage class extensions, ensuring that all registered
+ * classes extend a specified base constructor.
+ *
+ * @module Utils/Registry
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * Global registry object to hold multiple registries.
+ * Each registry is keyed by a string identifier.
+ *
+ * @type {Record<string, RegistryService<any>>}
+ */
+const registry = Object.create(null);
+/**
+ * Factory object to hold factory functions for creating instances.
+ * This is used to create instances of registered classes.
+ *
+ * @type {Record<string, ( cls: string, ...args: any[] ) => InstanceType<any>>}
+ */
+const factory = Object.create(null);
+/**
+ * Registry function to create a service for managing class constructors.
+ *
+ * @param {string} reg - The name of the registry
+ * @param {RegistryConstructor<T>} ctor - The base constructor that all registered classes must extend
+ * @returns {RegistryService<T>} - An object with methods to register, remove, check, get, and list classes
+ * @throws {Error} If the registry already exists (overwriting is forbidden)
+ */
+function Registry(reg, ctor) {
+    // Throws an error if the registry already exists
+    if (reg in registry || reg in factory)
+        throw new Error(`registry <${reg}> already exists / overwriting is forbidden`);
+    // Create a registry object to hold class constructors
+    const classes = Object.create(null);
+    const service = {
+        /**
+         * Register a new extension of the base class.
+         *
+         * @param {string} name - The name of the class to register
+         * @param {RegistryConstructor<T>} cls - The class constructor
+         * @param {boolean} [update=false] - Whether to allow overwriting an existing entry
+         * @throws {TypeError} If the class does not extend the base constructor
+         * @throws {Error} If the class name already exists and update is false
+         */
+        add(name, cls, update = false) {
+            if (!(cls.prototype instanceof ctor))
+                throw new TypeError(`class must extend <${reg}>`);
+            if (!update && name in classes)
+                throw new Error(`entry <${name}> already exists / use <update=true> to overwrite`);
+            classes[name] = cls;
+        },
+        /**
+         * Remove a class from the registry.
+         *
+         * @param {string} name - The name of the class to remove
+         */
+        remove(name) { delete classes[name]; },
+        /**
+         * Check if a class is registered.
+         *
+         * @param {string} name - The name of the class to check
+         * @returns {boolean} - True if the class is registered, false otherwise
+         */
+        has(name) { return name in classes; },
+        /**
+         * List all registered class names.
+         *
+         * @returns {string[]} - An array of registered class names
+         */
+        list() { return Object.keys(classes); },
+        /**
+         * Get a registered class by name.
+         *
+         * @param {string} name - The name of the class to retrieve
+         * @returns {RegistryConstructor<T>} - The class constructor
+         * @throws {Error} If the class is not registered
+         */
+        get(name) {
+            if (!(name in classes))
+                throw new Error(`class <${name}> not registered for <${reg}>`);
+            return classes[name];
+        }
+    };
+    // Register the service in the global registry
+    registry[reg] = service;
+    // Create a factory function for creating instances from the registry
+    factory[reg] = (cls, ...args) => (createFromRegistry(reg, cls, ...args));
+    // Return the service object
+    return service;
+}
+/**
+ * Resolve a class constructor from a specific registry.
+ *
+ * @param {string} reg - The name of the registry
+ * @param {T|string} cls - The class itself or name of the class to resolve
+ * @returns {T|undefined} - The class constructor if found, otherwise undefined
+ * @throws {ReferenceError} If the registry does not exist
+ */
+function resolveCls(reg, cls) {
+    if (!(reg in registry))
+        throw new ReferenceError(`registry <${reg}> does not exist`);
+    return (typeof cls === 'string' ? registry[reg]?.get(cls) : cls);
+}
+/**
+ * Create an instance of a class from a specific registry.
+ *
+ * @param {string} reg - The name of the registry
+ * @param {T|string} cls - The class itself or name of the class to instantiate
+ * @param {...any} args - Arguments to pass to the class constructor
+ * @returns {T} - An instance of the class
+ * @throws {Error} If the class cannot be instantiated
+ */
+function createFromRegistry(reg, cls, ...args) {
+    cls = resolveCls(reg, cls);
+    try {
+        return new cls(...args);
+    }
+    catch (err) {
+        throw new Error(`cannot instantiate class <${cls}>`);
+    }
+}
+
+/**
+ * Abstract Metric
+ * src/metric/Metric.ts
+ *
+ * This module defines an abstract class for string metrics, providing a framework for
+ * computing various string similarity metrics. It includes methods for running metrics
+ * in different modes (single, batch, pairwise) synchronous or asynchronous and caching
+ * results to optimize performance. The class is designed to be extended by specific
+ * metric implementations like the Levenshtein distance or Jaro-Winkler similarity.
+ *
+ * It provides:
+ *  - A base class for string metrics with common functionality
+ *  - Methods for running metrics in different modes
+ *  - Pre-computation for trivial cases to optimize performance
+ *  - Caching of metric computations to avoid redundant calculations
+ *  - Support for symmetrical metrics (same result for inputs in any order)
+ *  - Performance tracking capabilities (Profiler)
+ *  - Asynchronous execution support for metrics
+ *
+ * This class is intended to be extended by specific metric implementations that will
+ * implement the `compute` method to define the specific metric computation logic.
+ *
+ * @module Metric
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+// Get the singleton profiler instance for performance monitoring
+const profiler$2 = Profiler.getInstance();
+/**
+ * Abstract class representing a generic string metric.
+ *
+ * @abstract
+ * @template R - The type of the raw result, defaulting to `MetricRaw`.
+ */
+class Metric {
+    // Cache for metric computations to avoid redundant calculations
+    static cache = new HashTable();
+    // Metric name for identification
+    metric;
+    // Inputs for the metric computation, transformed into arrays
+    a;
+    b;
+    // Store original inputs for result mapping
+    origA = [];
+    origB = [];
+    // Options for the metric computation, such as performance tracking
+    options;
+    // Indicates whether the metric is symmetric (same result for inputs in any order)
+    symmetric;
+    /**
+     * Result of the metric computation, which can be a single result or an array of results.
+     * This will be populated after running the metric.
+     */
+    results;
+    /**
+     * Static method to clear the cache of metric computations.
+     */
+    static clear() { this.cache.clear(); }
+    /**
+     * Swaps two strings and their lengths if the first is longer than the second.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @returns {[string, string, number, number]} - Swapped strings and lengths
+     */
+    static swap(a, b, m, n) { return m > n ? [b, a, n, m] : [a, b, m, n]; }
+    /**
+     * Clamps the similarity result between 0 and 1.
+     *
+     * @param {number} res - The input similarity to clamp
+     * @returns {number} - The clamped similarity (0 to 1)
+     */
+    static clamp(res) { return Math.max(0, Math.min(1, res)); }
+    /**
+     * Constructor for the Metric class.
+     * Initializes the metric with two inputs (strings or arrays of strings) and options.
+     *
+     * @param {string} metric - The name of the metric (e.g. 'levenshtein')
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     * @param {boolean} [symmetric=false] - Whether the metric is symmetric (same result for inputs in any order)
+     * @throws {Error} - If inputs `a` or `b` are empty
+     */
+    constructor(metric, a, b, opt = {}, symmetric = false) {
+        // Set the metric name
+        this.metric = metric;
+        // Set the inputs
+        this.a = Array.isArray(a) ? a : [a];
+        this.b = Array.isArray(b) ? b : [b];
+        // Validate inputs: ensure they are not empty
+        if (this.a.length === 0 || this.b.length === 0)
+            throw new Error(`inputs <a> and <b> must not be empty`);
+        // Set options
+        this.options = opt;
+        this.symmetric = symmetric;
+    }
+    /**
+     * Pre-compute the metric for two strings.
+     * This method is called before the actual computation to handle trivial cases.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @returns {MetricCompute<R>|undefined} - Pre-computed result or undefined if not applicable
+     */
+    preCompute(a, b, m, n) {
+        // If strings are identical, return a similarity of 1
+        if (a === b)
+            return { res: 1 };
+        // If the lengths of both strings is less than 2, return a similarity of 0
+        if (m == 0 || n == 0 || (m < 2 && n < 2))
+            return { res: 0 };
+        return undefined;
+    }
+    /**
+     * Abstract method to be implemented by subclasses to perform the metric computation.
+     * This method should contain the logic for computing the metric between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @param {number} maxLen - Maximum length of the strings
+     * @returns {MetricCompute<R>} - The result of the metric computation
+     * @throws {Error} - If not overridden in a subclass
+     */
+    compute(a, b, m, n, maxLen) {
+        throw new Error(`method compute() must be overridden in a subclass`);
+    }
+    /**
+     * Run the metric computation for single inputs (two strings).
+     * Applies preCompute for trivial cases before cache lookup and computation.
+     *
+     * If the profiler is active, it will measure time and memory usage.
+     *
+     * @param {number} i - Pointer to the first string
+     * @param {number} j - Pointer to the second string
+     * @returns {MetricResultSingle<R>} - The result of the metric computation
+     */
+    runSingle(i, j) {
+        // Type safety: convert inputs to strings
+        let a = String(this.a[i]), A = a;
+        let b = String(this.b[j]), B = b;
+        // Get lengths
+        let m = A.length, n = B.length;
+        // Pre-compute trivial cases (identical, empty, etc.)
+        let result = this.preCompute(A, B, m, n);
+        if (!result) {
+            // If the profiler is enabled, measure; else, just run
+            result = profiler$2.run(() => {
+                // Generate a cache key based on the metric and pair of strings `a` and `b`
+                const key = Metric.cache.key(this.metric, [A, B], this.symmetric);
+                // If the key exists in the cache, return the cached result
+                // Otherwise, compute the metric using the algorithm
+                return Metric.cache.get(key || '') ?? (() => {
+                    // If the metric is symmetrical, swap `a` and `b` (shorter string first)
+                    if (this.symmetric)
+                        [A, B, m, n] = Metric.swap(A, B, m, n);
+                    // Compute the similarity using the algorithm
+                    const res = this.compute(A, B, m, n, Math.max(m, n));
+                    // If a key was generated, store the result in the cache
+                    if (key)
+                        Metric.cache.set(key, res);
+                    return res;
+                })();
+            });
+        }
+        // Build metric result object
+        return {
+            metric: this.metric,
+            a: this.origA[i] ?? a,
+            b: this.origB[j] ?? b,
+            ...result
+        };
+    }
+    /**
+     * Run the metric computation for single inputs (two strings) asynchronously.
+     *
+     * @param {number} i - Pointer to the first string
+     * @param {number} j - Pointer to the second string
+     * @returns {Promise<MetricResultSingle<R>>} - Promise resolving the result of the metric computation
+     */
+    async runSingleAsync(i, j) {
+        return Promise.resolve(this.runSingle(i, j));
+    }
+    /**
+     * Run the metric computation for batch inputs (arrays of strings).
+     *
+     * It iterates through each string in the first array and computes the metric
+     * against each string in the second array.
+     */
+    runBatch() {
+        const results = [];
+        // Loop through each combination of strings in a[] and b[]
+        for (let i = 0; i < this.a.length; i++)
+            for (let j = 0; j < this.b.length; j++)
+                results.push(this.runSingle(i, j));
+        // Populate the results
+        // `this.results` will be an array of MetricResultSingle
+        this.results = results;
+    }
+    /**
+     * Run the metric computation for batch inputs (arrays of strings) asynchronously.
+     */
+    async runBatchAsync() {
+        const results = [];
+        // Loop through each combination of strings in a[] and b[]
+        for (let i = 0; i < this.a.length; i++)
+            for (let j = 0; j < this.b.length; j++)
+                results.push(await this.runSingleAsync(i, j));
+        // Populate the results
+        // `this.results` will be an array of MetricResultSingle
+        this.results = results;
+    }
+    /**
+     * Run the metric computation for pairwise inputs (A[i] vs B[i]).
+     *
+     * This method assumes that both `a` and `b` are arrays of equal length
+     * and computes the metric only for corresponding index pairs.
+     */
+    runPairwise() {
+        const results = [];
+        // Compute metric for each corresponding pair
+        for (let i = 0; i < this.a.length; i++)
+            results.push(this.runSingle(i, i));
+        // Populate the results
+        // `this.results` will be an array of MetricResultSingle
+        this.results = results;
+    }
+    /**
+     * Run the metric computation for pairwise inputs (A[i] vs B[i]) asynchronously.
+     */
+    async runPairwiseAsync() {
+        const results = [];
+        // Compute metric for each corresponding pair
+        for (let i = 0; i < this.a.length; i++)
+            results.push(await this.runSingleAsync(i, i));
+        // Populate the results
+        // `this.results` will be an array of MetricResultSingle
+        this.results = results;
+    }
+    /**
+     * Set the original inputs to which the results of the metric calculation will refer.
+     *
+     * @param {MetricInput} [a] - original input(s) for a
+     * @param {MetricInput} [b] - original input(s) for b
+     */
+    setOriginal(a, b) {
+        if (a)
+            this.origA = Array.isArray(a) ? a : [a];
+        if (b)
+            this.origB = Array.isArray(b) ? b : [b];
+        return this;
+    }
+    /**
+     * Check if the inputs are in batch mode.
+     *
+     * This method checks if either `a` or `b` contains more than one string,
+     * indicating that the metric is being run in batch mode.
+     *
+     * @returns {boolean} - True if either input is an array with more than one element
+     */
+    isBatch() { return this.a.length > 1 || this.b.length > 1; }
+    /**
+     * Check if the inputs are in single mode.
+     *
+     * This method checks if both `a` and `b` are single strings (not arrays),
+     * indicating that the metric is being run on a single pair of strings.
+     *
+     * @returns {boolean} - True if both inputs are single strings
+     */
+    isSingle() { return !this.isBatch(); }
+    /**
+     * Check if the inputs are in pairwise mode.
+     *
+     * This method checks if both `a` and `b` are arrays of the same length,
+     * indicating that the metric is being run on corresponding pairs of strings.
+     *
+     * @returns {boolean} - True if both inputs are arrays of equal length
+     * @param {boolean} [safe=false] - If true, does not throw an error if lengths are not equal
+     * @throws {Error} - If `safe` is false and the lengths of `a` and `b` are not equal
+     */
+    isPairwise(safe = false) {
+        return this.isBatch() && this.a.length === this.b.length ? true : !safe && (() => {
+            throw new Error(`mode <pairwise> requires arrays of equal length`);
+        })();
+    }
+    /**
+     * Check if the metric is symmetrical.
+     *
+     * This method returns whether the metric is symmetric, meaning it produces the same
+     * result regardless of the order of inputs (e.g., Levenshtein distance).
+     *
+     * @returns {boolean} - True if the metric is symmetric
+     */
+    isSymmetrical() { return this.symmetric; }
+    /**
+     * Determine which mode to run the metric in.
+     *
+     * This method checks the provided mode or defaults to the mode specified in options.
+     * If no mode is specified, it defaults to 'default'.
+     *
+     * @param {MetricMode} [mode] - The mode to run the metric in (optional)
+     * @returns {MetricMode} - The determined mode
+     */
+    whichMode(mode) { return mode ?? this.options?.mode ?? 'default'; }
+    /**
+     * Clear the cached results of the metric.
+     *
+     * This method resets the `results` property to `undefined`, effectively clearing
+     * any previously computed results. It can be useful for re-running the metric
+     * with new inputs or options.
+     */
+    clear() { this.results = undefined; }
+    /**
+     * Run the metric computation based on the specified mode.
+     *
+     * @param {MetricMode} [mode] - The mode to run the metric in (optional)
+     * @param {boolean} [clear=true] - Whether to clear previous results before running
+     * @throws {Error} - If an unsupported mode is specified
+     */
+    run(mode, clear = true) {
+        // Clear previous results if requested
+        if (clear)
+            this.clear();
+        switch (this.whichMode(mode)) {
+            // Default mode runs the metric on single inputs or falls back to batch mode
+            case 'default': if (this.isSingle()) {
+                this.results = this.runSingle(0, 0);
+                break;
+            }
+            // Batch mode runs the metric on all combinations of a[] and b[]
+            case 'batch':
+                this.runBatch();
+                break;
+            // Single mode runs the metric on the first elements of a[] and b[]
+            case 'single':
+                this.results = this.runSingle(0, 0);
+                break;
+            // Pairwise mode runs the metric on corresponding pairs of a[] and b[]
+            case 'pairwise':
+                if (this.isPairwise())
+                    this.runPairwise();
+                break;
+            // Unsupported mode
+            default: throw new Error(`unsupported mode <${mode}>`);
+        }
+    }
+    /**
+     * Run the metric computation based on the specified mode asynchronously.
+     *
+     * @param {MetricMode} [mode] - The mode to run the metric in (optional)
+     * @param {boolean} [clear=true] - Whether to clear previous results before running
+     * @returns {Promise<void>} - A promise that resolves when the metric computation is complete
+     * @throws {Error} - If an unsupported mode is specified
+     */
+    async runAsync(mode, clear = true) {
+        // Clear previous results if requested
+        if (clear)
+            this.clear();
+        switch (this.whichMode(mode)) {
+            // Default mode runs the metric on single inputs or falls back to batch mode
+            case 'default': if (this.isSingle()) {
+                this.results = await this.runSingleAsync(0, 0);
+                break;
+            }
+            // Batch mode runs the metric on all combinations of a[] and b[]
+            case 'batch':
+                await this.runBatchAsync();
+                break;
+            // Single mode runs the metric on the first elements of a[] and b[]
+            case 'single':
+                this.results = await this.runSingleAsync(0, 0);
+                break;
+            // Pairwise mode runs the metric on corresponding pairs of a[] and b[]
+            case 'pairwise':
+                if (this.isPairwise())
+                    await this.runPairwiseAsync();
+                break;
+            // Unsupported mode
+            default: throw new Error(`unsupported async mode <${mode}>`);
+        }
+    }
+    /**
+     * Get the name of the metric.
+     *
+     * @returns {string} - The name of the metric
+     */
+    getMetricName() { return this.metric; }
+    /**
+     * Get the result of the metric computation.
+     *
+     * @returns {MetricResult<R>} - The result of the metric computation
+     * @throws {Error} - If `run()` has not been called before this method
+     */
+    getResults() {
+        // Ensure that the metric has been run before getting the result
+        if (this.results === undefined)
+            throw new Error(`run() must be called before getResult()`);
+        // Return the result(s)
+        return this.results;
+    }
+}
+/**
+ * Metric registry service for managing metric implementations.
+ *
+ * This registry allows for dynamic registration and retrieval of metric classes,
+ * enabling the use of various string similarity metrics in a consistent manner.
+ */
+const MetricRegistry = Registry('metric', Metric);
+
+/**
+ * Pool Utility
+ * src/utils/Pool.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Circular_buffer
+ *
+ * The Pool class provides a simple and efficient buffer pool for dynamic programming
+ * algorithms that require temporary arrays (such as Levenshtein, LCS, etc.).
+ * By reusing pre-allocated typed arrays, it reduces memory allocations and garbage
+ * collection overhead, especially for repeated or batch computations.
+ *
+ * It supports different types of buffers (Uint16Array, number[], Set, Map) and allows
+ * for acquiring buffers of specific sizes while managing a maximum pool size.
+ *
+ * @module Utils/Pool
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * RingPool is a circular buffer implementation that manages a pool of buffers.
+ *
+ * It allows for efficient acquisition and release of buffers, ensuring that
+ * buffers are reused without unnecessary allocations.
+ *
+ * @template T - The type of buffers managed by the pool
+ */
+class RingPool {
+    maxSize;
+    // The buffers in the pool
+    buffers = [];
+    // The current pointer for acquiring buffers
+    pointer = 0;
+    /**
+     * Creates a new RingPool with a specified maximum size.
+     *
+     * @param {number} maxSize - The maximum number of buffers that can be stored in the pool
+     */
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+    }
+    /**
+     * Acquires a buffer of at least the specified minimum size from the pool.
+     *
+     * @param {number} minSize - The minimum size of the buffer to acquire
+     * @param {boolean} allowOversize - Whether to allow buffers larger than minSize
+     * @return {PoolBuffer<T>|null} - The acquired buffer or null if no suitable buffer is found
+     */
+    acquire(minSize, allowOversize) {
+        const len = this.buffers.length;
+        // Iterate through the buffers in the pool
+        for (let i = 0; i < len; i++) {
+            const idx = (this.pointer + i) % len;
+            const item = this.buffers[idx];
+            // Check if the item size is greater than or equal to the minimum size
+            if (item.size >= minSize) {
+                // Set the pointer to the next position
+                this.pointer = (idx + 1) % len;
+                // If the item size is equal to minSize or oversize is allowed, return the item
+                return allowOversize || item.size === minSize ? item : null;
+            }
+        }
+        // If no suitable buffer is found, return null
+        return null;
+    }
+    /**
+     * Releases a buffer back to the pool.
+     * If the pool is full, it replaces the oldest buffer with the new one.
+     *
+     * @param {PoolBuffer<T>} item - The buffer to release back to the pool
+     */
+    release(item) {
+        if (this.buffers.length < this.maxSize) {
+            // If the pool is not full, simply add the item
+            this.buffers.push(item);
+        }
+        else {
+            // If the pool is full, replace the oldest buffer
+            this.buffers[this.pointer] = item;
+            this.pointer = (this.pointer + 1) % this.maxSize;
+        }
+    }
+    /**
+     * Clears the pool, removing all buffers.
+     * This resets the pointer and empties the buffer list.
+     */
+    clear() {
+        this.buffers = [];
+        this.pointer = 0;
+    }
+}
+/**
+ * The Pool class provides a buffer pool for dynamic programming algorithms.
+ *
+ * It allows for efficient reuse of buffers (Uint16Array, number[], Set, Map)
+ * to reduce memory allocations and garbage collection overhead.
+ */
+class Pool {
+    // Pool Types
+    static CONFIG = {
+        'uint16': { type: 'uint16', maxSize: 32, maxItemSize: 2048, allowOversize: true },
+        'number[]': { type: 'number[]', maxSize: 16, maxItemSize: 1024, allowOversize: false },
+        'set': { type: 'set', maxSize: 8, maxItemSize: 0, allowOversize: false },
+        'map': { type: 'map', maxSize: 8, maxItemSize: 0, allowOversize: false }
+    };
+    // Pool Rings for each type
+    static POOLS = {
+        'uint16': new RingPool(32),
+        'number[]': new RingPool(16),
+        'set': new RingPool(8),
+        'map': new RingPool(8)
+    };
+    /**
+     * Allocates a new buffer of the specified type and size.
+     *
+     * @param {PoolType} type - The type of buffer to allocate
+     * @param {number} size - The size of the buffer to allocate
+     * @return {any} - The newly allocated buffer
+     */
+    static allocate(type, size) {
+        switch (type) {
+            case 'uint16': return new Uint16Array(size);
+            case 'number[]': return new Array(size).fill(0);
+            case 'set': return new Set();
+            case 'map': return new Map();
+        }
+    }
+    /**
+     * Acquires a buffer of the specified type and size from the pool.
+     * If no suitable buffer is available, it allocates a new one.
+     *
+     * @param {PoolType} type - The type of buffer to acquire (e.g., 'uint16', 'number[]', 'set', 'map')
+     * @param {number} size - The size of the buffer to acquire
+     * @return {T} - The acquired buffer of the specified type
+     */
+    static acquire(type, size) {
+        // Get the configuration for the specified type
+        const CONFIG = this.CONFIG[type];
+        // If the requested size exceeds the maximum item size, allocate a new buffer
+        if (size > CONFIG.maxItemSize)
+            return this.allocate(type, size);
+        // Try to acquire a buffer from the pool ring
+        // If a suitable buffer is found, return it (subarray for uint16)
+        const item = this.POOLS[type].acquire(size, CONFIG.allowOversize);
+        if (item) {
+            // If the type is 'uint16', return a subarray of the buffer
+            return type === 'uint16' ? item.buffer.subarray(0, size) : item.buffer;
+        }
+        // If no suitable buffer is found, allocate a new one
+        return this.allocate(type, size);
+    }
+    /**
+     * Acquires multiple buffers of the specified type and sizes from the pool.
+     *
+     * @param {PoolType} type - The type of buffers to acquire
+     * @param {number[]} sizes - An array of sizes for each buffer to acquire
+     * @return {T[]} - An array of acquired buffers of the specified type
+     */
+    static acquireMany(type, sizes) {
+        return sizes.map(size => this.acquire(type, size));
+    }
+    /**
+     * Releases a buffer back to the pool.
+     * If the size of the buffer is larger than the maximum item size, it will not be released.
+     *
+     * @param {PoolType} type - The type of buffer to release
+     * @param {T} buffer - The buffer to release
+     * @param {number} size - The size of the buffer
+     */
+    static release(type, buffer, size) {
+        // Get the configuration for the specified type
+        const CONFIG = this.CONFIG[type];
+        // If the size of the buffer is less than or equal to the maximum item size, release it
+        if (size <= CONFIG.maxItemSize) {
+            // Release the buffer back to the pool ring
+            this.POOLS[type].release({ buffer, size });
+        }
+    }
+}
+
+/**
+ * Cosine Similarity
+ * src/metric/Cosine.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Cosine_similarity
+ *
+ * Cosine similarity is a metric used to measure how similar two vectors are, regardless
+ * of their magnitude. In text analysis, it is commonly used to compare documents or
+ * strings by representing them as term frequency vectors and computing the cosine of
+ * the angle between these vectors.
+ *
+ * The result is a value between 0 and 1, where 1 means the vectors are identical and
+ * 0 means they are orthogonal (no similarity).
+ *
+ * @module Metric/CosineSimilarity
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * CosineSimilarity class extends the Metric class to implement the Cosine similarity algorithm.
+ */
+class CosineSimilarity extends Metric {
+    /**
+     * Constructor for the CosineSimilarity class.
+     *
+     * Initializes the Cosine similarity metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('cosine', a, b, opt, true);
+    }
+    /**
+     * Calculates the term frequency vector for a given string.
+     *
+     * @param {string} str - The input string
+     * @param {string} delimiter - The delimiter to split terms
+     * @return {Map<string, number>} - Term frequency object
+     */
+    _termFreq(str, delimiter) {
+        const terms = str.split(delimiter);
+        const freq = Pool.acquire('map', terms.length);
+        for (const term of terms)
+            freq.set(term, (freq.get(term) || 0) + 1);
+        return freq;
+    }
+    /**
+     * Calculates the Cosine similarity between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @return {MetricCompute<CosineRaw>} - Object containing the similarity result and raw values
+     */
+    compute(a, b) {
+        // Get delimiter from options or use default (space)
+        const { delimiter = ' ' } = this.options;
+        // Compute term frequency vectors
+        const termsA = this._termFreq(a, delimiter);
+        const termsB = this._termFreq(b, delimiter);
+        // Calculate dot product and magnitudes
+        let dotProduct = 0, magnitudeA = 0, magnitudeB = 0;
+        // Iterate over terms in A for dotProduct and magnitudeA
+        for (const [term, freqA] of termsA) {
+            const freqB = termsB.get(term) || 0;
+            dotProduct += freqA * freqB;
+            magnitudeA += freqA * freqA;
+        }
+        // Iterate over terms in B for magnitudeB
+        for (const freqB of termsB.values())
+            magnitudeB += freqB * freqB;
+        magnitudeA = Math.sqrt(magnitudeA);
+        magnitudeB = Math.sqrt(magnitudeB);
+        // Release maps back to the pool
+        Pool.release('map', termsA, termsA.size);
+        Pool.release('map', termsB, termsB.size);
+        // Return the result as a MetricCompute object
+        return {
+            res: (magnitudeA && magnitudeB) ? Metric.clamp(dotProduct / (magnitudeA * magnitudeB)) : 0,
+            raw: { dotProduct, magnitudeA, magnitudeB }
+        };
+    }
+}
+// Register the Cosine similarity in the metric registry
+MetricRegistry.add('cosine', CosineSimilarity);
+
+/**
+ * Damerau-Levenshtein Distance
+ * src/metric/DamerauLevenshtein.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance
+ *
+ * The Damerau-Levenshtein distance extends the classical Levenshtein algorithm by
+ * including transpositions (swapping of two adjacent characters) as a single edit
+ * operation, in addition to insertions, deletions, and substitutions.
+ *
+ * This metric is particularly useful for detecting and correcting common
+ * typographical errors.
+ *
+ * @module Metric/DamerauLevenshtein
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * DamerauLevenshteinDistance class extends the Metric class to implement the Damerau-Levenshtein algorithm.
+ */
+class DamerauLevenshteinDistance extends Metric {
+    /**
+     * Constructor for the DamerauLevenshteinDistance class.
+     *
+     * Initializes the Damerau-Levenshtein metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('damerau', a, b, opt, true);
+    }
+    /**
+     * Calculates the normalized Damerau-Levenshtein distance between two strings.
+     *
+     * @param {string} a - First string (always the shorter string for memory efficiency)
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string (a)
+     * @param {number} n - Length of the second string (b)
+     * @param {number} maxLen - Maximum length of the strings
+     * @return {MetricCompute<DamerauRaw>} - Object containing the similarity result and raw distance
+     */
+    compute(a, b, m, n, maxLen) {
+        // Get three reusable arrays from the Pool for the DP rows
+        const len = m + 1;
+        const [test, prev, curr] = Pool.acquireMany('uint16', [len, len, len]);
+        // Initialize the first row (edit distances from empty string to a)
+        for (let i = 0; i <= m; i++)
+            prev[i] = i;
+        // Fill the DP matrix row by row (over the longer string)
+        for (let j = 1; j <= n; j++) {
+            // Cost of transforming empty string to b[0..j]
+            curr[0] = j;
+            // Get the character code of the current character in b
+            const cb = b.charCodeAt(j - 1);
+            for (let i = 1; i <= m; i++) {
+                // Get the character code of the current character in b
+                const ca = a.charCodeAt(i - 1);
+                // If characters are the same, no cost for substitution
+                const cost = ca === cb ? 0 : 1;
+                // Calculate minimum of deletion, insertion, substitution
+                let val = Math.min(curr[i - 1] + 1, // Insertion
+                prev[i] + 1, // Deletion
+                prev[i - 1] + cost // Substitution
+                );
+                // Check for transposition
+                if (i > 1 && j > 1 &&
+                    ca === b.charCodeAt(j - 2) &&
+                    cb === a.charCodeAt(i - 2)) {
+                    // Transposition
+                    val = Math.min(val, test[i - 2] + cost);
+                }
+                // Set the cost for the current cell
+                curr[i] = val;
+            }
+            // Rotate rows: test <= prev, prev <= curr, curr <= test
+            test.set(prev);
+            prev.set(curr);
+        }
+        // The last value in prev is the Damerau-Levenshtein distance
+        const dist = prev[m];
+        // Release arrays back to the pool
+        Pool.release('uint16', test, len);
+        Pool.release('uint16', prev, len);
+        Pool.release('uint16', curr, len);
+        // Normalize by the length of the longer string
+        return {
+            res: maxLen === 0 ? 1 : Metric.clamp(1 - (dist / maxLen)),
+            raw: { dist, maxLen }
+        };
+    }
+}
+// Register the Damerau-Levenshtein distance in the metric registry
+MetricRegistry.add('damerau', DamerauLevenshteinDistance);
+
+/**
+ * Dice-Sørensen Coefficient
+ * src/metric/DiceSorensen.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Dice-S%C3%B8rensen_coefficient
+ *
+ * This module implements the Dice-Sørensen coefficient, a statistic used to gauge
+ * the similarity of two samples. It is commonly used in natural language processing
+ * and information retrieval to compare the similarity between two sets of data,
+ * such as text documents. The coefficient is defined as twice the size of the
+ * intersection divided by the sum of the sizes of the two sets.
+ *
+ * The implementation includes methods to compute bigrams from strings and calculate
+ * the coefficient based on these bigrams. It handles edge cases, such as empty
+ * strings and identical strings, to ensure accurate results.
+ *
+ * @module Metric/DiceSorensenCoefficient
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * DiceSorensenCoefficient class extends the Metric class to implement the Dice-Sørensen coefficient.
+ */
+class DiceSorensenCoefficient extends Metric {
+    /**
+     * Constructor for the DiceSorensen class.
+     *
+     * Initializes the DiceSorensen metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('dice', a, b, opt, true);
+    }
+    /**
+     * Computes the bigrams of a given string.
+     *
+     * @param {string} str - The input string
+     * @return {Set<string>} - A set of bigrams (two-character sequences) from the string
+     */
+    _bigrams(str) {
+        const len = str.length - 1;
+        const bigrams = Pool.acquire('set', len);
+        // Generate bigrams by iterating through the string
+        for (let i = 0; i < len; i++)
+            bigrams.add(str.substring(i, i + 2));
+        return bigrams;
+    }
+    /**
+     * Calculates the Dice-Sørensen coefficient between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @return {MetricCompute<DiceRaw>} - Object containing the similarity result and raw distance
+     */
+    compute(a, b) {
+        // Generate bigrams for both strings
+        const setA = this._bigrams(a);
+        const setB = this._bigrams(b);
+        // Calculate the intersection of bigrams
+        let intersection = 0;
+        for (const bigram of setA)
+            if (setB.has(bigram))
+                intersection++;
+        // Calculate the size of the union of both sets
+        const sizeA = setA.size, sizeB = setB.size;
+        const size = sizeA + sizeB;
+        // Release sets back to the pool
+        Pool.release('set', setA, sizeA);
+        Pool.release('set', setB, sizeB);
+        // Return the result as a MetricCompute object
+        return {
+            res: size === 0 ? 1 : Metric.clamp((2 * intersection) / size),
+            raw: { intersection, size }
+        };
+    }
+}
+// Register the Dice-Sørensen coefficient in the metric registry
+MetricRegistry.add('dice', DiceSorensenCoefficient);
+
+/**
+ * Hamming Distance
+ * src/metric/Hamming.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Hamming_distance
+ *
+ * The Hamming distance is a metric for comparing two strings of equal length. It
+ * measures the number of positions at which the corresponding symbols are different.
+ *
+ * This implementation allows for optional padding of the shorter string to equalize
+ * lengths, otherwise it throws an error if the strings are of unequal length.
+ *
+ * @module Metric/HammingDistance
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * HammingDistance class extends the Metric class to implement the Hamming distance.
+ */
+class HammingDistance extends Metric {
+    /**
+     * Constructor for the Hamming class.
+     *
+     * Initializes the Hamming distance metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} opt - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('hamming', a, b, opt, true);
+    }
+    /**
+     * Calculates the Hamming distance between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @param {number} maxLen - Maximum length of the strings
+     * @return {MetricCompute<HammingRaw>} - Object containing the similarity result and raw distance
+     * @throws {Error} - If strings are of unequal length and padding is not specified
+     */
+    compute(a, b, m, n, maxLen) {
+        // Check for equal string length
+        if (m !== n) {
+            // Optional: use padding to equalize string length
+            if (this.options.pad !== undefined) {
+                if (m < maxLen)
+                    a = a.padEnd(maxLen, this.options.pad);
+                if (n < maxLen)
+                    b = b.padEnd(maxLen, this.options.pad);
+                m = n = maxLen;
+            }
+            // Standard: Error for unequal length
+            else
+                throw new Error(`strings must be of equal length for Hamming Distance, a=${m} and b=${n} given, ` +
+                    `use option.pad for automatic adjustment`);
+        }
+        // Calculate the Hamming distance
+        let dist = 0;
+        for (let i = 0; i < a.length; i++)
+            if (a[i] !== b[i])
+                dist++;
+        // Return the result as a MetricCompute object
+        return {
+            res: m === 0 ? 1 : Metric.clamp(1 - dist / m),
+            raw: { dist }
+        };
+    }
+}
+// Register the Hamming distance in the metric registry
+MetricRegistry.add('hamming', HammingDistance);
+
+/**
+ * Jaccard Index
+ * src/metric/Jaccard.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Jaccard_index
+ *
+ * The Jaccard Index (or Jaccard similarity coefficient) measures the similarity
+ * between two sets by dividing the size of their intersection by the size of
+ * their union. In string similarity, it is often used to compare sets of characters,
+ * tokens, or n-grams. The result is a value between 0 and 1, where 1 means the
+ * sets are identical and 0 means they have no elements in common.
+ *
+ * @module Metric/JaccardIndex
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * JaccardIndex class extends the Metric class to implement the Jaccard Index algorithm.
+ */
+class JaccardIndex extends Metric {
+    /**
+     * Constructor for the JaccardIndex class.
+     *
+     * Initializes the Jaccard Index metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('jaccard', a, b, opt, true);
+    }
+    /**
+     * Calculates the Jaccard Index between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @return {MetricCompute<JaccardRaw>} - Object containing the similarity result and raw values
+     */
+    compute(a, b, m, n) {
+        // Acquire two sets from the Pool
+        const [setA, setB] = Pool.acquireMany('set', [m, n]);
+        // Fill setA and setB with unique characters from a and b
+        for (const A of a)
+            setA.add(A);
+        for (const B of b)
+            setB.add(B);
+        // Calculate intersection size
+        let intersection = 0;
+        for (const c of setA)
+            if (setB.has(c))
+                intersection++;
+        // Calculate union size (setA + elements in setB not in setA)
+        const union = setA.size + setB.size - intersection;
+        // Release sets back to the pool
+        Pool.release('set', setA, m);
+        Pool.release('set', setB, n);
+        // Return the result as a MetricCompute object
+        return {
+            res: union === 0 ? 1 : Metric.clamp(intersection / union),
+            raw: { intersection, union }
+        };
+    }
+}
+// Register the Jaccard index in the metric registry
+MetricRegistry.add('jaccard', JaccardIndex);
+
+/**
+ * Jaro-Winkler Distance
+ * src/metric/JaroWinkler.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance
+ *
+ * The Jaro-Winkler distance is a string similarity metric that gives more weight
+ * to matching characters at the start of the strings. It is especially effective
+ * for short strings and typographical errors, and is widely used in record linkage
+ * and duplicate detection.
+ *
+ * @module Metric/JaroWinkler
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * JaroWinklerDistance class extends the Metric class to implement the Jaro-Winkler algorithm.
+ */
+class JaroWinklerDistance extends Metric {
+    /**
+     * Constructor for the JaroWinklerDistance class.
+     *
+     * Initializes the Jaro-Winkler metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('jaro-winkler', a, b, opt, true);
+    }
+    /**
+     * Calculates the Jaro-Winkler similarity between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @return {MetricCompute<JaroWinklerRaw>} - Object containing the similarity result and raw values
+     */
+    compute(a, b, m, n) {
+        // Find matches
+        const matchWindow = Math.max(0, Math.floor(n / 2) - 1);
+        // Use Pool for boolean arrays
+        const matchA = Pool.acquire('uint16', m);
+        const matchB = Pool.acquire('uint16', n);
+        // Initialize match arrays
+        for (let i = 0; i < m; i++)
+            matchA[i] = 0;
+        for (let i = 0; i < n; i++)
+            matchB[i] = 0;
+        // Find matches within the match window
+        let matches = 0;
+        for (let i = 0; i < m; i++) {
+            const start = Math.max(0, i - matchWindow);
+            const end = Math.min(i + matchWindow + 1, n);
+            for (let j = start; j < end; j++) {
+                if (!matchB[j] && a[i] === b[j]) {
+                    matchA[i] = 1;
+                    matchB[j] = 1;
+                    matches++;
+                    break;
+                }
+            }
+        }
+        // Set initial values for transpositions, jaro distance, prefix and result
+        let transpos = 0, jaro = 0, prefix = 0, res = 0;
+        // If matches are found, proceed with further calculations
+        if (matches > 0) {
+            // Count transpositions
+            let k = 0;
+            for (let i = 0; i < m; i++) {
+                if (matchA[i]) {
+                    while (!matchB[k])
+                        k++;
+                    if (a[i] !== b[k])
+                        transpos++;
+                    k++;
+                }
+            }
+            transpos /= 2;
+            // Calculate Jaro similarity
+            jaro = ((matches / m) + (matches / n) +
+                (matches - transpos) / matches) / 3;
+            // Calculate common prefix length (max 4)
+            for (let i = 0; i < Math.min(4, m, n); i++) {
+                if (a[i] === b[i])
+                    prefix++;
+                else
+                    break;
+            }
+            // Step 5: Calculate Jaro-Winkler similarity
+            res = jaro + prefix * 0.1 * (1 - jaro);
+        }
+        // Release arrays back to the pool
+        Pool.release('uint16', matchA, m);
+        Pool.release('uint16', matchB, n);
+        // Return the result as a MetricCompute object
+        return {
+            res: Metric.clamp(res),
+            raw: { matchWindow, matches, transpos, jaro, prefix }
+        };
+    }
+}
+// Register the Jaro-Winkler distance in the metric registry
+MetricRegistry.add('jaroWinkler', JaroWinklerDistance);
+
+/**
+ * Longest Common Subsequence (LCS)
+ * src/metric/LCS.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Longest_common_subsequence
+ *
+ * The Longest Common Subsequence (LCS) metric measures the length of the longest
+ * subsequence common to both strings. Unlike substrings, the characters of a
+ * subsequence do not need to be contiguous, but must appear in the same order.
+ *
+ * The LCS is widely used in diff tools, bioinformatics, and approximate string
+ * matching.
+ *
+ * @module Metric/LCS
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * LCSMetric class extends the Metric class to implement the Longest Common Subsequence algorithm.
+ */
+class LCSMetric extends Metric {
+    /**
+     * Constructor for the LCSMetric class.
+     *
+     * Initializes the LCS metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('lcs', a, b, opt, true);
+    }
+    /**
+     * Calculates the normalized LCS similarity between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @param {number} maxLen - Maximum length of the strings
+     * @return {MetricCompute<LCSRaw>} - Object containing the similarity result and raw LCS length
+     */
+    compute(a, b, m, n, maxLen) {
+        // Get two reusable arrays from the Pool for the DP rows
+        const len = m + 1;
+        const [prev, curr] = Pool.acquireMany('uint16', [len, len]);
+        // Initialize the first row to zeros
+        for (let i = 0; i <= m; i++)
+            prev[i] = 0;
+        // Fill the DP matrix row by row (over the longer string)
+        for (let j = 1; j <= n; j++) {
+            curr[0] = 0;
+            // Get the character code of the current character in b
+            const cb = b.charCodeAt(j - 1);
+            for (let i = 1; i <= m; i++) {
+                // If characters match, increment the LCS length
+                if (a.charCodeAt(i - 1) === cb)
+                    curr[i] = prev[i - 1] + 1;
+                // Otherwise, take the maximum of the left or above cell
+                else
+                    curr[i] = Math.max(prev[i], curr[i - 1]);
+            }
+            // Copy current row to previous for next iteration
+            prev.set(curr);
+        }
+        // The last value in prev is the LCS length
+        const lcs = prev[m];
+        // Release arrays back to the pool
+        Pool.release('uint16', prev, len);
+        Pool.release('uint16', curr, len);
+        // Normalize by the length of the longer string
+        return {
+            res: maxLen === 0 ? 1 : Metric.clamp(lcs / maxLen),
+            raw: { lcs, maxLen }
+        };
+    }
+}
+// Register the Longest Common Subsequence (LCS) in the metric registry
+MetricRegistry.add('lcs', LCSMetric);
+
+/**
+ * Levenshtein Distance
+ * src/metric/Levenshtein.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Levenshtein_distance
+ *
+ * The Levenshtein distance is a classic metric for measuring the minimum number
+ * of single-character edits (insertions, deletions, or substitutions) required
+ * to change one string into another.
+ *
+ * It is widely used in approximate string matching, spell checking, and natural
+ * language processing.
+ *
+ * @module Metric/LevenshteinDistance
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * LevenshteinDistance class extends the Metric class to implement the Levenshtein distance algorithm.
+ */
+class LevenshteinDistance extends Metric {
+    /**
+     * Constructor for the Levenshtein class.
+     *
+     * Initializes the Levenshtein metric with two input strings
+     * or arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('levenshtein', a, b, opt, true);
+    }
+    /**
+     * Calculates the Levenshtein distance between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @param {number} maxLen - Maximum length of the strings
+     * @return {MetricCompute<LevenshteinRaw>} - Object containing the similarity result and raw distance
+     */
+    compute(a, b, m, n, maxLen) {
+        // Get two reusable arrays from the Pool for the DP rows
+        const len = m + 1;
+        const [prev, curr] = Pool.acquireMany('uint16', [len, len]);
+        // Initialize the first row (edit distances from empty string to a)
+        for (let i = 0; i <= m; i++)
+            prev[i] = i;
+        // Fill the DP matrix row by row (over the longer string)
+        for (let j = 1; j <= n; j++) {
+            // Cost of transforming empty string to b[0..j]
+            curr[0] = j;
+            // Get the character code of the current character in b
+            const cb = b.charCodeAt(j - 1);
+            for (let i = 1; i <= m; i++) {
+                // Cost is 0 if characters match, 1 otherwise
+                const cost = a.charCodeAt(i - 1) === cb ? 0 : 1;
+                // Calculate the minimum edit distance for current cell
+                curr[i] = Math.min(curr[i - 1] + 1, // Insertion
+                prev[i] + 1, // Deletion
+                prev[i - 1] + cost // Substitution
+                );
+            }
+            // Copy current row to previous for next iteration
+            prev.set(curr);
+        }
+        // The last value in prev is the Levenshtein distance
+        const dist = prev[m];
+        // Release arrays back to the pool
+        Pool.release('uint16', prev, len);
+        Pool.release('uint16', curr, len);
+        // Return the result as a MetricCompute object
+        return {
+            res: maxLen === 0 ? 1 : Metric.clamp(1 - dist / maxLen),
+            raw: { dist, maxLen }
+        };
+    }
+}
+// Register the Levenshtein distance in the metric registry
+MetricRegistry.add('levenshtein', LevenshteinDistance);
+
+/**
+ * Needleman-Wunsch Algorithm
+ * src/metric/NeedlemanWunsch.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Needleman%E2%80%93Wunsch_algorithm
+ *
+ * The Needleman-Wunsch algorithm performs global alignment, aligning two strings
+ * entirely, including gaps. It is commonly used in bioinformatics for sequence
+ * alignment.
+ *
+ * @module Metric/NeedlemanWunsch
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * NeedlemanWunschDistance class extends the Metric class to implement the Needleman-Wunsch algorithm.
+ */
+class NeedlemanWunschDistance extends Metric {
+    /**
+     * Constructor for the NeedlemanWunsch class.
+     *
+     * Initializes the Needleman-Wunsch metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('needlemanWunsch', a, b, opt, true);
+    }
+    /**
+     * Calculates the Needleman-Wunsch global alignment score between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @param {number} maxLen - Maximum length of the strings
+     * @return {MetricCompute<NeedlemanRaw>} - Object containing the similarity result and raw score
+     */
+    compute(a, b, m, n, maxLen) {
+        // Scoring parameters (can be customized via options if needed)
+        const { match = 1, mismatch = -1, gap = -1 } = this.options;
+        // Get two reusable arrays from the Pool for the DP rows
+        const len = m + 1;
+        const [prev, curr] = Pool.acquireMany('uint16', [len, len]);
+        // Initialize the first row (gap penalties)
+        prev[0] = 0;
+        for (let i = 1; i <= m; i++)
+            prev[i] = prev[i - 1] + gap;
+        // Fill the DP matrix row by row (over the longer string)
+        for (let j = 1; j <= n; j++) {
+            curr[0] = prev[0] + gap;
+            // Get the character code of the current character in b
+            const cb = b.charCodeAt(j - 1);
+            for (let i = 1; i <= m; i++) {
+                // Score for match / mismatch
+                const score = a.charCodeAt(i - 1) === cb ? match : mismatch;
+                // Calculate the maximum score for current cell
+                curr[i] = Math.max(prev[i - 1] + score, // Diagonal (match/mismatch)
+                prev[i] + gap, // Up (gap)
+                curr[i - 1] + gap // Left (gap)
+                );
+            }
+            // Copy current row to previous for next iteration
+            prev.set(curr);
+        }
+        // The last value in prev is the Needleman-Wunsch score
+        const score = prev[m];
+        // Release arrays back to the pool
+        Pool.release('uint16', prev, len);
+        Pool.release('uint16', curr, len);
+        // Use the maximum possible score for the longer string (global alignment)
+        const denum = maxLen * match;
+        // Return the result as a MetricCompute object
+        return {
+            res: denum === 0 ? 0 : Metric.clamp(score / denum),
+            raw: { score, denum }
+        };
+    }
+}
+// Register the Needleman-Wunsch algorithm in the metric registry
+MetricRegistry.add('needlemanWunsch', NeedlemanWunschDistance);
+
+/**
+ * q-Gram Similarity
+ * src/metric/QGram.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Q-gram
+ *
+ * Q-gram similarity is a string-matching algorithm that compares two strings by
+ * breaking them into substrings (q-grams) of length Q. The similarity is computed
+ * as the size of the intersection of q-gram sets divided by the size of the larger
+ * set.
+ *
+ * This metric is widely used in approximate string matching, information retrieval,
+ * and computational linguistics.
+ *
+ * @module Metric/QGramSimilarity
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * QGramSimilarity class extends the Metric class to implement the q-Gram similarity algorithm.
+ */
+class QGramSimilarity extends Metric {
+    /**
+     * Constructor for the QGramSimilarity class.
+     *
+     * Initializes the q-Gram similarity metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('qgram', a, b, opt, true);
+    }
+    /**
+     * Converts a string into a set of q-grams (substrings of length q).
+     *
+     * @param {string} str - The input string
+     * @param {number} q - The length of each q-gram
+     * @return {Set<string>} - Set of q-grams
+     */
+    _qGrams(str, q) {
+        const len = Math.max(0, str.length - q + 1);
+        const grams = Pool.acquire('set', len);
+        for (let i = 0; i < len; i++)
+            grams.add(str.slice(i, i + q));
+        return grams;
+    }
+    /**
+     * Calculates the q-Gram similarity between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @return {MetricCompute<QGramRaw>} - Object containing the similarity result and raw values
+     */
+    compute(a, b) {
+        // Get q from options or use default "2"
+        const { q = 2 } = this.options;
+        // Generate q-gram sets for both strings
+        const setA = this._qGrams(a, q);
+        const setB = this._qGrams(b, q);
+        // Calculate intersection size
+        let intersection = 0;
+        for (const gram of setA)
+            if (setB.has(gram))
+                intersection++;
+        // Calculate the size of the larger set
+        const sizeA = setA.size, sizeB = setB.size;
+        const size = Math.max(sizeA, sizeB);
+        // Release sets back to the pool
+        Pool.release('set', setA, sizeA);
+        Pool.release('set', setB, sizeB);
+        // Return the result as a MetricCompute object
+        return {
+            res: size === 0 ? 1 : Metric.clamp(intersection / size),
+            raw: { intersection, size }
+        };
+    }
+}
+// Register the q-Gram similariry in the metric registry
+MetricRegistry.add('qGram', QGramSimilarity);
+
+/**
+ * Smith-Waterman Algorithm
+ * src/metric/SmithWaterman.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Smith%E2%80%93Waterman_algorithm
+ *
+ * The Smith-Waterman algorithm performs local alignment, finding the best matching
+ * subsequence between two strings. It is commonly used in bioinformatics for local
+ * sequence alignment. Instead of looking at the entire sequence, the Smith–Waterman
+ * algorithm compares segments of all possible lengths and optimizes the similarity
+ * measure.
+ *
+ * @module Metric/SmithWatermanDistance
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * SmithWatermanDistance class extends the Metric class to implement the Smith-Waterman algorithm.
+ */
+class SmithWatermanDistance extends Metric {
+    /**
+     * Constructor for the SmithWaterman class.
+     *
+     * Initializes the Smith-Waterman metric with two input strings or
+     * arrays of strings and optional options.
+     *
+     * @param {MetricInput} a - First input string or array of strings
+     * @param {MetricInput} b - Second input string or array of strings
+     * @param {MetricOptions} [opt] - Options for the metric computation
+     */
+    constructor(a, b, opt = {}) {
+        // Call the parent Metric constructor with the metric name and inputs
+        // Metric is symmetrical
+        super('smithWaterman', a, b, opt, true);
+    }
+    /**
+     * Calculates the Smith-Waterman local alignment score between two strings.
+     *
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @param {number} m - Length of the first string
+     * @param {number} n - Length of the second string
+     * @return {MetricCompute<SmithWatermanRaw>} - Object containing the similarity result and raw score
+     */
+    compute(a, b, m, n) {
+        // Scoring parameters (can be customized via options if needed)
+        const { match = 2, mismatch = -1, gap = -2 } = this.options;
+        // Get two reusable arrays from the Pool for the DP rows
+        const len = m + 1;
+        const [prev, curr] = Pool.acquireMany('uint16', [len, len]);
+        // Initialize the first row to zeros (Smith-Waterman local alignment)
+        for (let i = 0; i <= m; i++)
+            prev[i] = 0;
+        let maxScore = 0;
+        // Fill the DP matrix row by row (over the longer string)
+        for (let j = 1; j <= n; j++) {
+            // First column always zero
+            curr[0] = 0;
+            // Get the character code of the current character in b
+            const cb = b.charCodeAt(j - 1);
+            for (let i = 1; i <= m; i++) {
+                // Score for match / mismatch
+                const score = a.charCodeAt(i - 1) === cb ? match : mismatch;
+                // Calculate the maximum score for current cell
+                curr[i] = Math.max(0, prev[i - 1] + score, // Diagonal (match/mismatch)
+                prev[i] + gap, // Up (gap)
+                curr[i - 1] + gap // Left (gap)
+                );
+                // Track the maximum score in the matrix
+                if (curr[i] > maxScore)
+                    maxScore = curr[i];
+            }
+            // Copy current row to previous for next iteration
+            prev.set(curr);
+        }
+        // Release arrays back to the pool
+        Pool.release('uint16', prev, len);
+        Pool.release('uint16', curr, len);
+        // Use the maximum possible score for the shorter string (local alignment)
+        const denum = Math.min(m * match, n * match);
+        // Return the result as a MetricCompute object
+        return {
+            res: denum === 0 ? 0 : Metric.clamp(maxScore / denum),
+            raw: { score: maxScore, denum }
+        };
+    }
+}
+// Register the Smith-Waterman algorithm in the metric registry
+MetricRegistry.add('smithWaterman', SmithWatermanDistance);
+
+/**
+ * Abstract Phonetic
+ * src/phonetic/Phonetic.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Phonetic_algorithm
+ *
+ * A phonetic algorithm refers to a method for indexing words according to their
+ * pronunciation. When the algorithm relies on orthography, it is significantly
+ * influenced by the spelling conventions of the language for which it is intended:
+ * since the majority of phonetic algorithms were created for English, they tend
+ * to be less effective for indexing words in other languages.
+ *
+ * Phonetic search has numerous applications, and one of the initial use cases has
+ * been in trademark searches to verify that newly registered trademarks do not
+ * pose a risk of infringing upon existing trademarks due to their pronunciation.
+ *
+ * This module provides an abstract class for generating phonetic indices based
+ * on mappings and rules. It allows for the implementation of various phonetic
+ * algorithms by extending the abstract class.
+ *
+ * @module Phonetic
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+// Get the singleton profiler instance for performance monitoring
+const profiler$1 = Profiler.getInstance();
+/**
+ * Abstract class representing a phonetic algorithm.
+ *
+ * The protected methods `applyRules`, `encode`, `mapChar`, `equalLen`, `word2Chars`,
+ * `exitEarly`, `adjustCode`, `loop` and `loopAsync` can be overridden in subclasses
+ * to implement specific phonetic algorithms.
+ *
+ * @abstract
+ */
+class Phonetic {
+    // Cache for indexed words to avoid redundant calculations
+    static cache = new HashTable();
+    /**
+     * Default phonetic options.
+     *
+     * This object contains default settings for phonetic algorithms,
+     * implemented in the subclass.
+     */
+    static default;
+    // Phonetic algorithm name for identification
+    algo;
+    // Phonetic map and options for the algorithm
+    options;
+    map;
+    /**
+     * Static method to clear the cache of indexed words.
+     */
+    static clear() { this.cache.clear(); }
+    /**
+     * Constructor for the Phonetic class.
+     *
+     * Initializes the phonetic algorithm with the specified options and mapping.
+     *
+     * @param {string} algo - The name of the algorithm (e.g. 'soundex')
+     * @param {PhoneticOptions} [opt] - Options for the phonetic algorithm
+     * @throws {Error} - If the requested mapping is not declared
+     */
+    constructor(algo, opt = {}) {
+        // Set the options by merging the default options with the provided ones
+        this.options = merge(this.constructor.default ?? {}, opt);
+        // Get the mapping based on the provided options
+        const map = PhoneticMappingRegistry.get(algo, this.options.map);
+        // If the mapping is not defined, throw an error
+        if (map === undefined)
+            throw new Error(`requested mapping <${this.options.map}> is not declared`);
+        this.algo = algo;
+        this.map = map;
+    }
+    /**
+     * Applies phonetic rules to a character in a word context.
+     *
+     * This method is designed to be generic and efficient for all phonetic algorithms.
+     * It checks all rule types (prev, next, prevNot, nextNot, position, etc.) and
+     * returns either the appropriate code (string) or undefined.
+     *
+     * @param {string} char - The current character
+     * @param {number} i - The current position within the word
+     * @param {string[]} chars - The word as an array of characters
+     * @param {number} charLen - The total length of the word
+     * @returns {string|undefined} - The rule code or undefined if no rule applies
+     */
+    applyRules(char, i, chars, charLen) {
+        const { ruleset = [] } = this.map;
+        // If no rules are provided, return undefined
+        if (!ruleset || !ruleset.length)
+            return undefined;
+        // Get the surrounding characters
+        const prev = chars[i - 1] || '', prev2 = chars[i - 2] || '';
+        const next = chars[i + 1] || '', next2 = chars[i + 2] || '';
+        // Iterate over the rules to find a matching rule for the current character
+        for (const rule of ruleset) {
+            // Skip if the rule does not match the current character
+            if (rule.char && rule.char !== char)
+                continue;
+            // Position in the word (start, middle, end)
+            if (rule.position === 'start' && i !== 0)
+                continue;
+            if (rule.position === 'middle' && i > 0 && i < charLen)
+                continue;
+            if (rule.position === 'end' && i !== charLen)
+                continue;
+            // Previous character(s)
+            if (rule.prev && !rule.prev.includes(prev))
+                continue;
+            if (rule.prevNot && rule.prevNot.includes(prev))
+                continue;
+            if (rule.prev2 && !rule.prev2.includes(prev2))
+                continue;
+            if (rule.prev2Not && rule.prev2Not.includes(prev2))
+                continue;
+            // Following character(s)
+            if (rule.next && !rule.next.includes(next))
+                continue;
+            if (rule.nextNot && rule.nextNot.includes(next))
+                continue;
+            if (rule.next2 && !rule.next2.includes(next2))
+                continue;
+            if (rule.next2Not && rule.next2Not.includes(next2))
+                continue;
+            // Special case: Beginning of a word (e.g. chars.slice(0, n))
+            if (rule.leading && !rule.leading.includes(chars.slice(0, rule.leading.length).join('')))
+                continue;
+            // Special case: end of word (e.g. chars.slice(-n))
+            if (rule.trailing && !rule.trailing.includes(chars.slice(-rule.trailing.length).join('')))
+                continue;
+            // Check multiple characters (e.g. bigram/trigram)
+            if (rule.match && !rule.match.every((c, j) => chars[i + j] === c))
+                continue;
+            // If all conditions met, return the rule code
+            return rule.code;
+        }
+        // If no rule matched, return undefined
+        return undefined;
+    }
+    /**
+     * Generates the phonetic code for a given word.
+     *
+     * This method processes the word character by character, applying phonetic rules
+     * and mappings to generate a phonetic code.
+     *
+     * @param {string} word - The input word to be converted into a phonetic code
+     * @returns {string} - The generated phonetic code
+     */
+    encode(word) {
+        const { map = {}, ignore = [] } = this.map;
+        // Get the characters of the word and its length
+        const chars = this.word2Chars(word);
+        const charLen = chars.length;
+        let code = '', lastCode = null;
+        // Iterate over each character in the word
+        for (let i = 0; i < charLen; i++) {
+            const char = chars[i];
+            // Skip characters that are in the ignore list
+            if (ignore.includes(char))
+                continue;
+            // Convert the character to its phonetic code
+            const mapped = this.mapChar(char, i, chars, charLen, lastCode, map);
+            // If no code is generated, skip to the next character
+            if (mapped === undefined)
+                continue;
+            // Append the generated code to the final code
+            code += mapped, lastCode = mapped;
+            // If the code length exceeds the specified limit, exit early
+            if (this.exitEarly(code, i))
+                break;
+        }
+        // Return the adjusted phonetic code
+        return this.adjustCode(code, chars);
+    }
+    /**
+     * Converts a character to its phonetic code based on the mapping and rules.
+     *
+     * @param {string} char - The current character
+     * @param {number} i - The current position within the word
+     * @param {string[]} chars - The word as an array of characters
+     * @param {number} charLen - The total length of the word
+     * @param {string|null} lastCode - The last code generated (to avoid duplicates)
+     * @param {Record<string, string>} map - The phonetic mapping
+     * @returns {string|undefined} - The phonetic code or undefined if no code applies
+     */
+    mapChar(char, i, chars, charLen, lastCode, map) {
+        const { dedupe = true } = this.options;
+        // Apply phonetic rules to the character
+        // If no rules apply, use the mapping
+        // If the character is not in the mapping, return undefined
+        const c = this.applyRules(char, i, chars, charLen) ?? map[char] ?? undefined;
+        // De-duplicate the code if necessary
+        return dedupe && c === lastCode ? undefined : c;
+    }
+    /**
+     * Ensures the phonetic code has a fixed length by padding or truncating.
+     *
+     * @param {string} input - The input string to be adjusted
+     * @returns {string} - The adjusted string with fixed length
+     */
+    equalLen(input) {
+        const { length = -1, pad = '0' } = this.options;
+        return length === -1 ? input : (input + pad.repeat(length)).slice(0, length);
+    }
+    /**
+     * Converts a word into an array of characters.
+     *
+     * @param {string} word - The input word to be converted
+     * @returns {string[]} - An array of characters from the input word
+     */
+    word2Chars(word) { return word.toLowerCase().split(''); }
+    /**
+     * Determines whether to exit early based on the current phonetic code length.
+     *
+     * @param {string} code - The current phonetic code
+     * @param {number} i - The current index in the word
+     * @returns {boolean} - True if the code length exceeds the specified limit, false otherwise
+     */
+    exitEarly(code, i) {
+        const { length = -1 } = this.options;
+        return length > 0 && code.length >= length;
+    }
+    /**
+     * Adjusts the phonetic code.
+     *
+     * @param {string} code - The phonetic code to be adjusted
+     * @param {string[]} chars - Characters to be removed from the code
+     * @returns {string} - The adjusted phonetic code
+     */
+    adjustCode(code, chars) { return code; }
+    /**
+     * Processes an array of words to generate their phonetic indices.
+     *
+     * This method iterates over each word, generates its phonetic code,
+     * and ensures that the resulting codes are of equal length.
+     *
+     * @param {string[]} words - An array of words to be processed
+     * @returns {string[]} - An array of phonetic indices for the input words
+     */
+    loop(words) {
+        const index = [];
+        // Loop over each word in the input array
+        for (const word of words) {
+            // Generate a cache key based on the algorithm and word
+            const key = Phonetic.cache.key(this.algo, [word]);
+            // If the key exists in the cache, return the cached result
+            // Otherwise, encode the word using the algorithm
+            const code = Phonetic.cache.get(key || '') ?? (() => {
+                // Get the phonetic code for the word
+                const res = this.encode(word);
+                // If a key was generated, store the result in the cache
+                if (key)
+                    Phonetic.cache.set(key, res);
+                return res;
+            })();
+            // If a code is generated, add them to the index
+            if (code && code.length)
+                index.push(this.equalLen(code));
+        }
+        return index;
+    }
+    /**
+     * Asynchronously processes an array of words to generate their phonetic indices.
+     *
+     * This method iterates over each word, generates its phonetic code asynchronously,
+     * and ensures that the resulting codes are of equal length.
+     *
+     * @param {string[]} words - An array of words to be processed
+     * @returns {Promise<string[]>} - A promise that resolves to an array of phonetic indices for the input words
+     */
+    async loopAsync(words) {
+        const index = [];
+        // Loop over each word in the input array
+        for (const word of words) {
+            // Get the phonetic code for the word asynchronously
+            const code = await Promise.resolve(this.encode(word));
+            // If a code is generated, add them to the index
+            if (code && code.length)
+                index.push(this.equalLen(code));
+        }
+        return index;
+    }
+    /**
+     * Get the name of the phonetic algorithm.
+     *
+     * @returns {string} - The name of the algorithm
+     */
+    getAlgoName() { return this.algo; }
+    /**
+     * Generates a phonetic index for the given input string.
+     *
+     * @param {string} input - The input string to be indexed
+     * @returns {string[]} - An array of phonetic indices for the input words
+     */
+    getIndex(input) {
+        const { delimiter = ' ' } = this.options;
+        // Split the input string by the specified delimiter and loop over it
+        return profiler$1.run(() => this.loop(input.split(delimiter).filter(Boolean)).filter(Boolean));
+    }
+    /**
+     * Asynchronously generates a phonetic index for the given input string.
+     *
+     * @param {string} input - The input string to be indexed
+     * @returns {Promise<string[]>} - A promise that resolves to an array of phonetic indices for the input words
+     */
+    async getIndexAsync(input) {
+        const { delimiter = ' ' } = this.options;
+        // Split the input string by the specified delimiter and loop over it asynchronously
+        return (await profiler$1.runAsync(async () => await this.loopAsync(input.split(delimiter).filter(Boolean)))).filter(Boolean);
+    }
+}
+/**
+ * Phonetic registry service for managing phonetic implementations.
+ *
+ * This registry allows for dynamic registration and retrieval of phonetic classes,
+ * enabling the use of various phonetic algorithms in a consistent manner.
+ */
+const PhoneticRegistry = Registry('phonetic', Phonetic);
+/**
+ * Phonetic Mapping Service
+ *
+ * This service provides a simple interface to manage phonetic mappings across
+ * different phonetic algorithms. It allows adding, removing, checking existence,
+ * retrieving, and listing phonetic mappings for specified algorithms.
+ */
+const PhoneticMappingRegistry = (() => {
+    // Create a registry object to hold mappings
+    const mappings = Object.create(null);
+    // Helper function to retrieve mappings for a specific algorithm
+    const maps = (algo) => (mappings[algo] ||= Object.create(null));
+    return {
+        /**
+         * Adds a phonetic mapping for a specific algorithm and ID.
+         *
+         * @param {string} algo - The phonetic algorithm identifier (e.g., 'soundex', 'metaphone')
+         * @param {string} id - The unique identifier for the mapping
+         * @param {PhoneticMap} map - The phonetic map to be added, containing rules and mappings
+         * @param {boolean} [update=false] - Whether to allow overwriting an existing entry
+         * @throws {Error} If the mapping name already exists and update is false
+         */
+        add(algo, id, map, update = false) {
+            const mappings = maps(algo);
+            if (!update && id in mappings)
+                throw new Error(`entry <${id}> already exists / use <update=true> to overwrite`);
+            mappings[id] = map;
+        },
+        /**
+         * Removes a phonetic mapping for a specific algorithm and ID.
+         *
+         * @param {string} algo - The phonetic algorithm identifier
+         * @param {string} id - The unique identifier for the mapping to be removed
+         */
+        remove(algo, id) { delete maps(algo)[id]; },
+        /**
+         * Checks if a phonetic mapping exists for a specific algorithm and ID.
+         *
+         * @param {string} algo - The phonetic algorithm identifier
+         * @param {string} id - The unique identifier for the mapping to check
+         * @returns {boolean} - Returns true if the mapping exists, false otherwise
+         */
+        has(algo, id) { return id in maps(algo); },
+        /**
+         * Retrieves a phonetic mapping for a specific algorithm and ID.
+         *
+         * @param {string} algo - The phonetic algorithm identifier
+         * @param {string} id - The unique identifier for the mapping to retrieve
+         * @returns {PhoneticMap | undefined} - Returns the phonetic map if found, otherwise undefined
+         */
+        get(algo, id) { return maps(algo)[id]; },
+        /**
+         * Lists all phonetic mappings for a specific algorithm.
+         *
+         * @param {string} algo - The phonetic algorithm identifier
+         * @returns {string[]} - Returns an array of mapping IDs for the specified algorithm
+         */
+        list(algo) { return Object.keys(maps(algo)); }
+    };
+})();
+
+/**
+ * Cologne Phonetic Algorithm
+ * src/phonetic/Cologne.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Cologne_phonetics
+ *
+ * Cologne phonetics, also known as `Kölner Phonetik` or the `Cologne process`,
+ * is a phonetic algorithm that assigns a sequence of digits, referred to as the
+ * phonetic code, to words. The purpose of this method is to ensure that words
+ * with identical sounds receive the same code. This algorithm can facilitate a
+ * similarity search among words.
+ *
+ * Cologne phonetics is associated with the well-known Soundex phonetic algorithm,
+ * yet it is specifically optimized for the German language. This algorithm was
+ * introduced by Hans Joachim Postel in 1969.
+ *
+ * The Cologne phonetic algorithm works by mapping letters to digits, ignoring
+ * certain letters, and applying specific rules to handle character combinations.
+ *
+ * @module Phonetic/Cologne
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * Cologne class extends the Phonetic class to implement the Cologne phonetic algorithm.
+ */
+class Cologne extends Phonetic {
+    // Default options for the Cologne phonetic algorithm
+    static default = {
+        map: 'default', delimiter: ' ', length: -1, dedupe: true
+    };
+    /**
+     * Constructor for the Cologne class.
+     *
+     * Initializes the Cologne phonetic algorithm with the mapping and options.
+     *
+     * @param {PhoneticOptions} [opt] - Options for the Cologne phonetic algorithm
+     */
+    constructor(opt = {}) { super('cologne', opt); }
+    /**
+     * Adjusts the phonetic code by removing all '0's except the first character.
+     *
+     * @param {string} code - The phonetic code to adjust
+     * @returns {string} - The adjusted phonetic code
+     */
+    adjustCode(code) {
+        return code.slice(0, 1) + code.slice(1).replaceAll('0', '');
+    }
+}
+// Register the Cologne algorithm in the phonetic registry
+PhoneticRegistry.add('cologne', Cologne);
+// Register the Cologne phonetic mapping
+PhoneticMappingRegistry.add('cologne', 'default', {
+    map: {
+        a: '0', ä: '0', e: '0', i: '0', j: '0', o: '0', ö: '0', u: '0', ü: '0', y: '0',
+        b: '1', p: '1', d: '2', t: '2', f: '3', v: '3', w: '3', g: '4', k: '4', q: '4',
+        l: '5', m: '6', n: '6', r: '7', c: '8', s: '8', ß: '8', z: '8', x: '48'
+    },
+    ignore: ['h'],
+    ruleset: [
+        { char: 'p', next: ['h'], code: '3' },
+        { char: 'c', position: 'start', next: ['a', 'h', 'k', 'l', 'o', 'q', 'r', 'u', 'x'], code: '4' },
+        { char: 'c', next: ['a', 'h', 'k', 'o', 'q', 'u', 'x'], prevNot: ['s', 'z'], code: '4' },
+        { char: 'd', next: ['c', 's', 'z'], code: '8' },
+        { char: 't', next: ['c', 's', 'z'], code: '8' },
+        { char: 'x', prev: ['c', 'k', 'q'], code: '8' }
+    ]
+});
+
+/**
+ * Metaphone Phonetic Algorithm
+ * src/phonetic/Metaphone.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Metaphone
+ *
+ * Metaphone is a phonetic algorithm for indexing words by their English pronunciation.
+ * It encodes words into a string of consonant symbols, allowing for the comparison of
+ * words based on their pronunciation rather than their spelling. Metaphone is more
+ * accurate than Soundex for English and is widely used in search, spell-checking,
+ * and fuzzy matching.
+ *
+ * This implementation uses a mapping and a comprehensive ruleset to efficiently
+ * transform input words into their Metaphone code. The algorithm drops or transforms
+ * letters according to context-sensitive rules, and only retains vowels at the start.
+ *
+ * @module Phonetic/Metaphone
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * Metaphone class extends the Phonetic class to implement the Metaphone phonetic algorithm.
+ */
+class Metaphone extends Phonetic {
+    // Default options for the Metaphone phonetic algorithm
+    static default = {
+        map: 'en90', delimiter: ' ', length: -1, pad: '', dedupe: false
+    };
+    /**
+     * Constructor for the Metaphone class.
+     *
+     * Initializes the Metaphone phonetic algorithm with the mapping and options.
+     *
+     * @param {PhoneticOptions} [opt] - Options for the Metaphone phonetic algorithm
+     */
+    constructor(opt = {}) { super('metaphone', opt); }
+    /**
+     * Generates the Metaphone code for a given word.
+     *
+     * @param {string} word - The input word to be converted into a Metaphone code
+     * @returns {string} - The generated Metaphone code
+     */
+    encode(word) {
+        // Remove duplicate adjacent letters except for C
+        word = word.replace(/([A-BD-Z])\1+/gi, (m, c) => c === 'C' ? m : c);
+        // Use the base implementation for rule/mapping application
+        return super.encode(word);
+    }
+    /**
+     * Adjusts the Metaphone code by removing vowels except for the first letter.
+     *
+     * @param {string} code - The Metaphone code to be adjusted
+     * @returns {string} - The adjusted Metaphone code
+     */
+    adjustCode(code) {
+        // Remove vowels except for the first letter
+        return code.slice(0, 1) + code.slice(1).replace(/[AEIOU]/g, '');
+    }
+}
+// Register the Metaphone algorithm in the phonetic registry
+PhoneticRegistry.add('metaphone', Metaphone);
+/**
+ * Register the Metaphone phonetic mapping for English.
+ *
+ * This version is based on the original BASIC implementation from 1990,
+ * written by Lawrence Philips.
+ *
+ * @see https://gist.github.com/Rostepher/b688f709587ac145a0b3
+ */
+PhoneticMappingRegistry.add('metaphone', 'en90', {
+    map: {
+        a: 'A', b: 'B', c: 'K', d: 'T', e: 'E', f: 'F',
+        g: 'K', h: 'H', i: 'I', j: 'J', k: 'K',
+        l: 'L', m: 'M', n: 'N', o: 'O', p: 'P', q: 'K',
+        r: 'R', s: 'S', t: 'T', u: 'U', v: 'F', w: 'W',
+        x: 'KS', y: 'Y', z: 'S'
+    },
+    ruleset: [
+        // Drop the first letter if the string begins with `AE`, `GN`, `KN`, `PN` or `WR`
+        { char: 'a', position: 'start', next: ['e'], code: '' },
+        { char: 'g', position: 'start', next: ['n'], code: '' },
+        { char: 'k', position: 'start', next: ['n'], code: '' },
+        { char: 'p', position: 'start', next: ['n'], code: '' },
+        { char: 'w', position: 'start', next: ['r'], code: '' },
+        // Drop `B` if after `M` at the end of the string
+        { char: 'b', position: 'end', prev: ['m'], code: '' },
+        // `C` transforms into `X` if followed by `H` or `IA`
+        { char: 'c', next: ['h'], prevNot: ['s'], code: 'X' },
+        { char: 'c', next: ['i'], next2: ['a'], code: 'X' },
+        // `C` transforms into `S` if followed by `E`, `I` or `Y`
+        { char: 'c', next: ['e', 'i', 'y'], code: 'S' },
+        // `D` transforms into `J` if followed by `GE`, `GI` or `GY`
+        { char: 'd', next: ['g'], next2: ['e', 'i', 'y'], code: 'J' },
+        // Drop `G` if followed by `H` and `H` is not at the end or before a vowel
+        { char: 'g', next: ['h'], next2Not: ['', 'a', 'e', 'i', 'o', 'u'], code: '' },
+        // Drop `G` if followed by `N` or `NED` and is at the end of the string
+        { char: 'g', trailing: 'n', code: '' },
+        { char: 'g', trailing: 'ned', code: '' },
+        // `G` transforms into `J` if before `E`, `I` or `Y` and is not a `GG`
+        { char: 'g', next: ['e', 'i', 'y'], prevNot: ['g'], code: 'J' },
+        // Drop `H` if after a vowel and not before a vowel
+        { char: 'h', prev: ['a', 'e', 'i', 'o', 'u'], nextNot: ['a', 'e', 'i', 'o', 'u'], code: '' },
+        // Drop `H` if after `C`, `G`, `P`, `S` or `T`
+        { char: 'h', prev: ['c', 'g', 'p', 's', 't'], code: '' },
+        // Drop `K` if after `C`
+        { char: 'k', prev: ['c'], code: '' },
+        // `PH` transforms into `F`
+        { char: 'p', next: ['h'], code: 'F' },
+        // `S` transforms into `X` if followed by `H`, `IA` or `IO`
+        { char: 's', next: ['h'], code: 'X' },
+        { char: 's', next: ['i'], next2: ['a', 'o'], code: 'X' },
+        // `T` transforms into `X` if followed by `IA` or `IO`
+        { char: 't', next: ['i'], next2: ['a', 'o'], code: 'X' },
+        // `TH` transforms into `0` (zero)
+        { char: 't', next: ['h'], code: '0' },
+        // Drop `T` if followed by `CH`
+        { char: 't', next: ['c'], next2: ['h'], code: '' },
+        // Drop `W` if not followed by a vowel
+        { char: 'w', nextNot: ['a', 'e', 'i', 'o', 'u'], code: '' },
+        // `WH` transforms into `W` if at the beginning of the string
+        { char: 'h', leading: 'w', code: '' },
+        // `X` transforms into `S` if at the beginning
+        { char: 'x', position: 'start', code: 'S' },
+        // Drop `Y` if not followed by a vowel
+        { char: 'y', nextNot: ['a', 'e', 'i', 'o', 'u'], code: '' }
+    ]
+});
+
+/**
+ * Soundex Phonetic Algorithm
+ * src/phonetic/Soudex.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Soundex
+ *
+ * Soundex is a phonetic algorithm for indexing names by sound. It is used to
+ * encode words into a phonetic representation, allowing for the comparison of
+ * words based on their pronunciation rather than their spelling. This works
+ * by mapping letters to digits, ignoring certain letters, and applying specific
+ * rules to handle character combinations.
+ *
+ * It is particularly useful for matching names that may be spelled differently
+ * but sound similar and commonly used in genealogical research and databases
+ * to find similar-sounding names.
+ *
+ * The Soundex algorithm is not case-sensitive and ignores vowels and certain
+ * consonants. It outputs an array of strings that represents the phonetic code
+ * of the input, typically limited to the length of four characters.
+ *
+ * @module Phonetic/Soundex
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * Soundex class extends the Phonetic class to implement the Soundex phonetic algorithm.
+ */
+class Soundex extends Phonetic {
+    // Default options for the Soundex phonetic algorithm
+    static default = {
+        map: 'en', delimiter: ' ', length: 4, pad: '0', dedupe: true
+    };
+    /**
+     * Constructor for the Soundex class.
+     *
+     * Initializes the Soundex phonetic algorithm with the mapping and options.
+     *
+     * @param {PhoneticOptions} [opt] - Options for the Soundex phonetic algorithm
+     */
+    constructor(opt = {}) { super('soundex', opt); }
+    /**
+     * Adjusts the phonetic code by removing leading zeros and ensuring the
+     * first character is uppercase.
+     *
+     * @param {string} code - The phonetic code to adjust
+     * @param {string[]} chars - The characters used in the phonetic code
+     * @returns {string} - The adjusted phonetic code
+     */
+    adjustCode(code, chars) {
+        return chars[0].toUpperCase() + code.slice(1).replaceAll('0', '');
+    }
+}
+// Register the Soundex algorithm in the phonetic registry
+PhoneticRegistry.add('soundex', Soundex);
+//Register the Soundex phonetic mapping for English.
+PhoneticMappingRegistry.add('soundex', 'en', {
+    map: {
+        a: '0', e: '0', h: '0', i: '0', o: '0', u: '0', w: '0', y: '0',
+        b: '1', f: '1', p: '1', v: '1',
+        c: '2', g: '2', j: '2', k: '2', q: '2', s: '2', x: '2', z: '2',
+        d: '3', t: '3', l: '4', m: '5', n: '5', r: '6'
+    }
+});
+//Register the Soundex phonetic mapping for German.
+PhoneticMappingRegistry.add('soundex', 'de', {
+    map: {
+        a: '0', ä: '0', e: '0', h: '0', i: '0', j: '0', o: '0', ö: '0', u: '0', ü: '0', y: '0',
+        b: '1', f: '1', p: '1', v: '1', w: '1',
+        c: '2', g: '2', k: '2', q: '2', s: '2', ß: '2', x: '2', z: '2',
+        d: '3', t: '3', l: '4', m: '5', n: '5', r: '6'
+    },
+    ruleset: [
+        { char: 'c', next: ['h'], code: '7' }
+    ]
+});
+
+/**
+ * CmpStr Main API
+ * src/CmpStr.ts
+ *
+ * The CmpStr class provides a comprehensive, highly abstracted, and type-safe interface
+ * for string comparison, similarity measurement, phonetic indexing, filtering, normalization,
+ * and text analysis. It unifies all core features of the CmpStr package and exposes a
+ * consistent, user-friendly API for both single and batch operations.
+ *
+ * Features:
+ *  - Centralized management of metrics, phonetic algorithms, and filters
+ *  - Flexible normalization and filtering pipeline for all inputs
+ *  - Batch, pairwise, and single string comparison with detailed results
+ *  - Phonetic indexing and phonetic-aware search and comparison
+ *  - Text analysis and unified diff utilities
+ *  - Full TypeScript type safety and extensibility
+ *
+ * @module CmpStr
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+// Import the Profiler instance for global profiling
+const profiler = Profiler.getInstance();
+/**
+ * The main CmpStr class that provides a unified interface for string comparison,
+ * phonetic indexing, filtering, and text analysis.
+ *
+ * @template R - The type of the metric result, defaults to MetricRaw
+ */
+class CmpStr {
+    /**
+     * --------------------------------------------------------------------------------
+     * Static methods and properties for global access to CmpStr features
+     * --------------------------------------------------------------------------------
+     *
+     * These static methods provide a convenient way to access the core features of
+     * the CmpStr package without needing to instantiate a CmpStr object.
+     */
+    /**
+     * Adds, removes, pauses, resumes, lists, or clears global filters.
+     *
+     * @see Filter
+     */
+    static filter = {
+        add: Filter.add,
+        remove: Filter.remove,
+        pause: Filter.pause,
+        resume: Filter.resume,
+        list: Filter.list,
+        clear: Filter.clear
+    };
+    /**
+     * Adds, removes, checks, or lists available metrics.
+     *
+     * @see MetricRegistry
+     */
+    static metric = {
+        add: MetricRegistry.add,
+        remove: MetricRegistry.remove,
+        has: MetricRegistry.has,
+        list: MetricRegistry.list
+    };
+    /**
+     * Adds, removes, checks, or lists available phonetic algorithms and mappings.
+     *
+     * @see PhoneticRegistry
+     */
+    static phonetic = {
+        add: PhoneticRegistry.add,
+        remove: PhoneticRegistry.remove,
+        has: PhoneticRegistry.has,
+        list: PhoneticRegistry.list,
+        map: {
+            add: PhoneticMappingRegistry.add,
+            remove: PhoneticMappingRegistry.remove,
+            has: PhoneticMappingRegistry.has,
+            list: PhoneticMappingRegistry.list
+        }
+    };
+    /**
+     * Provides access to the global profiler services.
+     *
+     * @see Profiler
+     */
+    static profiler = profiler.services;
+    /**
+     * Clears the caches for normalizer, metric, and phonetic modules.
+     */
+    static clearCache = {
+        normalizer: Normalizer.clear,
+        metric: Metric.clear,
+        phonetic: Phonetic.clear
+    };
+    /**
+     * Returns a TextAnalyzer instance for the given input string.
+     *
+     * @param {string} [input] - The input string
+     * @returns {TextAnalyzer} - The text analyzer
+     */
+    static analyze(input) { return new TextAnalyzer(input); }
+    /**
+     * Returns a DiffChecker instance for computing the unified diff between two texts.
+     *
+     * @param {string} a - The first (original) text
+     * @param {string} b - The second (modified) text
+     * @param {DiffOptions} [opt] - Optional diff configuration
+     * @returns {DiffChecker} - The diff checker instance
+     */
+    static diff(a, b, opt) { return new DiffChecker(a, b, opt); }
+    /**
+     * --------------------------------------------------------------------------------
+     * Instanciate the CmpStr class
+     * --------------------------------------------------------------------------------
+     *
+     * Methods to create a new CmpStr instance with the given options.
+     * Using the static `create` method is recommended to ensure proper instantiation.
+     */
+    /**
+     * Creates a new CmpStr instance with the given options.
+     *
+     * @param {string|CmpStrOptions} [opt] - Optional serialized or options object
+     * @returns {CmpStr<R>} - A new CmpStr instance
+     */
+    static create(opt) { return new CmpStr(opt); }
+    // The options object that holds the configuration for this CmpStr instance
+    options = Object.create(null);
+    /**
+     * Creates a new CmpStr instance with the given options.
+     * The constructor is protected to enforce the use of the static `create` method.
+     *
+     * @param {string|CmpStrOptions} [opt] - Optional serialized or options object
+     */
+    constructor(opt) {
+        if (opt)
+            typeof opt === 'string'
+                ? this.setSerializedOptions(opt)
+                : this.setOptions(opt);
+    }
+    /**
+     * ---------------------------------------------------------------------------------
+     * Protected utility methods for internal use
+     * ---------------------------------------------------------------------------------
+     *
+     * These methods provide utility functions for converting inputs, merging options,
+     * normalizing inputs, filtering, and preparing inputs for comparison.
+     */
+    /**
+     * Assert a condition and throws if the condition is not met.
+     *
+     * @param {string} cond - The condition to met
+     * @param {any} [test] - Value to test for
+     * @throws {Error} If the condition is not met
+     */
+    assert(cond, test) {
+        switch (cond) {
+            // Check if the metric exists
+            case 'metric':
+                if (!CmpStr.metric.has(test))
+                    throw new Error(`CmpStr <metric> must be set, call .setMetric(), ` +
+                        `use CmpStr.metric.list() for available metrics`);
+                break;
+            // Check if the phonetic algorithm exists
+            case 'phonetic':
+                if (!CmpStr.phonetic.has(test))
+                    throw new Error(`CmpStr <phonetic> must be set, call .setPhonetic(), ` +
+                        `use CmpStr.phonetic.list() for available phonetic algorithms`);
+                break;
+            // Throw an error for unknown conditions
+            default: throw new Error(`Cmpstr condition <${cond}> unknown`);
+        }
+    }
+    /**
+     * Assert multiple conditions.
+     *
+     * @param {[ string, any? ][]} cond - Array of [ condition, value ] pairs
+     */
+    assertMany(...cond) {
+        for (const [c, test] of cond)
+            this.assert(c, test);
+    }
+    /**
+     * Resolves the options for the CmpStr instance, merging the provided options with
+     * the existing options.
+     *
+     * @param {CmpStrOptions} [opt] - Optional options to merge
+     * @returns {CmpStrOptions} - The resolved options
+     */
+    resolveOptions(opt) {
+        return merge({ ...(this.options ?? Object.create(null)) }, opt);
+    }
+    /**
+     * Normalizes the input string or array using the configured or provided flags.
+     *
+     * @param {MetricInput} input - The input string or array
+     * @param {NormalizeFlags} [flags] - Normalization flags
+     * @returns {MetricInput} - The normalized input
+     */
+    normalize(input, flags) {
+        return Normalizer.normalize(input, flags ?? this.options.flags ?? '');
+    }
+    /**
+     * Applies all active filters to the input string or array.
+     *
+     * @param {MetricInput} input - The input string or array
+     * @param {string} [hook='input'] - The filter hook
+     * @returns {MetricInput} - The filtered string(s)
+     */
+    filter(input, hook) {
+        return Filter.apply(hook, input);
+    }
+    /**
+     * Prepares the input by normalizing and filtering.
+     *
+     * @param {MetricInput} [input] - The input string or array
+     * @param {CmpStrOptions} [opt] - Optional options to use
+     * @returns {MetricInput} - The prepared input
+     */
+    prepare(input, opt) {
+        const { flags, processors } = opt ?? this.options;
+        // Normalize the input using flags (i.e., 'itw')
+        if (flags?.length)
+            input = this.normalize(input, flags);
+        // Filter the input using hooked up filters
+        input = this.filter(input, 'input');
+        // Apply phonetic processors if configured
+        if (processors?.phonetic)
+            input = this.index(input, processors.phonetic);
+        return input;
+    }
+    /**
+     * Post-process the results of the metric computation.
+     *
+     * @param {MetricResult<R>} result - The metric result
+     * @returns {MetricResult<R>} - The post-processed results
+     */
+    postProcess(result, opt) {
+        // Remove "zero similarity" from batch results if configured
+        if (opt?.removeZero && Array.isArray(result))
+            result = result.filter(r => r.res > 0);
+        return result;
+    }
+    /**
+     * Computes the phonetic index for the given input using the specified phonetic algorithm.
+     *
+     * @param {MetricInput} input - The input string or array
+     * @param {{ algo: string, opt?: PhoneticOptions }} options - The phonetic algorithm and options
+     * @returns {MetricInput} - The phonetic index for the given input
+     */
+    index(input, { algo, opt }) {
+        this.assert('phonetic', algo);
+        const phonetic = factory.phonetic(algo, opt);
+        const delimiter = opt?.delimiter ?? ' ';
+        return Array.isArray(input)
+            ? input.map(s => phonetic.getIndex(s).join(delimiter))
+            : phonetic.getIndex(input).join(delimiter);
+    }
+    /**
+     * Computes the metric result for the given inputs, applying normalization and
+     * filtering as configured.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The first input string or array
+     * @param {MetricInput} b - The second input string or array
+     * @param {CmpStrOptions} [opt] - Optional options to use
+     * @param {MetricMode} [mode='single'] - The metric mode to use
+     * @param {boolean} [raw=false] - Whether to return raw results
+     * @param {boolean} [skip=false] - Whether to skip normalization and filtering
+     * @returns {T} - The computed metric result
+     */
+    compute(a, b, opt, mode, raw, skip) {
+        const resolved = this.resolveOptions(opt);
+        this.assert('metric', resolved.metric);
+        // Prepare the input
+        const A = skip ? a : this.prepare(a, resolved);
+        const B = skip ? b : this.prepare(b, resolved);
+        // Get the metric class
+        const metric = factory.metric(resolved.metric, A, B, resolved.opt);
+        // Pass the original inputs to the metric
+        if (resolved.output !== 'prep')
+            metric.setOriginal(a, b);
+        // Compute the metric result
+        metric.run(mode);
+        // Post-process the results
+        const result = this.postProcess(metric.getResults(), resolved);
+        // Resolve and return the result based on the raw flag
+        return this.output(result, raw ?? resolved.raw);
+    }
+    /**
+     * Resolves the result format (raw or formatted).
+     *
+     * @template T - The type of the metric result
+     * @param {MetricResult<R>} result - The metric result
+     * @param {boolean} [raw] - Whether to return raw results
+     * @returns {T} - The resolved result
+     */
+    output(result, raw) {
+        return (raw ?? this.options.raw ? result : Array.isArray(result)
+            ? result.map(r => ({ source: r.a, target: r.b, match: r.res }))
+            : { source: result.a, target: result.b, match: result.res });
+    }
+    /**
+     * ---------------------------------------------------------------------------------
+     * Managing methods for CmpStr
+     * ---------------------------------------------------------------------------------
+     *
+     * These methods provides an interface to set and get properties of the CmpStr
+     * instance, such as options, metric, phonetic algorithm, and more.
+     */
+    /**
+     * Creates a shallow clone of the current instance.
+     *
+     * @returns {CmpStr<R>} - The cloned instance
+     */
+    clone() { return Object.assign(Object.create(Object.getPrototypeOf(this)), this); }
+    /**
+     * Resets the instance, clearing all data and options.
+     *
+     * @returns {this}
+     */
+    reset() { for (const k in this.options)
+        delete this.options[k]; return this; }
+    /**
+     * Sets / replaces the full options object.
+     *
+     * @param {CmpStrOptions} opt - The options
+     * @returns {this}
+     */
+    setOptions(opt) { this.options = opt; return this; }
+    /**
+     * Deep merges and sets new options.
+     *
+     * @param {CmpStrOptions} opt - The options to merge
+     * @returns {this}
+     */
+    mergeOptions(opt) { merge(this.options, opt); return this; }
+    /**
+     * Sets the serialized options from a JSON string.
+     *
+     * @param {string} opt - The serialized options
+     * @returns {this}
+     */
+    setSerializedOptions(opt) { this.options = JSON.parse(opt); return this; }
+    /**
+     * Sets a specific option at the given path.
+     *
+     * @param {string} path - The path to the option
+     * @param {any} value - The value to set
+     * @returns {this}
+     */
+    setOption(path, value) { set(this.options, path, value); return this; }
+    /**
+     * Removes an option at the given path.
+     *
+     * @param {string} path - The path to the option
+     * @returns {this}
+     */
+    rmvOption(path) { rmv(this.options, path); return this; }
+    /**
+     * Enable or disable raw output.
+     *
+     * @param {boolean} enable - Whether to enable or disable raw output
+     * @returns {this}
+     */
+    setRaw(enable) { return this.setOption('raw', enable); }
+    /**
+     * Sets the similatity metric to use (e.g., 'levenshtein', 'dice').
+     *
+     * @param {string} name - The metric name
+     * @returns {this}
+     */
+    setMetric(name) { return this.setOption('metric', name); }
+    /**
+     * Sets the normalization flags (e.g., 'itw', 'nfc').
+     *
+     * @param {NormalizeFlags} flags - The normalization flags
+     * @returns {this}
+     */
+    setFlags(flags) { return this.setOption('flags', flags); }
+    /**
+     * Removes the normalization flags entirely.
+     *
+     * @return {this}
+     */
+    rmvFlags() { return this.rmvOption('flags'); }
+    /**
+     * Sets the pre-processors to use for preparing the input.
+     *
+     * @param {CmpStrProcessors} opt - The processors to set
+     * @returns {this}
+     */
+    setProcessors(opt) { return this.setOption('processors', opt); }
+    /**
+     * Removes the processors entirely.
+     *
+     * @returns {this}
+     */
+    rmvProcessors() { return this.rmvOption('processors'); }
+    /**
+     * Returns the current options object.
+     *
+     * @returns {CmpStrOptions} - The options
+     */
+    getOptions() { return this.options; }
+    /**
+     * Returns the options as a JSON string.
+     *
+     * @returns {string} - The serialized options
+     */
+    getSerializedOptions() { return JSON.stringify(this.options); }
+    /**
+     * Returns a specific option value by path.
+     *
+     * @param {string} path - The path to the option
+     * @returns {any} - The option value
+     */
+    getOption(path) { return get(this.options, path); }
+    /**
+     * ---------------------------------------------------------------------------------
+     * Public core methods for string comparison
+     * ---------------------------------------------------------------------------------
+     *
+     * These methods provide the core functionality of the CmpStr class, allowing for
+     * string comparison, phonetic indexing, filtering, and text search.
+     */
+    /**
+     * Performs a single metric comparison between the source and target.
+     *
+     * @template T - The type of the metric result
+     * @param {string} a - The source string
+     * @param {string} b - The target string
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {T} - The metric result
+     */
+    test(a, b, opt) {
+        return this.compute(a, b, opt, 'single');
+    }
+    /**
+     * Performs a single metric comparison and returns only the numeric score.
+     *
+     * @param {string} a - The source string
+     * @param {string} b - The target string
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {number} - The similarity score (0..1)
+     */
+    compare(a, b, opt) {
+        return this.compute(a, b, opt, 'single', true).res;
+    }
+    /**
+     * Performs a batch metric comparison between source and target strings
+     * or array of strings.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {T} - The batch metric results
+     */
+    batchTest(a, b, opt) {
+        return this.compute(a, b, opt, 'batch');
+    }
+    /**
+     * Performs a batch metric comparison and returns results sorted by score.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {'desc'|'asc'} [dir='desc'] - Sort direction (desc, asc)
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {T} - The sorted batch results
+     */
+    batchSorted(a, b, dir = 'desc', opt) {
+        return this.output(this.compute(a, b, opt, 'batch', true)
+            .sort((a, b) => dir === 'asc' ? a.res - b.res : b.res - a.res), opt?.raw ?? this.options.raw);
+    }
+    /**
+     * Performs a pairwise metric comparison between source and target strings
+     * or array of strings.
+     *
+     * Input arrays needs of the same length to perform pairwise comparison,
+     * otherwise the method will throw an error.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {T} - The pairwise metric results
+     */
+    pairs(a, b, opt) {
+        return this.compute(a, b, opt, 'pairwise');
+    }
+    /**
+     * Performs a batch comparison and returns only results above the threshold.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {number} threshold - The similarity threshold (0..1)
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {T} - The filtered batch results
+     */
+    match(a, b, threshold, opt) {
+        return this.output(this.compute(a, b, opt, 'batch', true)
+            .filter(r => r.res >= threshold).sort((a, b) => b.res - a.res), opt?.raw ?? this.options.raw);
+    }
+    /**
+     * Returns the n closest matches from a batch comparison.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {number} [n=1] - Number of closest matches
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {T} - The closest matches
+     */
+    closest(a, b, n = 1, opt) {
+        return this.batchSorted(a, b, 'desc', opt).slice(0, n);
+    }
+    /**
+     * Returns the n furthest matches from a batch comparison.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {number} [n=1] - Number of furthest matches
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {T} - The furthest matches
+     */
+    furthest(a, b, n = 1, opt) {
+        return this.batchSorted(a, b, 'asc', opt).slice(0, n);
+    }
+    /**
+     * Performs a normalized and filtered substring search.
+     *
+     * @param {string} needle - The search string
+     * @param {string[]} haystack - The array to search in
+     * @param {NormalizeFlags} [flags] - Normalization flags
+     * @param {CmpStrProcessors} [processors] - Pre-processors to apply
+     * @returns {string[]} - Array of matching entries
+     */
+    search(needle, haystack, flags, processors) {
+        const resolved = this.resolveOptions({ flags, processors });
+        // Prepare the needle and haystack, normalizing and filtering them
+        const test = this.prepare(needle, resolved);
+        const hstk = this.prepare(haystack, resolved);
+        // Filter the haystack based on the normalized test string
+        return haystack.filter((_, i) => hstk[i].includes(test));
+    }
+    /**
+     * Computes a similarity matrix for the given input array.
+     *
+     * @param {string[]} input - The input array
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {number[][]} - The similarity matrix
+     */
+    matrix(input, opt) {
+        input = this.prepare(input, this.resolveOptions(opt));
+        return input.map(a => this.compute(a, input, undefined, 'batch', true, true).map(b => b.res ?? 0));
+    }
+    /**
+     * Computes the phonetic index for a string using the configured
+     * or given algorithm.
+     *
+     * @param {string} [input] - The input string
+     * @param {string} [algo] - The phonetic algorithm to use
+     * @param {PhoneticOptions} [opt] - Optional phonetic options
+     * @returns {string} - The phonetic index as a string
+     */
+    phoneticIndex(input, algo, opt) {
+        const { algo: a, opt: o } = this.options.processors?.phonetic ?? {};
+        return this.index(input, { algo: (algo ?? a), opt: opt ?? o });
+    }
+}
+
+/**
+ * CmpStrAsync Asynchronous API
+ * src/CmpStrAsync.ts
+ *
+ * The CmpStrAsync class provides a fully asynchronous, Promise-based interface for
+ * advanced string comparison, similarity measurement, phonetic indexing, filtering
+ * and normalization. It extends the CmpStr class and overrides all relevant methods
+ * to support non-blocking, scalable, and I/O-friendly workloads.
+ *
+ * Features:
+ *  - Asynchronous normalization, filtering, and metric computation
+ *  - Async batch, pairwise, and single string comparison with detailed results
+ *  - Async phonetic indexing and phonetic-aware search and comparison
+ *  - Full compatibility with the synchronous CmpStr API
+ *  - Designed for large-scale, high-performance, and server-side applications
+ *
+ * @module CmpStrAsync
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * The CmpStrAsync class provides a fully asynchronous API for string comparison,
+ * phonetic indexing, filtering and normalization.
+ *
+ * @template R - The type of the metric result, defaults to MetricRaw
+ */
+class CmpStrAsync extends CmpStr {
+    /**
+     * --------------------------------------------------------------------------------
+     * Instanciate the CmpStrAsync class
+     * --------------------------------------------------------------------------------
+     *
+     * Methods to create a new CmpStrAsync instance with the given options.
+     * Using the static `create` method is recommended to ensure proper instantiation.
+     */
+    /**
+     * Creates a new CmpStrAsync instance with the given options.
+     *
+     * @param {string|CmpStrOptions} [opt] - Optional serialized or options object
+     * @returns {CmpStrAsync<R>} - A new CmpStrAsync instance
+     */
+    static create(opt) {
+        return new CmpStrAsync(opt);
+    }
+    /**
+     * Creates a new CmpStrAsync instance calliing the super constructor.
+     *
+     * @param {string|CmpStrOptions} [opt] - Optional serialized or options object
+     */
+    constructor(opt) { super(opt); }
+    /**
+     * ---------------------------------------------------------------------------------
+     * Protected asynchronously utility methods for internal use
+     * ---------------------------------------------------------------------------------
+     *
+     * These methods provide asynchronous normalization, filtering, and metric
+     * computation capabilities, allowing for non-blocking operations.
+     */
+    /**
+     * Asynchronously normalizes the input string or array using the configured or provided flags.
+     *
+     * @param {MetricInput} input - The input string or array
+     * @param {NormalizeFlags} [flags] - Normalization flags
+     * @returns {Promise<MetricInput>} - The normalized input
+     */
+    async normalizeAsync(input, flags) {
+        return Normalizer.normalizeAsync(input, flags ?? this.options.flags ?? '');
+    }
+    /**
+     * Asynchronously applies all active filters to the input string or array.
+     *
+     * @param {MetricInput} input - The input string or array
+     * @param {string} [hook='input'] - The filter hook
+     * @returns {Promise<MetricInput>} - The filtered string(s)
+     */
+    async filterAsync(input, hook) {
+        return Filter.applyAsync(hook, input);
+    }
+    /**
+     * Asynchronously prepares the input by normalizing and filtering.
+     *
+     * @param {MetricInput} [input] - The input string or array
+     * @param {CmpStrOptions} [opt] - Optional options to use
+     * @returns {Promise<MetricInput>} - The prepared input
+     */
+    async prepareAsync(input, opt) {
+        const { flags, processors } = opt ?? this.options;
+        // Normalize the input using flags (i.e., 'itw')
+        if (flags?.length)
+            input = await this.normalizeAsync(input, flags);
+        // Filter the input using hooked up filters
+        input = await this.filterAsync(input, 'input');
+        // Apply phonetic processors if configured
+        if (processors?.phonetic)
+            input = await this.indexAsync(input, processors.phonetic);
+        return input;
+    }
+    /**
+     * Asynchronously computes the phonetic index for the given input using
+     * the specified phonetic algorithm.
+     *
+     * @param {MetricInput} input - The input string or array
+     * @param {{ algo: string, opt?: PhoneticOptions }} options - The phonetic algorithm and options
+     * @returns {Promise<MetricInput>} - The phonetic index for the given input
+     */
+    async indexAsync(input, { algo, opt }) {
+        this.assert('phonetic', algo);
+        const phonetic = factory.phonetic(algo, opt);
+        const delimiter = opt?.delimiter ?? ' ';
+        return Array.isArray(input)
+            ? Promise.all(input.map(s => phonetic.getIndexAsync(s).then(r => r.join(delimiter))))
+            : phonetic.getIndexAsync(input).then(r => r.join(delimiter));
+    }
+    /**
+     * Asynchronously computes the metric result for the given inputs, applying
+     * normalization and filtering as configured.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The first input string or array
+     * @param {MetricInput} b - The second input string or array
+     * @param {CmpStrOptions} [opt] - Optional options to use
+     * @param {MetricMode} [mode='single'] - The metric mode to use
+     * @param {boolean} [raw=false] - Whether to return raw results
+     * @param {boolean} [skip=false] - Whether to skip normalization and filtering
+     * @returns {Promise<T>} - The computed metric result
+     */
+    async computeAsync(a, b, opt, mode, raw, skip) {
+        const resolved = this.resolveOptions(opt);
+        this.assert('metric', resolved.metric);
+        // Prepare the input
+        const A = skip ? a : await this.prepareAsync(a, resolved);
+        const B = skip ? b : await this.prepareAsync(b, resolved);
+        // Get the metric class
+        const metric = factory.metric(resolved.metric, A, B, resolved.opt);
+        // Pass the original inputs to the metric
+        if (resolved.output !== 'prep')
+            metric.setOriginal(a, b);
+        // Compute the metric result
+        await metric.runAsync(mode);
+        // Post-process the results and concat the original inputs
+        const result = this.postProcess(metric.getResults(), resolved);
+        // Resolve and return the result based on the raw flag
+        return this.output(result, raw ?? resolved.raw);
+    }
+    /**
+     * ---------------------------------------------------------------------------------
+     * Public asynchronously core methods for string comparison
+     * ---------------------------------------------------------------------------------
+     *
+     * These methods provide the asynchronous core functionality for string comparison,
+     * phonetic indexing and text search, allowing for non-blocking operations.
+     */
+    /**
+     * Asynchronously performs a single metric comparison.
+     *
+     * @template T - The type of the metric result
+     * @param {string} a - The source string
+     * @param {string} b - The target string
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {Promise<T>} - The metric result
+     */
+    async testAsync(a, b, opt) {
+        return this.computeAsync(a, b, opt, 'single');
+    }
+    /**
+     * Asynchronously performs a single metric comparison returning the numeric score.
+     *
+     * @param {string} a - The source string
+     * @param {string} b - The target string
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {Promise<number>} - The similarity score (0..1)
+     */
+    async compareAsync(a, b, opt) {
+        return (await this.computeAsync(a, b, opt, 'single', true)).res;
+    }
+    /**
+     * Asynchronously performs a batch metric comparison between source and target
+     * strings or array of strings.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {Promise<T>} - The batch metric results
+     */
+    async batchTestAsync(a, b, opt) {
+        return this.computeAsync(a, b, opt, 'batch');
+    }
+    /**
+     * Asynchronously performs a batch metric comparison and returns results sorted by score.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {'desc'|'asc'} [dir='desc'] - Sort direction (desc, asc)
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {Promise<T>} - The sorted batch results
+     */
+    async batchSortedAsync(a, b, dir = 'desc', opt) {
+        const res = await this.computeAsync(a, b, opt, 'batch', true);
+        return this.output(res.sort((a, b) => dir === 'asc' ? a.res - b.res : b.res - a.res), opt?.raw ?? this.options.raw);
+    }
+    /**
+     * Asynchronously performs a pairwise metric comparison between source and target
+     * strings or array of strings.
+     *
+     * @template T - The type of the metric result
+     * Input arrays needs of the same length to perform pairwise comparison,
+     * otherwise the method will throw an error.
+     *
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {Promise<T>} - The pairwise metric results
+     */
+    async pairsAsync(a, b, opt) {
+        return this.computeAsync(a, b, opt, 'pairwise');
+    }
+    /**
+     * Asynchronously performs a batch comparison and returns only results above the threshold.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {number} threshold - The similarity threshold (0..1)
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {Promise<T>} - The filtered batch results
+     */
+    async matchAsync(a, b, threshold, opt) {
+        const res = await this.computeAsync(a, b, opt, 'batch', true);
+        return this.output(res.filter(r => r.res >= threshold).sort((a, b) => b.res - a.res), opt?.raw ?? this.options.raw);
+    }
+    /**
+     * Asynchronously returns the n closest matches from a batch comparison.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {number} [n=1] - Number of closest matches
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {Promise<T>} - The closest matches
+     */
+    async closestAsync(a, b, n = 1, opt) {
+        return (await this.batchSortedAsync(a, b, 'desc', opt)).slice(0, n);
+    }
+    /**
+     * Asynchronously returns the n furthest matches from a batch comparison.
+     *
+     * @template T - The type of the metric result
+     * @param {MetricInput} a - The source string or array of strings
+     * @param {MetricInput} b - The target string or array of strings
+     * @param {number} [n=1] - Number of furthest matches
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {Promise<T>} - The furthest matches
+     */
+    async furthestAsync(a, b, n = 1, opt) {
+        return (await this.batchSortedAsync(a, b, 'asc', opt)).slice(0, n);
+    }
+    /**
+     * Asynchronously performs a normalized and filtered substring search.
+     *
+     * @param {string} needle - The search string
+     * @param {string[]} haystack - The array to search in
+     * @param {NormalizeFlags} [flags] - Normalization flags
+     * @param {CmpStrProcessors} [processors] - Pre-processors to apply
+     * @returns {Promise<string[]>} - Array of matching entries
+     */
+    async searchAsync(needle, haystack, flags, processors) {
+        const resolved = this.resolveOptions({ flags, processors });
+        // Prepare the needle and haystack, normalizing and filtering them
+        const test = await this.prepareAsync(needle, resolved);
+        const hstk = await this.prepareAsync(haystack, resolved);
+        // Filter the haystack based on the normalized test string
+        return haystack.filter((_, i) => hstk[i].includes(test));
+    }
+    /**
+     * Asynchronously computes a similarity matrix for the given input array.
+     *
+     * @param {string[]} input - The input array
+     * @param {CmpStrOptions} [opt] - Optional options
+     * @returns {Promise<number[][]>} - The similarity matrix
+     */
+    async matrixAsync(input, opt) {
+        input = await this.prepareAsync(input, this.resolveOptions(opt));
+        return Promise.all(input.map(async (a) => (await this.computeAsync(a, input, undefined, 'batch', true, true).then(r => r.map(b => b.res ?? 0)))));
+    }
+    /**
+     * Asynchronously computes the phonetic index for a string using the
+     * configured or given algorithm.
+     *
+     * @param {string} [input] - The input string
+     * @param {string} [algo] - The phonetic algorithm to use
+     * @param {PhoneticOptions} [opt] - Optional phonetic options
+     * @returns {Promise<string>} - The phonetic index as a string
+     */
+    async phoneticIndexAsync(input, algo, opt) {
+        const { algo: a, opt: o } = this.options.processors?.phonetic ?? {};
+        return this.indexAsync(input, {
+            algo: (algo ?? a), opt: opt ?? o
+        });
+    }
+}
+
+export { CmpStr, CmpStrAsync, DiffChecker, Normalizer, TextAnalyzer };
+//# sourceMappingURL=CmpStr.esm.js.map