cmpstr 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Paul Köhler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# cmpstr
+
+This lightweight npm package can be used to __calculate the similarity of strings__. It supports both the best known __Levenshtein distance__ and the slightly more accurate __Sørensen dice coefficient__.
+
+## Install
+
+Using Node.js install the package using shell command:
+
+```sh
+npm install cmpstr
+```
+
+## Usage
+
+Load the package into your project:
+
+```js
+const cmpstr = require( 'cmpstr' );
+```
+
+Sample of how to use the package in your code:
+
+```js
+let str1 = 'kitten';
+let str2 = 'sitting';
+
+let distance = cmpstr.levenshteinDistance( str1, str2 );
+// expected 3
+
+let dice = cmpstr.diceCoefficient( str1, str2 );
+// expected 0.3636363636363636
+
+let closest = cmpstr.diceClosest( 'best', [
+  'better', 'bestest', 'well', 'good'
+] );
+// expected bestest
+```
+
+## API
+
+The npm package ``cmpstr`` supports two different methods for determining the similarity of two strings. The __Levenshtein distance__, as the minimum number of inserting, deleting and replacing operations to convert one string into another, and the __Sørensen-Dice coefficient__ to measure the similarity of two samples.
+
+Learn more about both by visiting these links:
+
+* [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance)
+* [Sørensen-Dice coefficient](https://en.wikipedia.org/wiki/Sørensen–Dice_coefficient)
+
+### Levenshtein distance
+
+#### ``levenshteinDistance( a, b )``
+
+Calculates the difference between two strings ``a`` and ``b`` and returns the Levenshtein distance as an integer value.
+
+#### ``levenshtein( a, b )``
+
+Returns the match percentage of two strings ``a`` and ``b``. The output value is in the range ``0..1`` as a floating point number.
+
+#### ``levenshteinClosest( str, arr )``
+
+Returns the best match of the string ``str`` against the array ``arr`` of passed strings. The function returns the most closely matched string found in the array.
+
+### Sørensen-Dice coefficient
+
+#### ``diceCoefficient( a, b )``
+
+This function evaluates the similarity of two given strings ``a`` and ``b`` as percentage value according to the Sørensen-Dice coefficient and returns the result as floating point number.
+
+#### ``diceClosest( str, arr )``
+
+As another way to find the best match between the string ``str`` and a given array ``arr`` of samples, this function uses the Sørensen-Dice coefficient. It returns the most matching string as well.

package/index.js

@@ -0,0 +1,313 @@
+/**
+ * cmpstr
+ * lightweight npm package to calculate string similarity
+ * 
+ * @author komed3 (Paul Köhler)
+ * @version 1.0.0
+ * @license MIT
+ */
+
+'use strict'
+
+/**
+ * basic functions
+ * @private
+ */
+
+/**
+ * normalize string
+ * @param {String} str string
+ * @returns normalized string
+ */
+const normalize = ( str ) => {
+
+    return str.toString();
+
+};
+
+/**
+ * get bigrams from string
+ * @param {String} str string
+ * @returns bigrams
+ */
+const bbigrams = ( str ) => {
+
+    let bigrams = new Set();
+
+    for( let i = 0; i < str.length - 1; i++ ) {
+
+        bigrams.add(
+            str.substring( i, i + 2 )
+        );
+
+    }
+
+    return bigrams;
+
+};
+
+/**
+ * search for closest string
+ * @param {String} algo algorithm to use
+ * @param {String} test test string
+ * @param  {Array} arr targets to test
+ * @returns closest target
+ */
+const findClosest = ( algo, test, arr ) => {
+
+    let best = -Infinity,
+        idx = 0,
+        pct;
+
+    /* search for closest element in arr */
+
+    arr.forEach( ( str, i ) => {
+
+        switch( algo ) {
+
+            case 'levenshtein':
+                pct = levenshtein( test, str );
+                break;
+
+            case 'diceCoefficient':
+                pct = diceCoefficient( test, str );
+                break;
+
+            default:
+                pct = 0;
+                break;
+
+        }
+
+        if( pct > best ) {
+
+            /* save closest target */
+
+            best = pct;
+            idx = i;
+
+        }
+
+    } );
+
+    /* return closest target */
+
+    return arr[ idx ];
+
+};
+
+/**
+ * similarity calculations
+ * @public
+ */
+
+/**
+ * calculate levenshtein similarity (in percent)
+ * @param {String} a string 1
+ * @param {String} b string 2
+ * @returns similarity 0..1
+ */
+const levenshtein = ( a, b ) => {
+
+    /* normalize string */
+
+    a = normalize( a );
+    b = normalize( b );
+
+    if( a == b ) {
+
+        /* both string are similar or empty */
+
+        return 1;
+
+    } else if( a.length < 2 || b.length < 2 ) {
+
+        /* for 0-letter or 1-letter strings */
+
+        return 0;
+
+    } else {
+
+        /* get levenshtein distance */
+
+        let distance = levenshteinDistance( a, b );
+
+        /* return percentage */
+
+        return 1 - (
+            distance / Math.max(
+                a.length,
+                b.length
+            )
+        );
+
+    }
+
+};
+
+/**
+ * get levenshtein distance
+ * @param {String} a string 1
+ * @param {String} b string 2
+ * @returns distance
+ */
+const levenshteinDistance = ( a, b ) => {
+
+    /* normalize string */
+
+    a = normalize( a );
+    b = normalize( b );
+
+    if( a == b ) {
+
+        /* both string are similar or empty */
+
+        return 0;
+
+    } else if( a.length == 0 ) {
+
+        /* empty string 1 */
+
+        return b.length;
+
+    } else if( b.length == 0 ) {
+
+        /* empty string 2 */
+
+        return a.length;
+
+    } else {
+
+        /* create matrix */
+
+        const matrix = [];
+
+        for( let i = 0; i <= a.length; i++ ) {
+
+            const row = [];
+
+            for( let j = 0; j <= b.length; j++ ) {
+
+                row.push( j );
+
+            }
+
+            row[0] = i;
+
+            matrix.push( row );
+
+        }
+
+        /* calculate 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 ]
+                    );
+
+                }
+
+            }
+
+        }
+
+        /* return levenshtein distance */
+
+        return matrix[ a.length ][ b.length ];
+
+    }
+
+};
+
+/**
+ * search for closest target to test string
+ * @param {String} test test string
+ * @param  {Array} arr targets to test
+ * @returns closest target
+ */
+const levenshteinClosest = ( test, arr ) => {
+
+    return findClosest( 'levenshtein', test, arr );
+
+};
+
+/**
+ * calculate dice coefficient
+ * @param {String} a string 1
+ * @param {String} b string 2
+ * @returns dice coefficient
+ */
+const diceCoefficient = ( a, b ) => {
+
+    /* normalize string */
+
+    a = normalize( a );
+    b = normalize( b );
+
+    if( a == b ) {
+
+        /* both string are similar or empty */
+
+        return 1;
+
+    } else if( a.length < 2 || b.length < 2 ) {
+
+        /* for 0-letter or 1-letter strings */
+
+        return 0;
+
+    } else {
+
+        /* get bigrams */
+
+        let setA = bbigrams( a ),
+            setB = bbigrams( b );
+
+        /* calculate dice coefficient */
+
+        return (
+            ( new Set( [ ...setA ].filter( ( x ) => {
+                return setB.has( x );
+            } ) ) ).size * 2
+        ) / (
+            setA.size +
+            setB.size
+        );
+
+    }
+
+}
+
+/**
+ * search for closest target to test string
+ * @param {String} test test string
+ * @param  {Array} arr targets to test
+ * @returns closest target
+ */
+const diceClosest = ( test, arr ) => {
+
+    return findClosest( 'diceCoefficient', test, arr );
+
+};
+
+/**
+ * export module functions
+ */
+module.exports = {
+    levenshtein,
+    levenshteinDistance,
+    levenshteinClosest,
+    diceCoefficient,
+    diceClosest
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "cmpstr",
+  "description": "lightweight npm package to calculate string similarity",
+  "author": {
+    "name" : "komed3 (Paul Köhler)",
+    "email" : "webmaster@komed3.de",
+    "url" : "https://komed3.de"
+  },
+  "homepage": "https://github.com/komed3/cmpstr#readme",
+  "version": "1.0.0",
+  "license": "MIT",
+  "keywords": [
+    "string",
+    "similarity",
+    "levenshtein-distance",
+    "dice-coefficient"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/komed3/cmpstr.git"
+  },
+  "bugs": {
+    "url": "https://github.com/komed3/cmpstr/issues"
+  }
+}