Merge pull request #26 from soukand/abort_controller

AbortController support

Author: nol13

README.md

@@ -2,11 +2,11 @@
 
 ![fuzzball.js logo](fuzzballlogo.jpg "feed me strings!")
 ==========
-Easy to use and powerful fuzzy string matching. 
+Easy to use and powerful fuzzy string matching.
 
 Mostly a JavaScript port of the [TheFuzz](https://github.com/seatgeek/thefuzz) (formerly fuzzywuzzy) Python library, with some additional features like token similarity sorting and wildcard support.
 
-Demo <a href="https://nol13.github.io/fuzzball.js" target="_blank">here</a> comparing some of the different scorers/options. Auto-generated API Docs <a href="https://github.com/nol13/fuzzball.js/blob/master/jsdocs/fuzzball.md" target="_blank">here</a>. 
+Demo <a href="https://nol13.github.io/fuzzball.js" target="_blank">here</a> comparing some of the different scorers/options. Auto-generated API Docs <a href="https://github.com/nol13/fuzzball.js/blob/master/jsdocs/fuzzball.md" target="_blank">here</a>.
 
 # Contents
  * [Installation](#installation)
@@ -73,7 +73,7 @@ fuzz.extract("mr. harry hood", choices, options);
   [ 'Mr. Henry Hood', 85, 2 ],
   [ 'Mr. Minor', 40, 1 ] ]
 
-/** 
+/**
 * Set options.returnObjects = true to get back
 * an array of {choice, score, key} objects instead of tuples
 */
@@ -89,9 +89,21 @@ options.cancelToken = cancelToken;
 fuzz.extractAsPromised("gonna get canceled", choices, options)
         .then(res => {/* do stuff */})
         .catch((e) => {
-                if (e.message === 'canceled') console.log('I got canceled!') 
+                if (e.message === 'canceled') console.log('I got canceled!')
         });
 cancelToken.canceled = true;
+
+// or use AbortController to cancel search
+const abortController = new AbortController();
+
+options.abortController = abortController;
+fuzz.extractAsPromised("gonna get canceled", choices, options)
+        .then(res => {/* do stuff */})
+        .catch((e) => {
+                if (e.message === 'aborted') console.log('Search was aborted!')
+        });
+
+abortController.abort();
 ```
 
 **Simple Ratio**
@@ -102,7 +114,7 @@ fuzz.ratio("this is a test", "This is a test!");
         100
 ```
 
-**Partial Ratio** 
+**Partial Ratio**
 
 Highest scoring substring of the longer string vs. the shorter string.
 
@@ -122,18 +134,18 @@ fuzz.token_sort_ratio("fuzzy wuzzy was a bear", "wuzzy fuzzy was a bear");
         100
 ```
 
-**Token Set Ratio** 
+**Token Set Ratio**
 
 Highest of 3 scores comparing the set intersection, intersection + difference 1 to 2, and intersection + difference 2 to 1.
 ```js
 fuzz.token_sort_ratio("fuzzy was a bear", "fuzzy fuzzy was a bear");
         84
-fuzz.token_set_ratio("fuzzy was a bear", "fuzzy fuzzy was a bear"); 
+fuzz.token_set_ratio("fuzzy was a bear", "fuzzy fuzzy was a bear");
         100
 ```
 If you set options.trySimple to true it will add the simple ratio to the token_set_ratio test suite as well. This can help smooth out occational irregularities in how much differences in the first letter of a token will get penalized.
 
-**Token Similarity Sort Ratio** 
+**Token Similarity Sort Ratio**
 
 Instead of sorting alphabetically, tokens will be sorted by similarity to the smaller set. Useful if the matching token may have a different first letter, but performs a bit slower. You can also use similarity sorting when calculating token_set_ratio by setting sortBySimilarity to true.
 
@@ -200,7 +212,7 @@ fuzz.ratio("this is ä test", "this is a test", options);
         100
 ```
 
-If your strings contain code points beyond the basic multilingual plane (BMP), set **astral** to true. If your strings contain astral symbols and this is not set, those symbols will be treated as multiple characters and the ratio will be off a bit. (This will have some impact on performance, which is why it is turned off by default.) 
+If your strings contain code points beyond the basic multilingual plane (BMP), set **astral** to true. If your strings contain astral symbols and this is not set, those symbols will be treated as multiple characters and the ratio will be off a bit. (This will have some impact on performance, which is why it is turned off by default.)
 
 ```js
 options = {astral: true};
@@ -211,7 +223,7 @@ fuzz.ratio("ab🐴c", "ab🐴d", options);
 
 When astral is true it will also normalize your strings before scoring, as long as String.prototype.normalize exists in your environment, but will not attempt to polyfill. (So if you need to compare unnormalized strings in IE, normalize separately) You can set the **normalize** option to false if you want different representations not to match, but is true by default.
 
-### Batch Extract 
+### Batch Extract
 Search list of choices for top results.
 
 ###### fuzz.extract(query, choices, options);
@@ -318,16 +330,45 @@ results = fuzz.extract(query, choices, options);
 
 ### Async and Cancellation
 
-When using extractAsPromised or extractAsync, create a new object with a 'canceled' property to use as a cancel token. For performance, by default only every 256th loop will be async, but set asyncLoopOffset to change. It is most likely not worth changing this.
+When using extractAsPromised or extractAsync, you might want to cancel the action before it has finished.
+It can be done using `CancelToken` or `AbortController`.
+
+For performance, by default only every 256th loop will be async, but set `asyncLoopOffset` to change. It is most likely not worth changing this.
+
+**AbortController**
+
+[AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) is present in modern browsers and from node version `15+`. It is currently a standard way how to cancel running operations.
 
 ```js
-let cancelToken = {canceled: false};
+// or use AbortController to cancel search
+const abortController = new AbortController();
+
+options.abortController = abortController;
+options.asyncLoopOffset = 64;
+
+fuzz.extractAsPromised("gonna get aborted", choices, options)
+        .then(res => {/* do stuff */})
+        .catch((e) => {
+                if (e.message === 'aborted') console.log('I got aborted!')
+        });
+
+abortController.abort();
+```
+
+**CancelToken**
+
+For older browsers and node versions you can use cancel token. It is an in
+
+```js
+let cancelToken = { canceled: false };
+
 options.cancelToken = cancelToken;
 options.asyncLoopOffset = 64;
+
 fuzz.extractAsPromised("gonna get canceled", choices, options)
         .then(res => {/* do stuff */})
         .catch((e) => {
-                if (e.message === 'canceled') console.log('I got canceled!') 
+                if (e.message === 'canceled') console.log('I got canceled!')
         });
 
 // ...
@@ -476,4 +517,4 @@ Thanks to dvisg and voidevector on reddit for .d.ts feedback.
 
 ### Contributions
 
-Pull requests welcome.
+Pull requests welcome.

dist/esm/fuzzball.esm.min.js

@@ -67,6 +67,13 @@ interface FuzzballExtractBaseOptions extends FuzzballBaseOptions {
     sortBySimilarity?: boolean
 }
 
+interface AbortController {
+    /**
+     * If extract has been aborted;
+     */
+    signal: { aborted: boolean }
+}
+
 interface CancellationToken {
     /**
      * If extract has been canceled;
@@ -89,6 +96,10 @@ export interface FuzzballExtractObjectOptions extends FuzzballExtractBaseOptions
 }
 
 export interface FuzzballAsyncExtractOptions extends FuzzballExtractOptions {
+    /**
+     * Track if extract has been aborted
+     */
+    abortController?: AbortController;
     /**
      * Track if extract has been canceled
      */
@@ -100,6 +111,10 @@ export interface FuzzballAsyncExtractOptions extends FuzzballExtractOptions {
 }
 
 export interface FuzzballAsyncExtractObjectOptions extends FuzzballExtractObjectOptions {
+    /**
+     * Track if extract has been aborted
+     */
+     abortController?: AbortController;
     /**
      * Track if extract has been canceled;
      */

dist/fuzzball.umd.min.js

@@ -511,11 +511,18 @@
          * @param {boolean} [options_p.sortBySimilarity] - sort tokens by similarity to each other before combining instead of alphabetically
          * @param {string} [options_p.wildcards] - characters that will be used as wildcards if provided
          * @param {boolean} [options_p.returnObjects] - return array of object instead of array of tuples; default false
+         * @param {Object} [options_p.abortController] - track abortion
          * @param {Object} [options_p.cancelToken] - track cancellation
          * @param {number} [options_p.asyncLoopOffset] - number of rows to run in between every async loop iteration, default 256
          * @param {function} callback - node style callback (err, arrayOfResults)
          */
         var options = clone_and_set_option_defaults(options_p);
+
+        var abortController;
+        if (typeof options_p.abortController === "object") {
+            abortController = options_p.abortController;
+        }
+
         var cancelToken;
         if (typeof options_p.cancelToken === "object") {
             cancelToken = options_p.cancelToken;
@@ -646,6 +653,11 @@
                 }
             }
 
+            if (abortController && abortController.signal.aborted === true) {
+                callback(new Error("aborted"));
+                return;
+            }
+
             if (cancelToken && cancelToken.canceled === true) {
                 callback(new Error("canceled"));
                 return;
@@ -742,7 +754,7 @@
                 }
             }
         }
-        
+
         return charCounts;
     }
 

fuzzball.d.ts

@@ -280,6 +280,7 @@ Return the top scoring items from an array (or assoc array) of choices
 | [options_p.sortBySimilarity] | <code>boolean</code> | sort tokens by similarity to each other before combining instead of alphabetically |
 | [options_p.wildcards] | <code>string</code> | characters that will be used as wildcards if provided |
 | [options_p.returnObjects] | <code>boolean</code> | return array of object instead of array of tuples; default false |
+| [options_p.abortController] | <code>Object</code> | track abortion |
 | [options_p.cancelToken] | <code>Object</code> | track cancellation |
 | [options_p.asyncLoopOffset] | <code>number</code> | number of rows to run in between every async loop iteration, default 256 |
 | callback | <code>function</code> | node style callback (err, arrayOfResults) |

fuzzball.js

@@ -59,6 +59,13 @@ interface FuzzballExtractBaseOptions extends FuzzballBaseOptions {
     cutoff?: number;
 }
 
+interface AbortController {
+    /**
+     * If extract has been aborted;
+     */
+    signal: { aborted: boolean }
+}
+
 interface CancellationToken {
     /**
      * If extract has been canceled;
@@ -81,6 +88,10 @@ export interface FuzzballExtractObjectOptions extends FuzzballExtractBaseOptions
 }
 
 export interface FuzzballAsyncExtractOptions extends FuzzballExtractOptions {
+    /**
+     * Track if extract has been aborted
+     */
+    abortController?: AbortController;
     /**
      * Track if extract has been canceled
      */
@@ -92,6 +103,10 @@ export interface FuzzballAsyncExtractOptions extends FuzzballExtractOptions {
 }
 
 export interface FuzzballAsyncExtractObjectOptions extends FuzzballExtractObjectOptions {
+    /**
+     * Track if extract has been aborted
+     */
+    abortController?: AbortController;
     /**
      * Track if extract has been canceled;
      */

jsdocs/fuzzball.md

@@ -28,7 +28,7 @@
 
     var processing = require('../lib/process.js')(clone_and_set_option_defaults, Array.isArray, QRatio, extract);
     var dedupe = processing.dedupe;
- 
+
 /** Mostly follows after python fuzzywuzzy, https://github.com/seatgeek/fuzzywuzzy */
 
 
@@ -292,12 +292,18 @@
          * @param {boolean} [options_p.trySimple] - try simple/partial ratio as part of (parial_)token_set_ratio test suite
          * @param {string} [options_p.wildcards] - characters that will be used as wildcards if provided
          * @param {boolean} [options_p.returnObjects] - return array of object instead of array of tuples; default false
+         * @param {Object} [options_p.abortController] - track abortion
          * @param {Object} [options_p.cancelToken] - track cancellation
          * @param {number} [options_p.asyncLoopOffset] - number of rows to run in between every async loop iteration, default 256
          * @param {function} callback - node style callback (err, arrayOfResults)
          */
         var options = clone_and_set_option_defaults(options_p);
 
+        var abortController;
+        if (typeof options_p.abortController === "object") {
+            abortController = options_p.abortController;
+        }
+
         var cancelToken;
         if (typeof options_p.cancelToken === "object") {
             cancelToken = options_p.cancelToken;
@@ -428,6 +434,11 @@
                 }
             }
 
+            if (abortController && abortController.signal.aborted === true) {
+                callback(new Error("aborted"));
+                return;
+            }
+
             if (cancelToken && cancelToken.canceled === true) {
                 callback(new Error("canceled"));
                 return;
@@ -476,7 +487,7 @@
         var sorted_2to1 = diff2to1.sort().join(" ");
         var combined_1to2 = sorted_sect + " " + sorted_1to2;
         var combined_2to1 = sorted_sect + " " + sorted_2to1;
-        
+
         sorted_sect = sorted_sect.trim();
         combined_1to2 = combined_1to2.trim();
         combined_2to1 = combined_2to1.trim();