@common.js/p-queue 7.4.1 → 9.3.1

package/dist/options.d.ts

@@ -1,17 +1,28 @@
-import { Queue, RunFunction } from './queue.js';
-interface TimeoutOptions {
+import { type Queue, type RunFunction } from './queue.js';
+type TimeoutOptions = {
     /**
-    Per-operation timeout in milliseconds. Operations fulfill once `timeout` elapses if they haven't already.
-    */
-    timeout?: number;
-    /**
-    Whether or not a timeout is considered an exception.
+    Per-operation timeout in milliseconds. Operations will throw a `TimeoutError` if they don't complete within the specified time.
 
-    @default false
+    The timeout begins when the operation is dequeued and starts execution, not while it's waiting in the queue.
+
+    @default undefined
+
+    Can be overridden per task using the `timeout` option in `.add()`:
+
+    @example
+    ```
+    const queue = new PQueue({timeout: 5000});
+
+    // This task uses the global 5s timeout
+    await queue.add(() => fetchData());
+
+    // This task has a 10s timeout
+    await queue.add(() => slowTask(), {timeout: 10000});
+    ```
     */
-    throwOnTimeout?: boolean;
-}
-export interface Options<QueueType extends Queue<RunFunction, QueueOptions>, QueueOptions extends QueueAddOptions> extends TimeoutOptions {
+    timeout?: number;
+};
+export type Options<QueueType extends Queue<RunFunction, QueueOptions>, QueueOptions extends QueueAddOptions> = {
     /**
     Concurrency limit.
 
@@ -21,7 +32,7 @@ export interface Options<QueueType extends Queue<RunFunction, QueueOptions>, Que
     */
     readonly concurrency?: number;
     /**
-    Whether queue tasks within concurrency limit, are auto-executed as soon as they're added.
+    Whether queue tasks within the concurrency limit are auto-executed as soon as they're added.
 
     @default true
     */
@@ -51,17 +62,41 @@ export interface Options<QueueType extends Queue<RunFunction, QueueOptions>, Que
 
     @default false
     */
+    readonly carryoverIntervalCount?: boolean;
+    /**
+    @deprecated Renamed to `carryoverIntervalCount`.
+    */
     readonly carryoverConcurrencyCount?: boolean;
-}
-export interface QueueAddOptions extends TaskOptions, TimeoutOptions {
+    /**
+    Whether to use strict mode for rate limiting (sliding window algorithm).
+
+    When enabled, ensures that no more than `intervalCap` tasks execute in any rolling `interval` window, rather than resetting the count at fixed intervals. This provides more predictable and evenly distributed execution.
+
+    @default false
+
+    For example, with `intervalCap: 2` and `interval: 1000`:
+    - __Default mode (fixed window)__: Tasks can burst at window boundaries. You could execute 2 tasks at 999ms and 2 more at 1000ms, resulting in 4 tasks within 1ms.
+    - __Strict mode (sliding window)__: Enforces that no more than 2 tasks execute in any 1000ms rolling window, preventing bursts.
+
+    Strict mode is more resource-intensive as it tracks individual execution timestamps. Use it when you need guaranteed rate-limit compliance, such as when interacting with APIs that enforce strict rate limits.
+
+    The `carryoverIntervalCount` option has no effect when `strict` mode is enabled, as strict mode tracks actual execution timestamps rather than counting pending tasks.
+    */
+    readonly strict?: boolean;
+} & TimeoutOptions;
+export type QueueAddOptions = {
     /**
     Priority of operation. Operations with greater priority will be scheduled first.
 
     @default 0
     */
     readonly priority?: number;
-}
-export interface TaskOptions {
+    /**
+    Unique identifier for the promise function, used to update its priority before execution. If not specified, it is auto-assigned an incrementing BigInt starting from `1n`.
+    */
+    id?: string;
+} & TaskOptions & TimeoutOptions;
+export type TaskOptions = {
     /**
     [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for cancellation of the operation. When aborted, it will be removed from the queue and the `queue.add()` call will reject with an `AbortError`. If the operation is already running, the signal will need to be handled by the operation itself.
 
@@ -97,6 +132,6 @@ export interface TaskOptions {
     }
     ```
     */
-    readonly signal?: AbortSignal;
-}
+    readonly signal?: AbortSignal | undefined;
+};
 export {};

package/dist/priority-queue.d.ts

@@ -1,11 +1,14 @@
-import { Queue, RunFunction } from './queue.js';
-import { QueueAddOptions } from './options.js';
-export interface PriorityQueueOptions extends QueueAddOptions {
+import { type Queue, type RunFunction } from './queue.js';
+import { type QueueAddOptions } from './options.js';
+export type PriorityQueueOptions = {
     priority?: number;
-}
+} & QueueAddOptions;
 export default class PriorityQueue implements Queue<RunFunction, PriorityQueueOptions> {
     #private;
     enqueue(run: RunFunction, options?: Partial<PriorityQueueOptions>): void;
+    setPriority(id: string, priority: number): void;
+    remove(id: string): void;
+    remove(run: RunFunction): void;
     dequeue(): RunFunction | undefined;
     filter(options: Readonly<Partial<PriorityQueueOptions>>): RunFunction[];
     get size(): number;

package/dist/priority-queue.js

@@ -5,15 +5,97 @@ Object.defineProperty(exports, "__esModule", {
 Object.defineProperty(exports, "default", {
     enumerable: true,
     get: function() {
-        return _default;
+        return PriorityQueue;
     }
 });
 var _lowerBoundJs = /*#__PURE__*/ _interopRequireDefault(require("./lower-bound.js"));
+function _arrayLikeToArray(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _arrayWithHoles(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function _checkPrivateRedeclaration(obj, privateCollection) {
+    if (privateCollection.has(obj)) {
+        throw new TypeError("Cannot initialize the same private elements twice on an object");
+    }
+}
+function _classApplyDescriptorGet(receiver, descriptor) {
+    if (descriptor.get) {
+        return descriptor.get.call(receiver);
+    }
+    return descriptor.value;
+}
+function _classApplyDescriptorSet(receiver, descriptor, value) {
+    if (descriptor.set) {
+        descriptor.set.call(receiver, value);
+    } else {
+        if (!descriptor.writable) {
+            throw new TypeError("attempted to set read only private field");
+        }
+        descriptor.value = value;
+    }
+}
+function _classApplyDescriptorUpdate(receiver, descriptor) {
+    if (descriptor.set) {
+        if (!("__destrWrapper" in descriptor)) {
+            descriptor.__destrWrapper = {
+                set value (v){
+                    descriptor.set.call(receiver, v);
+                },
+                get value () {
+                    return descriptor.get.call(receiver);
+                }
+            };
+        }
+        return descriptor.__destrWrapper;
+    } else {
+        if (!descriptor.writable) {
+            throw new TypeError("attempted to set read only private field");
+        }
+        return descriptor;
+    }
+}
 function _classCallCheck(instance, Constructor) {
     if (!(instance instanceof Constructor)) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
+function _classExtractFieldDescriptor(receiver, privateMap, action) {
+    if (!privateMap.has(receiver)) {
+        throw new TypeError("attempted to " + action + " private field on non-instance");
+    }
+    return privateMap.get(receiver);
+}
+function _classPrivateFieldGet(receiver, privateMap) {
+    var descriptor = _classExtractFieldDescriptor(receiver, privateMap, "get");
+    return _classApplyDescriptorGet(receiver, descriptor);
+}
+function _classPrivateFieldInit(obj, privateMap, value) {
+    _checkPrivateRedeclaration(obj, privateMap);
+    privateMap.set(obj, value);
+}
+function _classPrivateFieldSet(receiver, privateMap, value) {
+    var descriptor = _classExtractFieldDescriptor(receiver, privateMap, "set");
+    _classApplyDescriptorSet(receiver, descriptor, value);
+    return value;
+}
+function _classPrivateFieldUpdate(receiver, privateMap) {
+    var descriptor = _classExtractFieldDescriptor(receiver, privateMap, "update");
+    return _classApplyDescriptorUpdate(receiver, descriptor);
+}
+function _classPrivateMethodGet(receiver, privateSet, fn) {
+    if (!privateSet.has(receiver)) {
+        throw new TypeError("attempted to get private field on non-instance");
+    }
+    return fn;
+}
+function _classPrivateMethodInit(obj, privateSet) {
+    _checkPrivateRedeclaration(obj, privateSet);
+    privateSet.add(obj);
+}
 function _defineProperties(target, props) {
     for(var i = 0; i < props.length; i++){
         var descriptor = props[i];
@@ -28,97 +110,180 @@ function _createClass(Constructor, protoProps, staticProps) {
     if (staticProps) _defineProperties(Constructor, staticProps);
     return Constructor;
 }
-function _defineProperty(obj, key, value) {
-    if (key in obj) {
-        Object.defineProperty(obj, key, {
-            value: value,
-            enumerable: true,
-            configurable: true,
-            writable: true
-        });
-    } else {
-        obj[key] = value;
-    }
-    return obj;
-}
 function _interopRequireDefault(obj) {
     return obj && obj.__esModule ? obj : {
         default: obj
     };
 }
-function _objectSpread(target) {
-    for(var i = 1; i < arguments.length; i++){
-        var source = arguments[i] != null ? arguments[i] : {};
-        var ownKeys = Object.keys(source);
-        if (typeof Object.getOwnPropertySymbols === "function") {
-            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
-                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
-            }));
+function _iterableToArrayLimit(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
         }
-        ownKeys.forEach(function(key) {
-            _defineProperty(target, key, source[key]);
-        });
     }
-    return target;
-}
-var __classPrivateFieldGet = (void 0) && (void 0).__classPrivateFieldGet || function(receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _PriorityQueue_queue;
+    return _arr;
+}
+function _nonIterableRest() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _slicedToArray(arr, i) {
+    return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest();
+}
+function _unsupportedIterableToArray(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _arrayLikeToArray(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen);
+}
+var compactionThreshold = 100;
+var _queue = /*#__PURE__*/ new WeakMap(), // The queue is stored as a sorted array, but dequeued items are left before `#head` until compaction. Only items from `#head` onward are live, which keeps repeated dequeues amortized O(1).
+_head = /*#__PURE__*/ new WeakMap(), _compact = /*#__PURE__*/ new WeakSet();
 var PriorityQueue = /*#__PURE__*/ function() {
     "use strict";
     function PriorityQueue() {
         _classCallCheck(this, PriorityQueue);
-        _PriorityQueue_queue.set(this, []);
+        _classPrivateMethodInit(this, _compact);
+        _classPrivateFieldInit(this, _queue, {
+            writable: true,
+            value: []
+        });
+        _classPrivateFieldInit(this, _head, {
+            writable: true,
+            value: 0
+        });
     }
     _createClass(PriorityQueue, [
         {
             key: "enqueue",
             value: function enqueue(run, options) {
-                options = _objectSpread({
-                    priority: 0
-                }, options);
+                var ref = options !== null && options !== void 0 ? options : {}, _priority = ref.priority, priority = _priority === void 0 ? 0 : _priority, id = ref.id;
+                var size = this.size;
                 var element = {
-                    priority: options.priority,
+                    priority: priority,
+                    id: id,
                     run: run
                 };
-                if (this.size && __classPrivateFieldGet(this, _PriorityQueue_queue, "f")[this.size - 1].priority >= options.priority) {
-                    __classPrivateFieldGet(this, _PriorityQueue_queue, "f").push(element);
+                if (size === 0) {
+                    // When the queue is logically empty, discard any consumed prefix before accepting new work.
+                    _classPrivateFieldGet(this, _queue).length = 0;
+                    _classPrivateFieldSet(this, _head, 0);
+                    _classPrivateFieldGet(this, _queue).push(element);
+                    return;
+                }
+                if (_classPrivateFieldGet(this, _queue).at(-1).priority >= priority) {
+                    // Same-priority and lower-priority items belong after the current tail. Appending preserves FIFO order for equal priorities.
+                    _classPrivateFieldGet(this, _queue).push(element);
                     return;
                 }
-                var index = (0, _lowerBoundJs.default)(__classPrivateFieldGet(this, _PriorityQueue_queue, "f"), element, function(a, b) {
+                // Binary insertion must run on the live sorted range only.
+                _classPrivateMethodGet(this, _compact, compact).call(this);
+                var index = (0, _lowerBoundJs.default)(_classPrivateFieldGet(this, _queue), element, function(a, b) {
                     return b.priority - a.priority;
                 });
-                __classPrivateFieldGet(this, _PriorityQueue_queue, "f").splice(index, 0, element);
+                _classPrivateFieldGet(this, _queue).splice(index, 0, element);
+            }
+        },
+        {
+            key: "setPriority",
+            value: function setPriority(id, priority) {
+                var _this = this;
+                // A dequeued item with the same id is no longer part of the queue.
+                var index = _classPrivateFieldGet(this, _queue).findIndex(function(element, index) {
+                    return index >= _classPrivateFieldGet(_this, _head) && element.id === id;
+                });
+                if (index === -1) {
+                    throw new ReferenceError('No promise function with the id "'.concat(id, '" exists in the queue.'));
+                }
+                var ref = _slicedToArray(_classPrivateFieldGet(this, _queue).splice(index, 1), 1), item = ref[0];
+                this.enqueue(item.run, {
+                    priority: priority,
+                    id: id
+                });
+            }
+        },
+        {
+            key: "remove",
+            value: function remove(idOrRun) {
+                var _this = this;
+                var index = _classPrivateFieldGet(this, _queue).findIndex(function(element, index) {
+                    // The consumed prefix may still contain references that should not be removable.
+                    if (index < _classPrivateFieldGet(_this, _head)) {
+                        return false;
+                    }
+                    if (typeof idOrRun === "string") {
+                        return element.id === idOrRun;
+                    }
+                    return element.run === idOrRun;
+                });
+                if (index !== -1) {
+                    _classPrivateFieldGet(this, _queue).splice(index, 1);
+                }
             }
         },
         {
             key: "dequeue",
             value: function dequeue() {
-                var item = __classPrivateFieldGet(this, _PriorityQueue_queue, "f").shift();
+                if (_classPrivateFieldGet(this, _head) === _classPrivateFieldGet(this, _queue).length) {
+                    return undefined;
+                }
+                var item = _classPrivateFieldGet(this, _queue)[_classPrivateFieldGet(this, _head)];
+                _classPrivateFieldUpdate(this, _head).value++;
+                if (_classPrivateFieldGet(this, _head) === _classPrivateFieldGet(this, _queue).length) {
+                    // Fully drained queues are reset immediately so the next enqueue starts from a clean array.
+                    _classPrivateFieldGet(this, _queue).length = 0;
+                    _classPrivateFieldSet(this, _head, 0);
+                } else if (_classPrivateFieldGet(this, _head) > compactionThreshold && _classPrivateFieldGet(this, _head) > _classPrivateFieldGet(this, _queue).length / 2) {
+                    // Keep repeated dequeues cheap, but stop the consumed prefix from growing without bound.
+                    _classPrivateMethodGet(this, _compact, compact).call(this);
+                }
                 return item === null || item === void 0 ? void 0 : item.run;
             }
         },
         {
             key: "filter",
             value: function filter(options) {
-                return __classPrivateFieldGet(this, _PriorityQueue_queue, "f").filter(function(element) {
-                    return element.priority === options.priority;
-                }).map(function(element) {
-                    return element.run;
-                });
+                var result = [];
+                for(var index = _classPrivateFieldGet(this, _head); index < _classPrivateFieldGet(this, _queue).length; index++){
+                    var element = _classPrivateFieldGet(this, _queue)[index];
+                    if (element.priority === options.priority) {
+                        result.push(element.run);
+                    }
+                }
+                return result;
             }
         },
         {
             key: "size",
             get: function get() {
-                return __classPrivateFieldGet(this, _PriorityQueue_queue, "f").length;
+                return _classPrivateFieldGet(this, _queue).length - _classPrivateFieldGet(this, _head);
             }
         }
     ]);
     return PriorityQueue;
 }();
-_PriorityQueue_queue = new WeakMap();
-var _default = PriorityQueue;
+function compact() {
+    // Compaction restores the invariant that the whole array is the live sorted range.
+    if (_classPrivateFieldGet(this, _head) === 0) {
+        return;
+    }
+    _classPrivateFieldGet(this, _queue).splice(0, _classPrivateFieldGet(this, _head));
+    _classPrivateFieldSet(this, _head, 0);
+}

package/dist/queue.d.ts

@@ -1,7 +1,9 @@
 export type RunFunction = () => Promise<unknown>;
-export interface Queue<Element, Options> {
+export type Queue<Element, Options> = {
     size: number;
-    filter: (options: Partial<Options>) => Element[];
+    filter: (options: Readonly<Partial<Options>>) => Element[];
     dequeue: () => Element | undefined;
     enqueue: (run: Element, options?: Partial<Options>) => void;
-}
+    setPriority: (id: string, priority: number) => void;
+    remove?: (id: string) => void;
+};

package/package.json

@@ -1,61 +1,54 @@
 {
   "name": "@common.js/p-queue",
-  "version": "7.4.1",
+  "version": "9.3.1",
   "description": "p-queue package exported as CommonJS modules",
   "license": "MIT",
   "repository": "etienne-martin/common.js",
   "funding": "https://github.com/sponsors/sindresorhus",
   "type": "commonjs",
+  "sideEffects": false,
   "engines": {
-    "node": ">=12"
+    "node": ">=20"
   },
   "scripts": {
     "build": "del-cli dist && tsc",
-    "//test": "xo && ava && del-cli dist && tsc && tsd",
-    "test": "ava && del-cli dist && tsc && tsd",
-    "bench": "node --loader=ts-node/esm bench.ts"
+    "test": "xo && node --import=tsx/esm --test test/*.ts && del-cli dist && tsc && tsd",
+    "bench": "node --import=tsx/esm bench.ts"
   },
   "files": [
     "dist"
   ],
-  "types": "dist/index.d.ts",
+  "types": "./dist/index.d.ts",
   "dependencies": {
-    "eventemitter3": "^5.0.1",
-    "@common.js/p-timeout": "^5.0.2"
+    "eventemitter3": "^5.0.4",
+    "@common.js/p-timeout": "^7.0.0"
   },
   "devDependencies": {
-    "@sindresorhus/tsconfig": "^2.0.0",
-    "@types/benchmark": "^2.1.1",
-    "@types/node": "^17.0.13",
-    "ava": "^5.3.1",
+    "@sindresorhus/tsconfig": "^8.0.1",
+    "@types/benchmark": "^2.1.5",
+    "@types/node": "^25.6.0",
     "benchmark": "^2.1.4",
-    "del-cli": "^5.0.0",
-    "delay": "^5.0.0",
+    "del-cli": "^6.0.0",
+    "delay": "^6.0.0",
     "in-range": "^3.0.0",
-    "p-defer": "^4.0.0",
-    "random-int": "^3.0.0",
-    "time-span": "^5.0.0",
-    "ts-node": "^10.9.1",
-    "tsd": "^0.25.0",
-    "typescript": "^5.2.2",
-    "xo": "^0.52.0"
-  },
-  "ava": {
-    "files": [
-      "test/**"
-    ],
-    "extensions": {
-      "ts": "module"
-    },
-    "nodeArguments": [
-      "--loader=ts-node/esm"
-    ]
+    "p-defer": "^4.0.1",
+    "random-int": "^3.1.0",
+    "time-span": "^5.1.0",
+    "tsd": "^0.33.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "xo": "^1.2.2"
   },
   "xo": {
     "rules": {
       "@typescript-eslint/member-ordering": "off",
       "@typescript-eslint/no-floating-promises": "off",
-      "@typescript-eslint/no-invalid-void-type": "off"
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-return": "off",
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/prefer-promise-reject-errors": "off",
+      "ava/no-import-test-files": "off"
     }
   },
   "homepage": "https://github.com/etienne-martin/common.js#readme",