cmpstr 1.0.0 → 1.0.2

package/README.md

@@ -24,16 +24,38 @@ Sample of how to use the package in your code:
 let str1 = 'kitten';
 let str2 = 'sitting';
 
+/**
+ * levenshteinDistance
+ * expected: 3
+ */
 let distance = cmpstr.levenshteinDistance( str1, str2 );
-// expected 3
 
+/**
+ * diceCoefficient
+ * expected: 0.3636363636363636
+ */
 let dice = cmpstr.diceCoefficient( str1, str2 );
-// expected 0.3636363636363636
 
+/**
+ * diceClosest
+ * expected: bestest
+ */
 let closest = cmpstr.diceClosest( 'best', [
   'better', 'bestest', 'well', 'good'
 ] );
-// expected bestest
+
+/**
+ * levenshteinMatch
+ * expected: [
+ *   { target: 'bestest', match: 0.5714285714285714 },
+ *   { target: 'better', match: 0.5 },
+ *   { target: 'well', match: 0.25 },
+ *   { target: 'good', match: 0 }
+ * ]
+ */
+let matches = cmpstr.levenshteinMatch( 'best', [
+  'better', 'bestest', 'well', 'good'
+] );
 ```
 
 ## API
@@ -47,24 +69,56 @@ Learn more about both by visiting these links:
 
 ### Levenshtein distance
 
-#### ``levenshteinDistance( a, b )``
+#### ``levenshteinDistance( a, b [, flags = null ] )``
 
 Calculates the difference between two strings ``a`` and ``b`` and returns the Levenshtein distance as an integer value.
 
-#### ``levenshtein( a, b )``
+#### ``levenshtein( a, b [, flags = null ] )``
 
 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 )``
+#### ``levenshteinClosest( str, arr [, flags = null ] )``
 
 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.
 
+#### ``levenshteinMatch( str, arr [, flags = null ] )``
+
+Calculates the similarity of all strings contained in the array ``arr`` according to Levenshtein compared to ``str`` and returns an array of all samples sorted by matching in descending order.
+
 ### Sørensen-Dice coefficient
 
-#### ``diceCoefficient( a, b )``
+#### ``diceCoefficient( a, b [, flags = null ] )``
 
 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 )``
+#### ``diceClosest( str, arr [, flags = null ] )``
 
 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.
+
+#### ``diceMatch( str, arr [, flags = null ] )``
+
+Calculates the similarity of all strings contained in the array ``arr`` according to Sørensen-Dice coefficient compared to ``str`` and returns an array of all samples sorted by matching in descending order.
+
+### Flags
+
+Each method can be passed the ``flags`` options listed below:
+
+| Flag  | Option                         |
+| ----- | ------------------------------ |
+| ``i`` | case insensitive               |
+| ``s`` | non-whitespace characters only |
+
+## Patch notes
+
+### 1.0.2
+
+* Add normalize options ``i`` and ``s``
+* Minor fixes
+
+### 1.0.1
+
+* Minor fixes
+
+### 1.0.0
+
+* Initial release

package/index.js

@@ -3,7 +3,7 @@
  * lightweight npm package to calculate string similarity
  * 
  * @author komed3 (Paul Köhler)
- * @version 1.0.0
+ * @version 1.0.2
  * @license MIT
  */
 
@@ -17,11 +17,40 @@
 /**
  * normalize string
  * @param {String} str string
+ * @param {Null|String} flags options
  * @returns normalized string
  */
-const normalize = ( str ) => {
+const normalize = ( str, flags = null ) => {
 
-    return str.toString();
+    str = str.toString();
+
+    ( flags || '' ).toString().split( '' ).forEach( ( f ) => {
+
+        /**
+         * normalize options
+         * i    case insensitive
+         * s    non-whitespace
+         */
+
+        switch( f.toLowerCase() ) {
+
+            case 'i':
+                str = str.toLowerCase();
+                break;
+
+            case 's':
+                str = str.replace( /[^\S]+/g, '' );
+                break;
+
+            default:
+                /* do nothing */
+                break;
+
+        }
+
+    } );
+
+    return str;
 
 };
 
@@ -30,7 +59,7 @@ const normalize = ( str ) => {
  * @param {String} str string
  * @returns bigrams
  */
-const bbigrams = ( str ) => {
+const str2bigrams = ( str ) => {
 
     let bigrams = new Set();
 
@@ -46,14 +75,40 @@ const bbigrams = ( str ) => {
 
 };
 
+/**
+ * compare strings by given algorithm
+ * @param {String} algo algorithm to use
+ * @param {String} a string 1
+ * @param {String} b string 2
+ * @param {Null|String} flags options
+ * @returns similarity
+ */
+const cpmByAlgo = ( algo, a, b, flags ) => {
+
+    switch( algo ) {
+
+        case 'levenshtein':
+            return levenshtein( a, b, flags );
+
+        case 'diceCoefficient':
+            return diceCoefficient( a, b, flags );
+
+        default:
+            return 0;
+
+    }
+
+};
+
 /**
  * search for closest string
  * @param {String} algo algorithm to use
  * @param {String} test test string
- * @param  {Array} arr targets to test
+ * @param {Array} arr targets to test
+ * @param {Null|String} flags options
  * @returns closest target
  */
-const findClosest = ( algo, test, arr ) => {
+const findClosest = ( algo, test, arr, flags ) => {
 
     let best = -Infinity,
         idx = 0,
@@ -61,23 +116,9 @@ const findClosest = ( algo, test, arr ) => {
 
     /* 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;
+    [ ...arr ].forEach( ( str, i ) => {
 
-        }
+        pct = cpmByAlgo( algo, test, str, flags );
 
         if( pct > best ) {
 
@@ -96,6 +137,44 @@ const findClosest = ( algo, test, arr ) => {
 
 };
 
+/**
+ * sort best matches to test string
+ * @param {String} algo algorithm to use
+ * @param {String} test test string
+ * @param {Array} arr targets to test
+ * @param {Null|String} flags options
+ * @returns sorted matches
+ */
+const bestMatch = ( algo, test, arr, flags = null ) => {
+
+    let matches = [],
+        pct;
+
+    /* calculate similarity for each arr items */
+
+    [ ...arr ].forEach( ( str ) => {
+
+        pct = cpmByAlgo( algo, test, str, flags );
+
+        matches.push( {
+            target: str,
+            match: pct
+        } );
+
+    } );
+
+    /* sort by highest similarity */
+
+    let sorted = matches.sort( ( a, b ) => {
+        return b.match - a.match;
+    } );
+
+    /* return sorted matches */
+
+    return sorted;
+
+};
+
 /**
  * similarity calculations
  * @public
@@ -105,14 +184,15 @@ const findClosest = ( algo, test, arr ) => {
  * calculate levenshtein similarity (in percent)
  * @param {String} a string 1
  * @param {String} b string 2
+ * @param {Null|String} flags options
  * @returns similarity 0..1
  */
-const levenshtein = ( a, b ) => {
+const levenshtein = ( a, b, flags = null ) => {
 
     /* normalize string */
 
-    a = normalize( a );
-    b = normalize( b );
+    a = normalize( a, flags );
+    b = normalize( b, flags );
 
     if( a == b ) {
 
@@ -149,14 +229,15 @@ const levenshtein = ( a, b ) => {
  * get levenshtein distance
  * @param {String} a string 1
  * @param {String} b string 2
+ * @param {Null|String} flags options
  * @returns distance
  */
-const levenshteinDistance = ( a, b ) => {
+const levenshteinDistance = ( a, b, flags = null ) => {
 
     /* normalize string */
 
-    a = normalize( a );
-    b = normalize( b );
+    a = normalize( a, flags );
+    b = normalize( b, flags );
 
     if( a == b ) {
 
@@ -233,12 +314,26 @@ const levenshteinDistance = ( a, b ) => {
 /**
  * search for closest target to test string
  * @param {String} test test string
- * @param  {Array} arr targets to test
+ * @param {Array} arr targets to test
+ * @param {Null|String} flags options
  * @returns closest target
  */
-const levenshteinClosest = ( test, arr ) => {
+const levenshteinClosest = ( test, arr, flags = null ) => {
+
+    return findClosest( 'levenshtein', test, arr, flags );
+
+};
+
+/**
+ * sort best matches to test string
+ * @param {String} test test string
+ * @param {Array} arr targets to test
+ * @param {Null|String} flags options
+ * @returns sorted matches
+ */
+const levenshteinMatch = ( test, arr, flags = null ) => {
 
-    return findClosest( 'levenshtein', test, arr );
+    return bestMatch( 'levenshtein', test, arr, flags );
 
 };
 
@@ -246,14 +341,15 @@ const levenshteinClosest = ( test, arr ) => {
  * calculate dice coefficient
  * @param {String} a string 1
  * @param {String} b string 2
+ * @param {Null|String} flags options
  * @returns dice coefficient
  */
-const diceCoefficient = ( a, b ) => {
+const diceCoefficient = ( a, b, flags = null ) => {
 
     /* normalize string */
 
-    a = normalize( a );
-    b = normalize( b );
+    a = normalize( a, flags );
+    b = normalize( b, flags );
 
     if( a == b ) {
 
@@ -271,8 +367,8 @@ const diceCoefficient = ( a, b ) => {
 
         /* get bigrams */
 
-        let setA = bbigrams( a ),
-            setB = bbigrams( b );
+        let setA = str2bigrams( a ),
+            setB = str2bigrams( b );
 
         /* calculate dice coefficient */
 
@@ -292,12 +388,26 @@ const diceCoefficient = ( a, b ) => {
 /**
  * search for closest target to test string
  * @param {String} test test string
- * @param  {Array} arr targets to test
+ * @param {Array} arr targets to test
+ * @param {Null|String} flags options
  * @returns closest target
  */
-const diceClosest = ( test, arr ) => {
+const diceClosest = ( test, arr, flags = null ) => {
+
+    return findClosest( 'diceCoefficient', test, arr, flags );
+
+};
+
+/**
+ * sort best matches to test string
+ * @param {String} test test string
+ * @param {Array} arr targets to test
+ * @param {Null|String} flags options
+ * @returns sorted matches
+ */
+const diceMatch = ( test, arr, flags = null ) => {
 
-    return findClosest( 'diceCoefficient', test, arr );
+    return bestMatch( 'diceCoefficient', test, arr, flags );
 
 };
 
@@ -308,6 +418,8 @@ module.exports = {
     levenshtein,
     levenshteinDistance,
     levenshteinClosest,
+    levenshteinMatch,
     diceCoefficient,
-    diceClosest
+    diceClosest,
+    diceMatch
 };

package/package.json

@@ -7,7 +7,7 @@
     "url" : "https://komed3.de"
   },
   "homepage": "https://github.com/komed3/cmpstr#readme",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "license": "MIT",
   "keywords": [
     "string",