cmpstr 2.0.0 → 2.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 CmpStr is a lightweight and powerful npm package for calculating string similarity, finding the closest matches in arrays, performing phonetic searches, and more. It supports a variety of built-in algorithms (e.g., Levenshtein, Dice-Sørensen, Damerau-Levenshtein, Soundex) and allows users to add custom algorithms and normalization filters.
 
-#### Key Features
+**Key Features**
 
 - Built-in support for multiple similarity algorithms.
 - Phonetic search with language-specific configurations (e.g., Soundex).
@@ -10,6 +10,7 @@ CmpStr is a lightweight and powerful npm package for calculating string similari
 - Customizable normalization with global flags and caching.
 - Asynchronous support for non-blocking workflows.
 - Extensible with custom algorithms and filters.
+- TypeScript declarations for better developer experience.
 
 ## Installation
 
@@ -61,15 +62,19 @@ Sets the base string for comparison.
 
 Parameters:
 
-- `<String> str` – string to set as the base
+`<String> str` – string to set as the base
+
+#### `getStr()`
+
+Gets the base string for comparison.
 
 #### `setFlags( [ flags = '' ] )`
 
 Set default normalization flags. They will be overwritten by passing `flags` through the configuration object. See description of available flags / normalization options below in the documentation.
 
-Parameters:
+#### `getFlags()`
 
-- `<String> flags` – normalization flags
+Gets the default normalization flags.
 
 #### `clearCache()`
 
@@ -77,17 +82,21 @@ Clears the normalization cache.
 
 ### Algorithms
 
-#### `listAlgo()`
+#### `listAlgo( [ loadedOnly = false ] )`
 
 List all registered similarity algorithms.
 
+Parameters:
+
+`<Boolean> loadedOnly` – it true, only loaded algorithm names are returned
+
 #### `isAlgo( algo )`
 
 Checks if an algorithm is registered. Returns `true` if so, `false` otherwise.
 
 Parameters:
 
-- `<String> algo` – name of the algorithm
+`<String> algo` – name of the algorithm
 
 #### `setAlgo( algo )`
 
@@ -97,7 +106,11 @@ Allowed options for build-in althorithms are `cosine`, `damerau`, `dice`, `hammi
 
 Parameters:
 
-- `<String> algo` – name of the algorithm
+`<String> algo` – name of the algorithm
+
+#### `getAlgo()`
+
+Gets the current algorithm to use for similarity calculations.
 
 #### `addAlgo( algo, callback [, useIt = true ] )`
 
@@ -105,9 +118,9 @@ Adding a new similarity algorithm by using the `addAlgo()` method passing the na
 
 Parameters:
 
-- `<String> algo` – name of the algorithm
-- `<Function> callback` – callback function implementing the algorithm
-- `<Boolean> useIt` – whether to set this algorithm as the current one
+`<String> algo` – name of the algorithm  
+`<Function> callback` – callback function implementing the algorithm  
+`<Boolean> useIt` – whether to set this algorithm as the current one
 
 Example:
 
@@ -128,7 +141,7 @@ Removing a registered similarity algorithm.
 
 Parameters:
 
-- `<String> algo` – name of the algorithm
+`<String> algo` – name of the algorithm
 
 ### Filters
 
@@ -142,9 +155,9 @@ Adds a custom normalization filter. Needs to be passed a unique name and callbac
 
 Parameters:
 
-- `<String> name` – filter name
-- `<Function> callback` – callback function implementing the filter
-- `<Int> priority` – priority of the filter
+`<String> name` – filter name  
+`<Function> callback` – callback function implementing the filter  
+`<Int> priority` – priority of the filter
 
 Example:
 
@@ -160,7 +173,7 @@ Removes a custom normalization filter.
 
 Parameters:
 
-- `<String> name` – filter name
+`<String> name` – filter name
 
 #### `pauseFilter( name )`
 
@@ -168,7 +181,7 @@ Pauses a custom normalization filter.
 
 Parameters:
 
-- `<String> name` – filter name
+`<String> name` – filter name
 
 #### `resumeFilter( name )`
 
@@ -176,7 +189,7 @@ Resumes a custom normalization filter.
 
 Parameters:
 
-- `<String> name` – filter name
+`<String> name` – filter name
 
 #### `clearFilter( name )`
 
@@ -190,10 +203,10 @@ Compares two strings using the specified algorithm. The method returns either th
 
 Parameters:
 
-- `<String> algo` – name of the algorithm
-- `<String> a` – first string
-- `<String> b` – second string
-- `<Object> config` – configuration object
+`<String> algo` – name of the algorithm  
+`<String> a` – first string  
+`<String> b` – second string  
+`<Object> config` – configuration object
 
 Example:
 
@@ -210,8 +223,8 @@ Tests the similarity between the base string and a given target string. Returns
 
 Parameters:
 
-- `<String> str` – target string
-- `<Object> config` – configuration object
+`<String> str` – target string  
+`<Object> config` – configuration object
 
 Example:
 
@@ -228,8 +241,8 @@ Tests the similarity of multiple strings against the base string. Returns an arr
 
 Parameters:
 
-- `<String[]> arr` – array of strings
-- `<Object> config` – configuration object
+`<String[]> arr` – array of strings  
+`<Object> config` – configuration object
 
 Example:
 
@@ -246,8 +259,8 @@ Finds strings in an array that exceed a similarity threshold and sorts them by h
 
 Parameters:
 
-- `<String[]> arr` – array of strings
-- `<Object> config` – configuration object
+`<String[]> arr` – array of strings  
+`<Object> config` – configuration object
 
 Example:
 
@@ -266,8 +279,8 @@ Finds the closest matching string from an array and returns them.
 
 Parameters:
 
-- `<String[]> arr` – array of strings
-- `<Object> config` – configuration object
+`<String[]> arr` – array of strings  
+`<Object> config` – configuration object
 
 Example:
 
@@ -284,9 +297,9 @@ Generates a similarity matrix for an array of strings. Returns an 2D array that
 
 Parameters:
 
-- `<String> algo` – name of the algorithm
-- `<String[]> arr` – array of strings
-- `<Object> config` – configuration object
+`<String> algo` – name of the algorithm  
+`<String[]> arr` – array of strings  
+`<Object> config` – configuration object
 
 Example:
 
@@ -307,24 +320,24 @@ The `CmpStr` package allows strings to be normalized before the similarity compa
 
 #### Supported Flags
 
-- `s` – remove special chars
-- `w` – collapse whitespaces
-- `r` – remove repeated chars
-- `k` – keep only letters
-- `n` – ignore numbers
-- `t` – trim whitespaces
-- `i` – case insensitivity
-- `d` – decompose unicode
-- `u` – normalize unicode
+`s` – remove special chars  
+`w` – collapse whitespaces  
+`r` – remove repeated chars  
+`k` – keep only letters  
+`n` – ignore numbers  
+`t` – trim whitespaces  
+`i` – case insensitivity  
+`d` – decompose unicode  
+`u` – normalize unicode
 
-#### `normalize( str [, flags = '' ] )`
+#### `normalize( input [, flags = '' ] )`
 
 The method for normalizing strings can also be called on its own, without comparing the similarity of two strings. This also applies all filters and reads or writes to the cache. This can be helpful if certain strings should be saved beforehand or different normalization options want to be tested.
 
 Parameters:
 
-- `<String> str` – string to normalize
-- `<String> flags` normalization flags
+`<String|String[]> input` – single string or array of strings to normalize  
+`<String> flags` normalization flags
 
 Example:
 
@@ -333,6 +346,9 @@ const cmp = new CmpStr();
 
 console.log( cmp.normalize( '   he123LLo  ', 'nti' ) );
 // Output: hello
+
+console.log( cmp.normalize( [ 'Hello World!', 'CmpStr 123' ], 'nwti' ) );
+// Output: [ 'hello world!', 'cmpstr' ]
 ```
 
 ### Configuration Object
@@ -343,9 +359,9 @@ It also contains `options` as an object of key-value pairs that are passed to th
 
 Global config options:
 
-- `<String> flags` – normalization flags
-- `<Number> threshold` – similarity threshold between 0 and 1
-- `<Object> options` – options passed to the algorithm
+`<String> flags` – normalization flags  
+`<Number> threshold` – similarity threshold between 0 and 1  
+`<Object> options` – options passed to the algorithm
 
 Example:
 
@@ -368,9 +384,9 @@ console.log( cmp.match( [
 
 ## Asynchronous Support
 
-The `CmpStrAsync` class provides asynchronous versions of all comparison methods. It is ideal for large datasets or non-blocking workflows.
+The `CmpStrAsync` class provides an asynchronous wrapper for all comparison methods as well as the string normalization function. It is ideal for large datasets or non-blocking workflows.
 
-The asynchronous class supports the methods `compareAsync`, `testAsync`, `batchTestAsync`, `matchAsync`, `closestAsync` and `similarityMatrixAsync`. Each of these methods returns a `Promise`.
+The asynchronous class supports the methods `normalizeAsync`, `compareAsync`, `testAsync`, `batchTestAsync`, `matchAsync`, `closestAsync` and `similarityMatrixAsync`. Each of these methods returns a `Promise`.
 
 For options, arguments and returned values, see the documentation above.
 
@@ -398,7 +414,7 @@ The Levenshtein distance between two strings is the minimum number of single-cha
 
 Options:
 
-- `<Boolean> raw` – if true the raw distance is returned
+`<Boolean> raw` – if true the raw distance is returned
 
 #### Damerau-Levenshtein – `damerau`
 
@@ -406,7 +422,7 @@ The Damerau-Levenshtein distance differs from the classical Levenshtein distance
 
 Options:
 
-- `<Boolean> raw` – if true the raw distance is returned
+`<Boolean> raw` – if true the raw distance is returned
 
 #### Jaro-Winkler – `jaro`
 
@@ -414,7 +430,7 @@ Jaro-Winkler is a string similarity metric that gives more weight to matching ch
 
 Options:
 
-- `<Boolean> raw` – if true the raw distance is returned
+`<Boolean> raw` – if true the raw distance is returned
 
 #### Cosine Similarity – `cosine`
 
@@ -422,7 +438,7 @@ Cosine similarity is a measure how similar two vectors are. It's often used in t
 
 Options:
 
-- `<String> delimiter` – term delimiter
+`<String> delimiter` – term delimiter
 
 #### Dice Coefficient – `dice`
 
@@ -446,9 +462,9 @@ The Needleman-Wunsch algorithm performs global alignment, aligning two strings e
 
 Options:
 
-- `<Number> match` – score for a match
-- `<Number> mismatch` – penalty for a mismatch
-- `<Number> gap` – penalty for a gap
+`<Number> match` – score for a match  
+`<Number> mismatch` – penalty for a mismatch  
+`<Number> gap` – penalty for a gap
 
 #### Smith-Waterman – `smithWaterman`
 
@@ -456,9 +472,9 @@ The Smith-Waterman algorithm performs local alignment, finding the best matching
 
 Options:
 
-- `<Number> match` – score for a match
-- `<Number> mismatch` – penalty for a mismatch
-- `<Number> gap` – penalty for a gap
+`<Number> match` – score for a match  
+`<Number> mismatch` – penalty for a mismatch  
+`<Number> gap` – penalty for a gap
 
 #### q-Gram – `qGram`
 
@@ -466,7 +482,7 @@ Q-gram similarity is a string-matching algorithm that compares two strings by br
 
 Options:
 
-- `<Int> q` length of substrings
+`<Int> q` length of substrings
 
 ### Phonetic Algorithms
 
@@ -476,8 +492,8 @@ The Soundex algorithm generates a phonetic representation of a string based on h
 
 Options:
 
-- `<String> lang` – language code for predefined setups (e.g., `en`, `de`)
-- `<Boolean> raw` – if true, returns the raw sound index codes
-- `<Object> mapping` – custom phonetic mapping (overrides predefined)
-- `<String> exclude` – characters to exclude from the input (overrides predefined)
-- `<Number> maxLength` – maximum length of the phonetic code
+`<String> lang` – language code for predefined setups (e.g., `en`, `de`)  
+`<Boolean> raw` – if true, returns the raw sound index codes  
+`<Object> mapping` – custom phonetic mapping (overrides predefined)  
+`<String> exclude` – characters to exclude from the input (overrides predefined)  
+`<Number> maxLength` – maximum length of the phonetic code

package/package.json

@@ -7,8 +7,9 @@
     "url" : "https://komed3.de"
   },
   "homepage": "https://github.com/komed3/cmpstr#readme",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "license": "MIT",
   "keywords": [
     "string-similarity",
@@ -35,7 +36,8 @@
     "text-processing",
     "fuzzy-matching",
     "string-matching",
-    "text-similarity"
+    "text-similarity",
+    "typescript-definitions"
   ],
   "repository": {
     "type": "git",

package/src/CmpStr.d.ts

@@ -0,0 +1,70 @@
+export interface Config {
+    flags?: string;
+    threshold?: number;
+    options?: Record<string, any>;
+}
+
+export interface BatchResult {
+    target: string;
+    match: number | any;
+}
+
+export declare class CmpStr {
+
+    constructor ( algo?: string, str?: string );
+
+    isReady () : boolean;
+
+    setStr ( str: string ) : boolean;
+
+    getStr () : string;
+
+    listAlgo ( loadedOnly?: boolean ) : string[];
+
+    isAlgo ( algo: string ) : boolean;
+
+    setAlgo ( algo: string ) : boolean;
+
+    getAlgo () : string;
+
+    addAlgo ( algo: string, callback: (
+        a: string, b: string, ...args : any
+    ) => number | any, useIt?: boolean ) : boolean;
+
+    rmvAlgo( algo: string ) : boolean;
+
+    listFilter () : string[];
+
+    addFilter ( name: string, callback: (
+        str: string
+    ) => string, priority?: number ) : boolean;
+
+    rmvFilter ( name: string ) : boolean;
+
+    pauseFilter ( name: string ) : boolean;
+
+    resumeFilter ( name: string ) : boolean;
+
+    clearFilter () : boolean;
+
+    setFlags( flags: string ) : void;
+
+    getFlags () : string;
+
+    normalize ( input: string|string[], flags?: string ) : string|string[];
+
+    clearCache () : boolean;
+
+    compare ( algo: string, a: string, b: string, config?: Config ) : number | any;
+
+    test ( str: string, config?: Config ) : number | any;
+
+    batchTest ( arr: string[], config?: Config ) : BatchResult[];
+
+    match ( arr: string[], config?: Config ) : BatchResult[];
+
+    closest ( arr: string[], config?: Config ) : string | undefined;
+
+    similarityMatrix ( algo: string, arr: string[], config?: Config ) : number[][];
+
+}

package/src/CmpStr.js

@@ -20,6 +20,12 @@
 
 module.exports = class CmpStr {
 
+    /**
+     * --------------------------------------------------
+     * Global Variables
+     * --------------------------------------------------
+     */
+
     /**
      * all pre-defined similarity algorithms
      * 
@@ -41,6 +47,15 @@ module.exports = class CmpStr {
         soundex: './algorithms/soundex'
     };
 
+    /**
+     * stores the names of loaded algorithms
+     * 
+     * @since 2.0.2
+     * @private
+     * @type {Set<String>}
+     */
+    #loadedAlgo = new Set ();
+
     /**
      * normalized strings cache
      * 
@@ -61,28 +76,43 @@ module.exports = class CmpStr {
      * default normalization flags
      * set by setFlags()
      * 
-     * @public
+     * @private
+     * @type {String}
+     */
+    #flags = '';
+
+    /**
+     * current algorithm to use for similarity calculations
+     * set by setAlgo(), addAlgo() or constructor()
+     * 
+     * @private
      * @type {String}
      */
-    flags = '';
+    #algo;
 
     /**
      * base string for comparison
      * set by setStr or constructor()
      * 
-     * @public
+     * @private
      * @type {String}
      */
-    str;
+    #str;
 
     /**
-     * current algorithm to use for similarity calculations
-     * set by setAlgo(), addAlgo() or constructor()
+     * stores the current ready state
      * 
-     * @public
-     * @type {String}
+     * @since 2.0.2
+     * @private
+     * @type {Boolean}
+     */
+    #readyState = false;
+
+    /**
+     * --------------------------------------------------
+     * Constructor
+     * --------------------------------------------------
      */
-    algo;
 
     /**
      * initializes a CmpStr instance
@@ -107,6 +137,12 @@ module.exports = class CmpStr {
 
     };
 
+    /**
+     * --------------------------------------------------
+     * Ready State
+     * --------------------------------------------------
+     */
+
     /**
      * checks whether string and algorithm are set correctly
      * 
@@ -114,11 +150,23 @@ module.exports = class CmpStr {
      */
     isReady () {
 
-        return (
-            typeof this.algo === 'string' &&
-            this.isAlgo( this.algo ) &&
-            typeof this.str === 'string' &&
-            this.str.length != 0
+        return this.#readyState;
+
+    };
+
+    /**
+     * updates the readiness state
+     * 
+     * @since 2.0.2
+     * @private
+     */
+    #updateReadyState () {
+
+        this.#readyState = (
+            typeof this.#algo === 'string' &&
+            this.isAlgo( this.#algo ) &&
+            typeof this.#str === 'string' &&
+            this.#str.length !== 0
         );
 
     };
@@ -126,12 +174,13 @@ module.exports = class CmpStr {
     /**
      * checks ready state and throws an error if not
      * 
+     * @private
      * @returns {Boolean} true if ready
      * @throws {Error} if CmpStr is not ready
      */
-    _checkReady () {
+    #checkReady () {
 
-        if ( !this.isReady() ) {
+        if ( !this.#readyState ) {
 
             throw new Error(
                 `CmpStr instance is not ready. Ensure the algorithm and base string are set.`
@@ -143,6 +192,12 @@ module.exports = class CmpStr {
 
     };
 
+    /**
+     * --------------------------------------------------
+     * Base String
+     * --------------------------------------------------
+     */
+
     /**
      * sets the base string for comparison
      * 
@@ -151,12 +206,26 @@ module.exports = class CmpStr {
      */
     setStr ( str ) {
 
-        this.str = String ( str );
+        this.#str = String ( str );
+
+        this.#updateReadyState();
 
         return true;
 
     };
 
+    /**
+     * gets the base string for comparison
+     * 
+     * @since 2.0.2
+     * @returns {String} base string
+     */
+    getStr () {
+
+        return this.#str;
+
+    };
+
     /**
      * --------------------------------------------------
      * Algorithms
@@ -166,11 +235,14 @@ module.exports = class CmpStr {
     /**
      * list all registered similarity algorithms
      * 
+     * @param {Boolean} [loadedOnly=false] it true, only loaded algorithm names are returned
      * @returns {String[]} array of algorithm names
      */
-    listAlgo () {
+    listAlgo ( loadedOnly = false ) {
 
-        return [ ...Object.keys( this.#algorithms ) ];
+        return loadedOnly
+            ? [ ...this.#loadedAlgo ]
+            : [ ...Object.keys( this.#algorithms ) ];
 
     };
 
@@ -194,9 +266,11 @@ module.exports = class CmpStr {
      */
     setAlgo ( algo ) {
 
-        if ( this._loadAlgo( algo ) ) {
+        if ( this.#loadAlgo( algo ) ) {
 
-            this.algo = algo;
+            this.#algo = algo;
+
+            this.#updateReadyState();
 
             return true;
 
@@ -204,6 +278,18 @@ module.exports = class CmpStr {
 
     };
 
+    /**
+     * gets the current algorithm to use for similarity calculations
+     * 
+     * @since 2.0.2
+     * @returns {String} name of the algorithm
+     */
+    getAlgo () {
+
+        return this.#algo;
+
+    };
+
     /**
      * adds a new similarity algorithm
      * 
@@ -255,11 +341,15 @@ module.exports = class CmpStr {
 
             delete this.#algorithms[ algo ];
 
-            if ( this.algo === algo ) {
+            this.#loadedAlgo.delete( algo );
+
+            if ( this.#algo === algo ) {
 
                 /* reset current algorithm if it was removed */
 
-                this.algo = undefined;
+                this.#algo = undefined;
+
+                this.#updateReadyState();
 
             }
 
@@ -278,18 +368,25 @@ module.exports = class CmpStr {
     /**
      * lazy-loads the specified algorithm module
      * 
+     * @private
      * @param {String} algo name of the similarity algorithm
      * @returns {Boolean} true if the algorithm is loaded
      * @throws {Error} if the algorithm cannot be loaded or is not defined
      */
-    _loadAlgo ( algo ) {
+    #loadAlgo ( algo ) {
 
-        if ( this.isAlgo( algo ) ) {
+        if ( this.#loadedAlgo.has( algo ) ) {
+
+            return true;
+
+        } else if ( this.isAlgo( algo ) ) {
 
             let typeOf = typeof this.#algorithms[ algo ];
 
             if ( typeOf === 'function' ) {
 
+                this.#loadedAlgo.add( algo );
+
                 return true;
 
             } else if ( typeOf === 'string' ) {
@@ -302,6 +399,8 @@ module.exports = class CmpStr {
                         this.#algorithms[ algo ]
                     );
 
+                    this.#loadedAlgo.add( algo );
+
                     return true;
 
                 } catch ( err ) {
@@ -482,11 +581,12 @@ module.exports = class CmpStr {
     /**
      * applies all active filters to a string
      * 
+     * @private
      * @param {String} str string to process
      * @returns {String} filtered string
      * @throws {Error} if applying filters cause an error
      */
-    _applyFilters ( str ) {
+    #applyFilters ( str ) {
 
         try {
 
@@ -524,7 +624,19 @@ module.exports = class CmpStr {
      */
     setFlags ( flags = '' ) {
 
-        this.flags = String ( flags );
+        this.#flags = String ( flags );
+
+    };
+
+    /**
+     * get default normalization flags
+     * 
+     * @since 2.0.2
+     * @returns {String} normalization flags
+     */
+    getFlags () {
+
+        return this.#flags;
 
     };
 
@@ -544,57 +656,73 @@ module.exports = class CmpStr {
      * d :: decompose unicode
      * u :: normalize unicode
      * 
-     * @param {String} string string to normalize
+     * @param {String|String[]} string string(s) to normalize
      * @param {String} [flags=''] normalization flags
-     * @returns {String} normalized string
+     * @returns {String|String[]} normalized string(s)
      * @throws {Error} if normalization cause an error
      */
-    normalize ( str, flags = '' ) {
+    normalize ( input, flags = '' ) {
 
-        let res = String ( str );
+        const processStr = ( str ) => {
 
-        /* use normalized string from cache to increase performance */
+            let res = String ( str );
 
-        let key = `${res}::${flags}`;
+            /* use normalized string from cache to increase performance */
 
-        if ( this.#cache.has( key ) ) {
+            let key = `${res}::${flags}`;
 
-            return this.#cache.get( key );
+            if ( this.#cache.has( key ) ) {
 
-        }
+                return this.#cache.get( key );
 
-        /* apply custom filters */
+            }
 
-        res = this._applyFilters( res );
+            /* apply custom filters */
 
-        /* normalize using flags */
+            res = this.#applyFilters( res );
 
-        try {
+            /* normalize using flags */
 
-            if ( flags.includes( 's' ) ) res = res.replace( /[^a-z0-9]/gi, '' );
-            if ( flags.includes( 'w' ) ) res = res.replace( /\s+/g, ' ' );
-            if ( flags.includes( 'r' ) ) res = res.replace( /(.)\1+/g, '$1' );
-            if ( flags.includes( 'k' ) ) res = res.replace( /[^a-z]/gi, '' );
-            if ( flags.includes( 'n' ) ) res = res.replace( /[0-9]/g, '' );
-            if ( flags.includes( 't' ) ) res = res.trim();
-            if ( flags.includes( 'i' ) ) res = res.toLowerCase();
-            if ( flags.includes( 'd' ) ) res = res.normalize( 'NFD' ).replace( /[\u0300-\u036f]/g, '' );
-            if ( flags.includes( 'u' ) ) res = res.normalize( 'NFC' );
+            try {
 
-        } catch ( err ) {
+                if ( flags.includes( 's' ) ) res = res.replace( /[^a-z0-9]/gi, '' );
+                if ( flags.includes( 'w' ) ) res = res.replace( /\s+/g, ' ' );
+                if ( flags.includes( 'r' ) ) res = res.replace( /(.)\1+/g, '$1' );
+                if ( flags.includes( 'k' ) ) res = res.replace( /[^a-z]/gi, '' );
+                if ( flags.includes( 'n' ) ) res = res.replace( /[0-9]/g, '' );
+                if ( flags.includes( 't' ) ) res = res.trim();
+                if ( flags.includes( 'i' ) ) res = res.toLowerCase();
+                if ( flags.includes( 'd' ) ) res = res.normalize( 'NFD' ).replace( /[\u0300-\u036f]/g, '' );
+                if ( flags.includes( 'u' ) ) res = res.normalize( 'NFC' );
 
-            throw new Error (
-                `Error while normalization.`,
-                { cause: err }
-            );
+            } catch ( err ) {
+
+                throw new Error (
+                    `Error while normalization.`,
+                    { cause: err }
+                );
+
+            }
+
+            /* store the normalized string in the cache */
+
+            this.#cache.set( key, res );
+
+            return res;
 
         }
 
-        /* store the normalized string in the cache */
+        /* processing multiple string */
+
+        if ( Array.isArray( input ) ) {
 
-        this.#cache.set( key, res );
+            return input.map(
+                ( str ) => processStr( str )
+            );
+
+        }
 
-        return res;
+        return processStr( input );
 
     };
 
@@ -629,7 +757,7 @@ module.exports = class CmpStr {
      */
     compare ( algo, a, b, config = {} ) {
 
-        if ( this._loadAlgo( algo ) ) {
+        if ( this.#loadAlgo( algo ) ) {
 
             /* handle trivial cases */
 
@@ -639,7 +767,7 @@ module.exports = class CmpStr {
             /* apply similarity algorithm */
 
             const {
-                flags = this.flags,
+                flags = this.#flags,
                 options = {}
             } = config;
 
@@ -674,11 +802,11 @@ module.exports = class CmpStr {
      */
     test ( str, config = {} ) {
 
-        if ( this._checkReady() ) {
+        if ( this.#checkReady() ) {
 
             return this.compare(
-                this.algo,
-                this.str, str,
+                this.#algo,
+                this.#str, str,
                 config
             );
 
@@ -695,13 +823,13 @@ module.exports = class CmpStr {
      */
     batchTest ( arr, config = {} ) {
 
-        if ( this._checkReady() ) {
+        if ( this.#checkReady() ) {
 
             return [ ...arr ].map( ( str ) => ( {
                 target: str,
                 match: this.compare(
-                    this.algo,
-                    this.str, str,
+                    this.#algo,
+                    this.#str, str,
                     config
                 )
             } ) );
@@ -763,7 +891,7 @@ module.exports = class CmpStr {
      */
     similarityMatrix ( algo, arr, config = {} ) {
 
-        if ( this._loadAlgo( algo ) ) {
+        if ( this.#loadAlgo( algo ) ) {
 
             delete config?.options?.raw;
 

package/src/CmpStrAsync.d.ts

@@ -0,0 +1,19 @@
+import { CmpStr, Config, BatchResult } from './CmpStr';
+
+export declare class CmpStrAsync extends CmpStr {
+
+    normalizeAsync ( input: string|string[], flags?: string ) : string|string[];
+
+    compareAsync ( algo: string, a: string, b: string, config?: Config ) : Promise<number | any>;
+
+    testAsync ( str: string, config?: Config ) : Promise<number | any>;
+
+    batchTestAsync ( arr: string[], config?: Config ) : Promise<BatchResult[]>;
+
+    matchAsync ( arr: string[], config?: Config ) : Promise<BatchResult[]>;
+
+    closestAsync ( arr: string[], config?: Config ) : Promise<string | undefined>;
+
+    similarityMatrixAsync ( algo: string, arr: string[], config?: Config ) : Promise<number[][]>;
+
+}

package/src/CmpStrAsync.js

@@ -40,9 +40,10 @@ module.exports = class CmpStrAsync extends CmpStr {
     };
 
     /**
-     * @private
      * generic async wrapper for methods
+     * @async
      * 
+     * @private
      * @param {Function} method method to call
      * @param {...any} args arguments to pass to the method
      * @returns {Promise} Promise resolving the result of the method
@@ -76,8 +77,25 @@ module.exports = class CmpStrAsync extends CmpStr {
      */
 
     /**
-     * compares two string a and b using the passed algorithm
+     * normalizes a string by chainable options; uses cache to increase
+     * performance and custom filters for advanced behavior
      * 
+     * @since 2.0.2
+     * @param {String|String[]} input string(s) to normalize
+     * @param {String} [flags=''] normalization flags
+     * @returns {Promise} Promise resolving string normalization
+     */
+    normalizeAsync ( input, flags = '' ) {
+
+        return this.#asyncWrapper(
+            this.normalize,
+            input, flags
+        );
+
+    };
+
+    /**
+     * compares two string a and b using the passed algorithm
      * @async
      * 
      * @param {String} algo name of the algorithm
@@ -98,7 +116,6 @@ module.exports = class CmpStrAsync extends CmpStr {
     /**
      * tests the similarity between the base string and a target string
      * using the current algorithm
-     * 
      * @async
      * 
      * @param {String} str target string
@@ -116,7 +133,6 @@ module.exports = class CmpStrAsync extends CmpStr {
 
     /**
      * tests the similarity of multiple strings against the base string
-     * 
      * @async
      * 
      * @param {String[]} arr array of strings
@@ -135,7 +151,6 @@ module.exports = class CmpStrAsync extends CmpStr {
     /**
      * finds strings in an array that exceed a similarity threshold
      * returns the array sorted by highest similarity
-     * 
      * @async
      * 
      * @param {String[]} arr array of strings
@@ -153,7 +168,6 @@ module.exports = class CmpStrAsync extends CmpStr {
 
     /**
      * finds the closest matching string from an array
-     * 
      * @async
      * 
      * @param {String[]} arr array of strings
@@ -171,7 +185,6 @@ module.exports = class CmpStrAsync extends CmpStr {
 
     /**
      * generate a similarity matrix for an array of strings
-     * 
      * @async
      * 
      * @param {String} algo name of the algorithm

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export { CmpStr, Config, BatchResult } from './CmpStr';
+
+export { CmpStrAsync } from './CmpStrAsync';

package/src/index.js

@@ -22,7 +22,7 @@
  * - generate similarity matrices for cross-comparisons
  * 
  * @author Paul Köhler (komed3)
- * @version 2.0.0
+ * @version 2.0.2
  * @license MIT
  */