@common.js/p-limit 6.1.0 → 7.3.0

package/README.md

@@ -2,4 +2,4 @@
 
 The [p-limit](https://www.npmjs.com/package/p-limit) package exported as CommonJS modules.
 
-Exported from [p-limit@6.1.0](https://www.npmjs.com/package/p-limit/v/6.1.0) using https://github.com/etienne-martin/common.js.
+Exported from [p-limit@7.3.0](https://www.npmjs.com/package/p-limit/v/7.3.0) using https://github.com/etienne-martin/common.js.

package/index.d.ts

@@ -20,12 +20,34 @@ export type LimitFunction = {
 	This might be useful if you want to teardown the queue at the end of your program's lifecycle or discard any function calls referencing an intermediary state of your app.
 
 	Note: This does not cancel promises that are already running.
+
+	When `rejectOnClear` is enabled, pending promises are rejected with an `AbortError`.
+	This is recommended if you await the returned promises, for example with `Promise.all`, so pending tasks do not remain unresolved after `clearQueue()`.
 	*/
 	clearQueue: () => void;
 
+	/**
+	Process an iterable of inputs with limited concurrency.
+
+	The mapper function receives the item value and its index.
+
+	This is a convenience function for processing inputs that arrive in batches. For more complex use cases, see [p-map](https://github.com/sindresorhus/p-map).
+
+	@param iterable - An iterable containing an argument for the given function.
+	@param mapperFunction - Promise-returning/async function.
+	@returns A promise equivalent to `Promise.all(Array.from(iterable, (item, index) => limit(mapperFunction, item, index)))`.
+	*/
+	map: <Input, ReturnType> (
+		iterable: Iterable<Input>,
+		mapperFunction: (input: Input, index: number) => PromiseLike<ReturnType> | ReturnType
+	) => Promise<ReturnType[]>;
+
 	/**
 	@param fn - Promise-returning/async function.
-	@param arguments - Any arguments to pass through to `fn`. Support for passing arguments on to the `fn` is provided in order to be able to avoid creating unnecessary closures. You probably don't need this optimization unless you're pushing a lot of functions.
+	@param arguments - Any arguments to pass through to `fn`. Support for passing arguments on to the `fn` is provided in order to be able to avoid creating unnecessary closures. You probably don't need this optimization unless you're pushing a *lot* of functions.
+
+	Warning: Avoid calling the same `limit` function inside a function that is already limited by it. This can create a deadlock where inner tasks never run. Use a separate limiter for inner tasks.
+
 	@returns The promise returned by calling `fn(...arguments)`.
 	*/
 	<Arguments extends unknown[], ReturnType>(
@@ -37,7 +59,78 @@ export type LimitFunction = {
 /**
 Run multiple promise-returning & async functions with limited concurrency.
 
-@param concurrency - Concurrency limit. Minimum: `1`.
+@param concurrency - Concurrency limit. Minimum: `1`. You can pass a number or an options object with a `concurrency` property.
 @returns A `limit` function.
+
+@example
+```
+import pLimit from 'p-limit';
+
+const limit = pLimit(1);
+
+const input = [
+	limit(() => fetchSomething('foo')),
+	limit(() => fetchSomething('bar')),
+	limit(() => doSomething())
+];
+
+// Only one promise is run at once
+const result = await Promise.all(input);
+console.log(result);
+```
+
+@example
+```
+import pLimit from 'p-limit';
+
+const limit = pLimit({concurrency: 1});
+```
+*/
+export default function pLimit(concurrency: number | Options): LimitFunction;
+
+export type Options = {
+	/**
+	Concurrency limit.
+
+	Minimum: `1`.
+	*/
+	readonly concurrency: number;
+
+	/**
+	Reject pending promises with an `AbortError` when `clearQueue()` is called.
+
+	Default: `false`.
+
+	This is recommended if you await the returned promises, for example with `Promise.all`, so pending tasks do not remain unresolved after `clearQueue()`.
+	*/
+	readonly rejectOnClear?: boolean;
+};
+
+/**
+Returns a function with limited concurrency.
+
+The returned function manages its own concurrent executions, allowing you to call it multiple times without exceeding the specified concurrency limit.
+
+Ideal for scenarios where you need to control the number of simultaneous executions of a single function, rather than managing concurrency across multiple functions.
+
+@param function_ - Promise-returning/async function.
+@return Function with limited concurrency.
+
+@example
+```
+import {limitFunction} from 'p-limit';
+
+const limitedFunction = limitFunction(async () => {
+	return doSomething();
+}, {concurrency: 1});
+
+const input = Array.from({length: 10}, limitedFunction);
+
+// Only one promise is run at once.
+await Promise.all(input);
+```
 */
-export default function pLimit(concurrency: number): LimitFunction;
+export function limitFunction<Arguments extends unknown[], ReturnType>(
+	function_: (...arguments_: Arguments) => PromiseLike<ReturnType>,
+	options: Options
+): (...arguments_: Arguments) => Promise<ReturnType>;

package/index.js

@@ -2,10 +2,18 @@
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
-Object.defineProperty(exports, "default", {
-    enumerable: true,
-    get: function() {
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    default: function() {
         return pLimit;
+    },
+    limitFunction: function() {
+        return limitFunction;
     }
 });
 var _yoctoQueue = /*#__PURE__*/ _interopRequireDefault(require("yocto-queue"));
@@ -164,14 +172,22 @@ var __generator = (void 0) && (void 0).__generator || function(thisArg, body) {
     }
 };
 function pLimit(concurrency) {
+    var rejectOnClear = false;
+    if (typeof concurrency === "object") {
+        var ref, ref1;
+        ref = concurrency, concurrency = ref.concurrency, ref1 = ref.rejectOnClear, rejectOnClear = ref1 === void 0 ? false : ref1, ref;
+    }
     validateConcurrency(concurrency);
+    if (typeof rejectOnClear !== "boolean") {
+        throw new TypeError("Expected `rejectOnClear` to be a boolean");
+    }
     var queue = new _yoctoQueue.default();
     var activeCount = 0;
     var resumeNext = function() {
+        // Process the next queued function if we're under the concurrency limit
         if (activeCount < concurrency && queue.size > 0) {
-            queue.dequeue()();
-            // Since `pendingCount` has been decreased by one, increase `activeCount` by one.
             activeCount++;
+            queue.dequeue().run();
         }
     };
     var next = function() {
@@ -192,6 +208,7 @@ function pLimit(concurrency) {
                                 ];
                             });
                         })();
+                        // Resolve immediately with the promise (don't wait for completion)
                         resolve(result);
                         _state.label = 1;
                     case 1:
@@ -218,6 +235,7 @@ function pLimit(concurrency) {
                             4
                         ];
                     case 4:
+                        // Decrement active count and process next queued function
                         next();
                         return [
                             2
@@ -229,42 +247,27 @@ function pLimit(concurrency) {
             return _ref.apply(this, arguments);
         };
     }();
-    var enqueue = function(function_, resolve, arguments_) {
-        // Queue `internalResolve` instead of the `run` function
-        // to preserve asynchronous context.
+    var enqueue = function(function_, resolve, reject, arguments_) {
+        var queueItem = {
+            reject: reject
+        };
+        // Queue the internal resolve function instead of the run function
+        // to preserve the asynchronous execution context.
         new Promise(function(internalResolve) {
-            queue.enqueue(internalResolve);
-        }).then(run.bind(undefined, function_, resolve, arguments_));
-        _asyncToGenerator(function() {
-            return __generator(this, function(_state) {
-                switch(_state.label){
-                    case 0:
-                        // This function needs to wait until the next microtask before comparing
-                        // `activeCount` to `concurrency`, because `activeCount` is updated asynchronously
-                        // after the `internalResolve` function is dequeued and called. The comparison in the if-statement
-                        // needs to happen asynchronously as well to get an up-to-date value for `activeCount`.
-                        return [
-                            4,
-                            Promise.resolve()
-                        ];
-                    case 1:
-                        _state.sent();
-                        if (activeCount < concurrency) {
-                            resumeNext();
-                        }
-                        return [
-                            2
-                        ];
-                }
-            });
-        })();
+            queueItem.run = internalResolve;
+            queue.enqueue(queueItem);
+        }).then(run.bind(undefined, function_, resolve, arguments_)); // eslint-disable-line promise/prefer-await-to-then
+        // Start processing immediately if we haven't reached the concurrency limit
+        if (activeCount < concurrency) {
+            resumeNext();
+        }
     };
     var generator = function(function_) {
         for(var _len = arguments.length, arguments_ = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++){
             arguments_[_key - 1] = arguments[_key];
         }
-        return new Promise(function(resolve) {
-            enqueue(function_, resolve, arguments_);
+        return new Promise(function(resolve, reject) {
+            enqueue(function_, resolve, reject, arguments_);
         });
     };
     Object.defineProperties(generator, {
@@ -280,7 +283,14 @@ function pLimit(concurrency) {
         },
         clearQueue: {
             value: function value() {
-                queue.clear();
+                if (!rejectOnClear) {
+                    queue.clear();
+                    return;
+                }
+                var abortError = AbortSignal.abort().reason;
+                while(queue.size > 0){
+                    queue.dequeue().reject(abortError);
+                }
             }
         },
         concurrency: {
@@ -297,10 +307,38 @@ function pLimit(concurrency) {
                     }
                 });
             }
+        },
+        map: {
+            value: function value(iterable, function_) {
+                return _asyncToGenerator(function() {
+                    var _this, promises;
+                    return __generator(this, function(_state) {
+                        _this = this;
+                        promises = Array.from(iterable, function(value, index) {
+                            return _this(function_, value, index);
+                        });
+                        return [
+                            2,
+                            Promise.all(promises)
+                        ];
+                    });
+                }).apply(this);
+            }
         }
     });
     return generator;
 }
+function limitFunction(function_, options) {
+    var limit = pLimit(options);
+    return function() {
+        for(var _len = arguments.length, arguments_ = new Array(_len), _key = 0; _key < _len; _key++){
+            arguments_[_key] = arguments[_key];
+        }
+        return limit(function() {
+            return function_.apply(void 0, _toConsumableArray(arguments_));
+        });
+    };
+}
 function validateConcurrency(concurrency) {
     if (!((Number.isInteger(concurrency) || concurrency === Number.POSITIVE_INFINITY) && concurrency > 0)) {
         throw new TypeError("Expected `concurrency` to be a number from 1 and up");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@common.js/p-limit",
-  "version": "6.1.0",
+  "version": "7.3.0",
   "description": "p-limit package exported as CommonJS modules",
   "license": "MIT",
   "repository": "etienne-martin/common.js",
@@ -8,28 +8,28 @@
   "type": "commonjs",
   "sideEffects": false,
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
-    "test": "xo && ava && tsd"
+    "test": "xo && ava && tsd",
+    "benchmark": "node benchmark.js"
   },
   "files": [
     "index.js",
     "index.d.ts"
   ],
   "dependencies": {
-    "@common.js/yocto-queue": "^1.1.1"
+    "@common.js/yocto-queue": "^1.2.1"
   },
   "devDependencies": {
-    "ava": "^6.1.3",
-    "delay": "^6.0.0",
+    "ava": "^6.4.1",
     "in-range": "^3.0.0",
     "random-int": "^3.0.0",
     "time-span": "^5.1.0",
-    "tsd": "^0.31.1",
-    "xo": "^0.58.0"
+    "tsd": "^0.33.0",
+    "xo": "^1.2.1"
   },
   "homepage": "https://github.com/etienne-martin/common.js#readme",
-  "types": "./index.d.ts",
-  "main": "./index.js"
+  "main": "./index.js",
+  "types": "./index.d.ts"
 }