cmpstr 1.0.3 → 2.0.0

package/src/CmpStrAsync.js

@@ -0,0 +1,191 @@
+/**
+ * class CmpStrAsync
+ * extends CmpStr
+ * 
+ * The CmpStrAsync class extends the CmpStr class and provides asynchronous
+ * versions of its methods. It uses Promises and setImmediate to ensure
+ * non-blocking execution, making it suitable for use in asynchronous workflows.
+ * 
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * module dependencies
+ * @private
+ */
+
+const CmpStr = require( './CmpStr' );
+
+/**
+ * module exports
+ * @public
+ */
+
+module.exports = class CmpStrAsync extends CmpStr {
+
+    /**
+     * initializes a CmpStrAsync instance
+     * algorithm and base string can be set by initialization
+     * 
+     * @param {String} algo name of the algorithm to use for calculation
+     * @param {String} str string to set as the base
+     */
+    constructor ( algo = undefined, str = undefined ) {
+
+        super ( algo, str );
+
+    };
+
+    /**
+     * @private
+     * generic async wrapper for methods
+     * 
+     * @param {Function} method method to call
+     * @param {...any} args arguments to pass to the method
+     * @returns {Promise} Promise resolving the result of the method
+     */
+    #asyncWrapper ( method, ...args ) {
+
+        return new Promise ( ( resolve, reject ) => {
+
+            setImmediate( () => {
+
+                try {
+
+                    resolve( method.apply( this, args ) );
+
+                } catch ( err ) {
+
+                    reject( err );
+
+                }
+
+            } );
+
+        } );
+
+    };
+
+    /**
+     * --------------------------------------------------
+     * Asynchronous Methods
+     * --------------------------------------------------
+     */
+
+    /**
+     * compares two string a and b using the passed algorithm
+     * 
+     * @async
+     * 
+     * @param {String} algo name of the algorithm
+     * @param {String} a string a
+     * @param {String} b string b
+     * @param {Object} [config={}] config (flags, args)
+     * @returns {Promise} Promise resolving similarity between a and b
+     */
+    compareAsync ( algo, a, b, config = {} ) {
+
+        return this.#asyncWrapper(
+            this.compare,
+            algo, a, b, config
+        );
+
+    };
+
+    /**
+     * tests the similarity between the base string and a target string
+     * using the current algorithm
+     * 
+     * @async
+     * 
+     * @param {String} str target string
+     * @param {Object} [config={}] config (flags, args)
+     * @returns {Promise} Promise resolving similarity to base string
+     */
+    testAsync ( str, config = {} ) {
+
+        return this.#asyncWrapper(
+            this.test,
+            str, config
+        );
+
+    };
+
+    /**
+     * tests the similarity of multiple strings against the base string
+     * 
+     * @async
+     * 
+     * @param {String[]} arr array of strings
+     * @param {Object} [config={}] config (flags, args)
+     * @returns {Promise} Promise resolving an array of objects, each containing target string and similarity score
+     */
+    batchTestAsync ( arr, config = {} ) {
+
+        return this.#asyncWrapper(
+            this.batchTest,
+            arr, config
+        );
+
+    };
+
+    /**
+     * finds strings in an array that exceed a similarity threshold
+     * returns the array sorted by highest similarity
+     * 
+     * @async
+     * 
+     * @param {String[]} arr array of strings
+     * @param {Object} [config={}] config (flags, threshold, args)
+     * @returns {Promise} Promise resolving an array of objects, sorted by highest similarity
+     */
+    async matchAsync ( arr, config = {} ) {
+
+        return this.#asyncWrapper(
+            this.match,
+            arr, config
+        );
+
+    };
+
+    /**
+     * finds the closest matching string from an array
+     * 
+     * @async
+     * 
+     * @param {String[]} arr array of strings
+     * @param {Object} [config={}] config (flags, args)
+     * @returns {Promise} Promise resolving the closest matching string
+     */
+    async closestAsync ( arr, config = {} ) {
+
+        return this.#asyncWrapper(
+            this.closest,
+            arr, config
+        );
+
+    };
+
+    /**
+     * generate a similarity matrix for an array of strings
+     * 
+     * @async
+     * 
+     * @param {String} algo name of the algorithm
+     * @param {String[]} arr array of strings to cross-compare
+     * @param {Object} [config={}] config (flags, args)
+     * @returns {Promise} Promise resolving an 2D array representing the similarity matrix
+     */
+    similarityMatrixAsync ( algo, arr, config = {} ) {
+
+        return this.#asyncWrapper(
+            this.similarityMatrix,
+            algo, arr, config
+        );
+
+    };
+
+};

package/src/algorithms/cosine.js

@@ -0,0 +1,86 @@
+/**
+ * Cosine Similarity
+ * CmpStr module
+ * 
+ * Cosine similarity is a measure how similar two vectors are. It's often used
+ * in text analysis to compare texts based on the words they contain.
+ * 
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * private helper function
+ * get term frequency from string
+ * @private
+ * 
+ * @param {String} str string
+ * @param {String} delimiter term delimiter
+ * @returns {Object} term frequency
+ */
+const _termFreq = ( str, delimiter ) => {
+
+    let freq = {};
+
+    str.split( delimiter ).forEach( ( term ) => {
+
+        freq[ term ] = ( freq[ term ] || 0 ) + 1;
+
+    } );
+
+    return freq;
+
+};
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @param {Object} options having {
+ *   @param {String} [delimiter=' '] term delimiter
+ * }
+ * @returns {Number} similarity score (0..1)
+ */
+
+module.exports = ( a, b, { delimiter = ' ' } = {} ) => {
+
+    /* step 1: count the frequency of chars per string */
+
+    let termsA = _termFreq( a, delimiter ),
+        termsB = _termFreq( b, delimiter );
+
+    let allTerms = new Set ( [
+        ...Object.keys( termsA ),
+        ...Object.keys( termsB )
+    ] );
+
+    /* step 2: calculate the dot product */
+
+    let dotProduct = [ ...allTerms ].reduce(
+        ( sum, char ) => sum + ( termsA[ char ] || 0 ) * ( termsB[ char ] || 0 ),
+        0
+    );
+
+    /* step 3: calculate the vector magnitudes */
+
+    let magnitudeA = Math.sqrt( [ ...allTerms ].reduce(
+        ( sum, char ) => sum + ( termsA[ char ] || 0 ) ** 2,
+        0
+    ) );
+
+    let magnitudeB = Math.sqrt( [ ...allTerms ].reduce(
+        ( sum, char ) => sum + ( termsB[ char ] || 0 ) ** 2,
+        0
+    ) );
+
+    /* step 4: calculate Cosine similarity */
+
+    return magnitudeA && magnitudeB
+        ? dotProduct / ( magnitudeA * magnitudeB )
+        : 0;
+
+};

package/src/algorithms/damerau.js

@@ -0,0 +1,78 @@
+/**
+ * Damerau-Levenshtein Distance
+ * CmpStr module
+ * 
+ * The Damerau-Levenshtein distance differs from the classical Levenshtein
+ * distance by including transpositions among its allowable operations in
+ * addition to the three classical single-character edit operations
+ * (insertions, deletions and substitutions). Useful for correcting typos.
+ * 
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @param {Object} options having {
+ *   @param {Boolean} [raw=false] if true the raw distance is returned
+ * }
+ * @returns {Number} similarity score (0..1) or distance
+ */
+
+module.exports = ( a, b, { raw = false } = {} ) => {
+
+    /* step 1: initialize scoring matrix */
+
+    let matrix = Array.from(
+        { length: a.length + 1 },
+        ( _, i ) => Array.from(
+            { length: b.length + 1 },
+            ( _, j ) => i && j ? 0 : i || j
+        )
+    );
+
+    /* step 2: calculate Damerau-Levenshtein distance */
+
+    for ( let i = 1; i <= a.length; i++ ) {
+
+        for ( let j = 1; j <= b.length; j++ ) {
+
+            let cost = a[ i - 1 ] === b[ j - 1 ] ? 0 : 1;
+
+            matrix[ i ][ j ] = Math.min(
+                matrix[ i - 1 ][ j ] + 1,
+                matrix[ i ][ j - 1 ] + 1,
+                matrix[ i - 1 ][ j - 1 ] + cost
+            );
+
+            if (
+                i > 1 && j > 1 &&
+                a[ i - 1 ] === b[ j - 2 ] &&
+                a[ i - 2 ] === b[ j - 1 ]
+            ) {
+
+                matrix[ i ][ j ] = Math.min(
+                    matrix[ i ][ j ],
+                    matrix[ i - 2 ][ j - 2 ] + cost
+                );
+
+            }
+
+        }
+
+    }
+
+    /* step 3: get Damerau-Levenshtein distance as value between 0..1 */
+
+    return raw ? matrix[ a.length ][ b.length ] : 1 - (
+        matrix[ a.length ][ b.length ] /
+        Math.max( a.length, b.length )
+    );
+
+};

package/src/algorithms/dice.js

@@ -0,0 +1,65 @@
+/**
+ * Dice-Sørensen Coefficient
+ * CmpStr module
+ * 
+ * The Dice-Sørensen index equals twice the number of elements common to
+ * both sets divided by the sum of the number of elements in each set.
+ * Equivalently, the index is the size of the intersection as a fraction
+ * of the average size of the two sets.
+ * 
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * private helper function
+ * get bigrams from string
+ * @private
+ * 
+ * @param {String} str string
+ * @returns {Set} set of bigrams
+ */
+const _str2bigrams = ( str ) => {
+
+    let bigrams = new Set ();
+
+    for ( let i = 0; i < str.length - 1; i++ ) {
+
+        bigrams.add( str.substring( i, i + 2 ) );
+
+    }
+
+    return bigrams;
+
+};
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @returns {Number} similarity score (0..1)
+ */
+
+module.exports = ( a, b ) => {
+
+    /* step 1: generate bigrams from strings */
+
+    let setA = _str2bigrams( a ),
+        setB = _str2bigrams( b );
+
+    /* step 2: calculate coefficient */
+
+    return (
+        ( new Set ( [ ...setA ].filter( ( test ) => {
+            return setB.has( test );
+        } ) ) ).size * 2
+    ) / (
+        setA.size +
+        setB.size
+    );
+
+};

package/src/algorithms/hamming.js

@@ -0,0 +1,44 @@
+/**
+ * Hamming Distance
+ * CmpStr module
+ * 
+ * The Hamming distance between two equal-length strings of symbols is the
+ * number of positions at which the corresponding symbols are different.
+ * 
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @returns {Number} similarity score (0..1)
+ * @throws {Error} if string not of equal length
+ */
+
+module.exports = ( a, b ) => {
+
+    if ( a.length !== b.length ) {
+
+        /* strings must be of equal length for this calculation */
+
+        throw new Error (
+            `Strings must be of equal length for Hamming Distance`
+        );
+
+    }
+
+    return 1 - (
+        [ ...a ].reduce(
+            ( sum, char, i ) => sum + ( char !== b[ i ] ? 1 : 0 ),
+            0
+        ) /
+        a.length
+    );
+
+};

package/src/algorithms/jaccard.js

@@ -0,0 +1,34 @@
+/**
+ * Jaccard Index
+ * CmpStr module
+ * 
+ * The Jaccard Index measures the similarity between two sets by dividing
+ * the size of their intersection by the size of their union.
+ * 
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @returns {Number} similarity score (0..1)
+ */
+
+module.exports = ( a, b ) => {
+
+    let setA = new Set ( a ),
+        setB = new Set ( b );
+
+    return (
+        new Set ( [ ...setA ].filter( x => setB.has( x ) ) )
+    ).size / (
+        new Set ( [ ...setA, ...setB ] )
+    ).size;
+
+};

package/src/algorithms/jaroWinkler.js

@@ -0,0 +1,106 @@
+/**
+ * Jaro-Winkler Distance
+ * CmpStr module
+ * 
+ * Jaro-Winkler is a string similarity metric that gives more weight to
+ * matching characters at the start of the strings.
+ * 
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @param {Object} options having {
+ *   @param {Boolean} [raw=false] if true the raw distance is returned
+ * }
+ * @returns {Number} similarity score (0..1) or distance
+ */
+
+module.exports = ( a, b, { raw = false } = {} ) => {
+
+    /* step 1: check for matches between strings */
+
+    let matchWindow = Math.floor(
+        Math.max( a.length, b.length ) / 2
+    ) - 1;
+
+    let aMatches = Array( a.length ).fill( false ),
+        bMatches = Array( b.length ).fill( false );
+
+    let matches = 0;
+
+    for ( let i = 0; i < a.length; i++ ) {
+
+        for (
+            let j = Math.max( 0, i - matchWindow );
+            j < Math.min( i + matchWindow + 1, b.length );
+            j++
+        ) {
+
+            if ( !bMatches[ j ] && a[ i ] === b[ j ] ) {
+
+                aMatches[ i ] = true;
+                bMatches[ j ] = true;
+
+                matches++;
+
+                break;
+
+            }
+
+        }
+
+    }
+
+    if ( matches === 0 ) {
+
+        /* if no matches found, return 0 */
+
+        return 0;
+
+    }
+
+    /* step 2: calculate transpositions */
+
+    let transpos = 0,
+        k = 0;
+
+    for ( let i = 0; i < a.length; i++ ) {
+
+        if ( aMatches[ i ] ) {
+
+            while ( !bMatches[ k ] ) k++;
+
+            if ( a[ i ] !== b[ k ] ) transpos++;
+
+            k++;
+
+        }
+
+    }
+
+    /* step 3: calculate Jaro-Winkler distance */
+
+    let jaro = (
+        ( matches / a.length ) +
+        ( matches / b.length ) +
+        ( matches - ( transpos / 2 ) ) /
+        matches
+    ) / 3;
+
+    /* step 4: get Jaro-Winkler as value between 0..1 */
+
+    return raw ? jaro : jaro + Math.min(
+        4, [ ...a ].findIndex(
+            ( char, i ) => char !== b[ i ]
+        ) || 0
+    ) * 0.1 * ( 1 - jaro );
+
+};

package/src/algorithms/lcs.js

@@ -0,0 +1,58 @@
+/**
+ * Longest Common Subsequence (LCS)
+ * CmpStr module
+ * 
+ * LCS measures the length of the longest subsequence common to both strings.
+ * 
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @returns {Number} similarity score (0..1)
+ */
+
+module.exports = ( a, b ) => {
+
+    /* step 1: initialize scoring matrix */
+
+    let matrix = Array( a.length + 1 ).fill( null ).map(
+        () => Array( b.length + 1 ).fill( 0 )
+    );
+
+    for ( let i = 1; i <= a.length; i++ ) {
+
+        for ( let j = 1; j <= b.length; j++ ) {
+
+            if ( a[ i - 1 ] === b[ j - 1 ] ) {
+
+                matrix[ i ][ j ] = matrix[ i - 1 ][ j - 1 ] + 1;
+
+            } else {
+
+                matrix[ i ][ j ] = Math.max(
+                    matrix[ i - 1 ][ j ],
+                    matrix[ i ][ j - 1 ]
+                );
+
+            }
+
+        }
+
+    }
+
+    /* step 2: calculate LCS */
+
+    return (
+        matrix[ a.length ][ b.length ] /
+        Math.max( a.length, b.length )
+    );
+
+};