cmpstr 2.0.3 → 3.0.0

package/src/CmpStrAsync.d.ts

@@ -1,19 +0,0 @@
-import { CmpStr, Config, BatchResult } from './CmpStr';
-
-export declare class CmpStrAsync extends CmpStr {
-
-    normalizeAsync ( input: string|string[], flags?: string ) : Promise<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

@@ -1,197 +0,0 @@
-/**
- * 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 );
-
-    };
-
-    /**
-     * generic async wrapper for methods
-     * 
-     * @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
-     */
-    #asyncWrapper ( method, ...args ) {
-
-        return new Promise ( ( resolve, reject ) => {
-
-            setImmediate( () => {
-
-                try {
-
-                    resolve( method.apply( this, args ) );
-
-                } catch ( err ) {
-
-                    reject( err );
-
-                }
-
-            } );
-
-        } );
-
-    };
-
-    /**
-     * --------------------------------------------------
-     * Asynchronous Methods
-     * --------------------------------------------------
-     */
-
-    /**
-     * 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
-     * 
-     * @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
-     * 
-     * @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
-     * 
-     * @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
-     * 
-     * @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
-     */
-    matchAsync ( arr, config = {} ) {
-
-        return this.#asyncWrapper(
-            this.match,
-            arr, config
-        );
-
-    };
-
-    /**
-     * finds the closest matching string from an array
-     * 
-     * @param {String[]} arr array of strings
-     * @param {Object} [config={}] config (flags, args)
-     * @returns {Promise} Promise resolving the closest matching string
-     */
-    closestAsync ( arr, config = {} ) {
-
-        return this.#asyncWrapper(
-            this.closest,
-            arr, config
-        );
-
-    };
-
-    /**
-     * generate a similarity matrix for an array of strings
-     * 
-     * @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

@@ -1,86 +0,0 @@
-/**
- * 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

@@ -1,78 +0,0 @@
-/**
- * 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

@@ -1,65 +0,0 @@
-/**
- * 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

@@ -1,44 +0,0 @@
-/**
- * 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

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,106 +0,0 @@
-/**
- * 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

@@ -1,58 +0,0 @@
-/**
- * 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 )
-    );
-
-};