cmpstr 1.0.3 → 2.0.0

package/src/algorithms/levenshtein.js

@@ -0,0 +1,70 @@
+/**
+ * Levenshtein Distance
+ * CmpStr module
+ * 
+ * The Levenshtein distance between two strings is the minimum number of
+ * single-character edits (i.e. insertions, deletions or substitutions)
+ * required to change one word into the other.
+ * 
+ * @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 ) => j
+        ).fill( i, 0, 1 )
+    );
+
+    /* step 2: calculate Levenshtein distance */
+
+    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 ];
+
+            } else {
+
+                matrix[ i ][ j ] = 1 + Math.min(
+                    matrix[ i ][ j - 1 ],
+                    matrix[ i - 1 ][ j - 1 ], 
+                    matrix[ i - 1 ][ j ]
+                );
+
+            }
+
+        }
+
+    }
+
+    /* step 3: get 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/needlemanWunsch.js

@@ -0,0 +1,72 @@
+/**
+ * Needleman-Wunsch Algorithm
+ * CmpStr module
+ * 
+ * The Needleman-Wunsch algorithm performs global alignment,
+ * aligning two strings entirely, including gaps. It is commonly
+ * used in bioinformatics.
+ * 
+ * @author Paul Köhler
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @param {Object} options having {
+ *   @param {Number} [match=1] score for a match
+ *   @param {Number} [mismatch=-1] penalty for a mismatch
+ *   @param {Number} [gap=-1] penalty for a gap
+ * }
+ * @returns {Number} similarity score (0..1)
+ */
+
+module.exports = ( a, b, {
+    match = 1, mismatch = -1, gap = -1
+} = {} ) => {
+
+    let rows = a.length + 1,
+        cols = b.length + 1;
+
+    /* step 1: initialize scoring matrix */
+
+    let matrix = Array.from(
+        { length: rows },
+        ( _, i ) => Array.from(
+            { length: cols },
+            ( _, j ) => ( i === 0 ? j * gap : j === 0 ? i * gap : 0 )
+        )
+    );
+
+    /* step 2: fill the scoring matrix */
+
+    for ( let i = 1; i < rows; i++ ) {
+
+        for ( let j = 1; j < cols; j++ ) {
+
+            let matchScore = a[ i - 1 ] === b[ j - 1 ] ? match : mismatch;
+
+            matrix[ i ][ j ] = Math.max(
+                matrix[ i - 1 ][ j - 1 ] + matchScore,
+                matrix[ i - 1 ][ j ] + gap,
+                matrix[ i ][ j - 1 ] + gap
+            );
+
+        }
+
+    }
+
+    /* step 3: normalize the score to a value between 0..1 */
+
+    return Math.max( 0, Math.min( 1,
+        matrix[ a.length ][ b.length ] / (
+            Math.max( a.length, b.length ) * match
+        )
+    ) );
+
+};

package/src/algorithms/qGram.js

@@ -0,0 +1,63 @@
+/**
+ * q-Gram Similarity
+ * CmpStr module
+ * 
+ * Q-gram similarity is a string-matching algorithm that compares two
+ * strings by breaking them into substrings of length Q. It's used to
+ * determine how similar the two strings are.
+ * 
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * private helper function
+ * convert string to array of substrings
+ * @private
+ * 
+ * @param {String} str string
+ * @param {Int} q length of substrings
+ * @returns {String[]} array of substrings
+ */
+
+const _qGrams = ( str, q ) => {
+
+    let grams = [];
+
+    for ( let i = 0; i <= str.length - q; i++ ) {
+
+        grams.push( str.slice( i, i + q ) );
+
+    }
+
+    return grams;
+
+};
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @param {Object} options having {
+ *   @param {Int} [q=2] length of substrings
+ * }
+ * @returns {Number} similarity score (0..1)
+ */
+module.exports = ( a, b, { q = 2 } = {} ) => {
+
+    let setA = new Set ( _qGrams( a, q ) ),
+        setB = new Set ( _qGrams( b, q ) );
+
+    return (
+        new Set( [ ...setA ].filter(
+            test => setB.has( test )
+        ) )
+    ).size / Math.max(
+        setA.size, setB.size
+    );
+
+};

package/src/algorithms/smithWaterman.js

@@ -0,0 +1,78 @@
+/**
+ * Smith-Waterman Algorithm
+ * CmpStr module
+ * 
+ * The Smith-Waterman algorithm performs local alignment, finding the
+ * best matching subsequence between two strings. It is commonly used
+ * in bioinformatics.
+ * 
+ * @author Paul Köhler
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @param {Object} options having {
+ *   @param {Number} [match=2] score for a match
+ *   @param {Number} [mismatch=-1] penalty for a mismatch
+ *   @param {Number} [gap=-1] penalty for a gap
+ * }
+ * @returns {Number} similarity score (0..1)
+ */
+
+module.exports = ( a, b, {
+    match = 2, mismatch = -1, gap = -1
+} = {} ) => {
+
+    let rows = a.length + 1,
+        cols = b.length + 1;
+
+    /* step 1: initialize scoring matrix */
+
+    let matrix = Array.from(
+        { length: rows },
+        () => Array( cols ).fill( 0 )
+    );
+
+    /* step 2: fill the scoring matrix */
+
+    let maxScore = 0;
+
+    for ( let i = 1; i < rows; i++ ) {
+
+        for ( let j = 1; j < cols; j++ ) {
+
+            let matchScore = a[ i - 1 ] === b[ j - 1 ] ? match : mismatch;
+
+            matrix[ i ][ j ] = Math.max(
+                0,
+                matrix[ i - 1 ][ j - 1 ] + matchScore,
+                matrix[ i - 1 ][ j ] + gap,
+                matrix[ i ][ j - 1 ] + gap
+            );
+
+            maxScore = Math.max(
+                maxScore,
+                matrix[ i ][ j ]
+            );
+
+        }
+
+    }
+
+    /* step 3: normalize the score to a value between 0..1 */
+
+    return Math.max( 0, Math.min( 1,
+        maxScore / Math.min(
+            a.length * match,
+            b.length * match
+        )
+    ) );
+
+};

package/src/algorithms/soundex.js

@@ -0,0 +1,152 @@
+/**
+ * Soundex Algorithm
+ * CmpStr module
+ * 
+ * The Soundex algorithm generates a phonetic representation of a string
+ * based on how it sounds. It supports predefined setups for English and
+ * German and allows users to provide custom options.
+ * 
+ * @author Paul Köhler
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * predefined phonetic mappings / excluded chars for supported languages
+ * @private
+ */
+const soundexConfig = {
+    en: {
+        exclude: 'AEIOUHWY',
+        mapping: {
+            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'
+        }
+    },
+    de: {
+        exclude: 'AEIOUÄÖÜHWY',
+        mapping: {
+            B: '1', P: '1', F: '1', V: '1',
+            C: '2', G: '2', K: '2', Q: '2', S: '2', X: '2', Z: '2', J: '2',
+            D: '3', T: '3',
+            L: '4',
+            M: '5', N: '5',
+            R: '6'
+        }
+    }
+};
+
+/**
+ * private helper function
+ * generate soundex code from string
+ * @private
+ * 
+ * @param {String} str string to create soundex code for
+ * @param {Object} mapping soundex mapping
+ * @param {String} exclude characters to exclude from the input
+ * @param {Number} maxLength maximum length of the phonetic code
+ * @returns {String} soundex code
+ */
+const _generateSoundex = ( str, mapping, exclude, maxLength ) => {
+
+    let normalized = str.toUpperCase().replace(
+        new RegExp( `[${exclude}]`, 'g' ), ''
+    );
+
+    let soundexCode = normalized[ 0 ],
+        prevCode = mapping[ soundexCode ] || '';
+
+    for ( let i = 1; i < normalized.length; i++ ) {
+
+        let code = mapping[ normalized[ i ] ] || '';
+
+        if ( code !== prevCode && code !== '' ) {
+
+            soundexCode += code;
+
+        }
+
+        prevCode = code;
+
+    }
+
+    /* pad or truncate the code to the desired length */
+
+    return soundexCode
+        .padEnd( maxLength, '0' )
+        .slice( 0, maxLength );
+
+};
+
+/**
+ * module exports
+ * @public
+ * 
+ * @param {String} a string a
+ * @param {String} b string b
+ * @param {Object} options having {
+ *   @param {String} [lang='en'] language code for predefined setups (e.g., 'en', 'de')
+ *   @param {Boolean} [raw=false] if true, returns the raw sound index codes
+ *   @param {Object} [mapping] custom phonetic mapping (overrides predefined)
+ *   @param {String} [exclude=''] characters to exclude from the input (overrides predefined)
+ *   @param {Number} [maxLength=4] maximum length of the phonetic code
+ * }
+ * @returns {Number|Object} similarity score (0..1) or raw soundex codes
+ */
+
+module.exports = ( a, b, {
+    lang = 'en',
+    raw = false,
+    mapping = null,
+    exclude = null,
+    maxLength = 4
+} = {} ) => {
+
+    /* step 1: load mapping and excluded chars or use custom data */
+
+    let pMapping = mapping || soundexConfig[ lang ].mapping || soundexConfig.en.mapping,
+        pExclude = exclude || soundexConfig[ lang ].exclude || soundexConfig.en.exclude;
+
+    /* step 2: generate soundex codes for both strings */
+
+    let soundexA = _generateSoundex( a, pMapping, pExclude, maxLength ),
+        soundexB = _generateSoundex( b, pMapping, pExclude, maxLength );
+
+    if ( raw ) {
+
+        /* return raw soundex codes */
+
+        return {
+            a: soundexA,
+            b: soundexB
+        };
+
+    }
+
+    /* step 3: calculate similarity between soundex codes */
+
+    let maxLen = Math.max(
+        soundexA.length,
+        soundexB.length
+    );
+
+    let matches = 0;
+
+    for ( let i = 0; i < maxLen; i++ ) {
+
+        if ( soundexA[ i ] === soundexB[ i ] ) {
+
+            matches++;
+
+        }
+
+    }
+
+    return matches / maxLen;
+
+};

package/src/index.js

@@ -0,0 +1,47 @@
+/**
+ * npm package
+ * cmpstr
+ * 
+ * The cmpstr package is a powerful and lightweight library for calculating string similarity,
+ * finding the closest matches in arrays, performing phonetic searches, and more. It supports
+ * a variety of built-in algorithms, including Levenshtein distance, Dice-Sørensen coefficient,
+ * Damerau-Levenshtein, Soundex, and many others. Users can also add custom algorithms and
+ * normalization filters to extend its functionality.
+ * 
+ * key features:
+ * - built-in support for multiple similarity algorithms
+ * - phonetic search with language-specific configurations
+ * - batch operations and similarity matrices for large datasets
+ * - customizable normalization with global flags and caching
+ * - asynchronous support for non-blocking workflows
+ * 
+ * usage:
+ * - compare strings for similarity using various algorithms
+ * - find the closest match from an array of strings
+ * - perform phonetic searches with raw or similarity-based results
+ * - generate similarity matrices for cross-comparisons
+ * 
+ * @author Paul Köhler (komed3)
+ * @version 2.0.0
+ * @license MIT
+ */
+
+'use strict';
+
+/**
+ * module dependencies
+ * @private
+ */
+
+const CmpStr = require( './CmpStr' );
+const CmpStrAsync = require( './CmpStrAsync' );
+
+/**
+ * module exports
+ * @public
+ */
+
+module.exports = {
+    CmpStr,
+    CmpStrAsync
+};