@common.js/p-queue 8.0.1 → 9.3.1

package/dist/options.d.ts

@@ -1,15 +1,26 @@
 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;
+    timeout?: number;
 };
 export type Options<QueueType extends Queue<RunFunction, QueueOptions>, QueueOptions extends QueueAddOptions> = {
     /**
@@ -21,7 +32,7 @@ export type Options<QueueType extends Queue<RunFunction, QueueOptions>, QueueOpt
     */
     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,7 +62,27 @@ export type Options<QueueType extends Queue<RunFunction, QueueOptions>, QueueOpt
 
     @default false
     */
+    readonly carryoverIntervalCount?: boolean;
+    /**
+    @deprecated Renamed to `carryoverIntervalCount`.
+    */
     readonly carryoverConcurrencyCount?: boolean;
+    /**
+    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 = {
     /**
@@ -60,6 +91,10 @@ export type QueueAddOptions = {
     @default 0
     */
     readonly priority?: number;
+    /**
+    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 = {
     /**
@@ -97,6 +132,6 @@ export type TaskOptions = {
     }
     ```
     */
-    readonly signal?: AbortSignal;
+    readonly signal?: AbortSignal | undefined;
 };
 export {};

package/dist/priority-queue.d.ts

@@ -6,6 +6,9 @@ export type PriorityQueueOptions = {
 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

@@ -9,6 +9,14 @@ Object.defineProperty(exports, "default", {
     }
 });
 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");
@@ -20,6 +28,36 @@ function _classApplyDescriptorGet(receiver, descriptor) {
     }
     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");
@@ -39,6 +77,25 @@ 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];
@@ -53,93 +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;
+    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.");
 }
-var _queue = /*#__PURE__*/ new WeakMap();
+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);
+        _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, _queue)[this.size - 1].priority >= options.priority) {
+                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;
                 }
+                // 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, _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, _queue).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, _queue).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, _queue).length;
+                return _classPrivateFieldGet(this, _queue).length - _classPrivateFieldGet(this, _head);
             }
         }
     ]);
     return 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

@@ -4,4 +4,6 @@ export type Queue<Element, Options> = {
     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,6 +1,6 @@
 {
   "name": "@common.js/p-queue",
-  "version": "8.0.1",
+  "version": "9.3.1",
   "description": "p-queue package exported as CommonJS modules",
   "license": "MIT",
   "repository": "etienne-martin/common.js",
@@ -8,11 +8,11 @@
   "type": "commonjs",
   "sideEffects": false,
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "del-cli dist && tsc",
-    "test": "xo && ava && del-cli dist && tsc && tsd",
+    "test": "xo && node --import=tsx/esm --test test/*.ts && del-cli dist && tsc && tsd",
     "bench": "node --import=tsx/esm bench.ts"
   },
   "files": [
@@ -20,43 +20,35 @@
   ],
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "eventemitter3": "^5.0.1",
-    "@common.js/p-timeout": "^6.1.2"
+    "eventemitter3": "^5.0.4",
+    "@common.js/p-timeout": "^7.0.0"
   },
   "devDependencies": {
-    "@sindresorhus/tsconfig": "^5.0.0",
+    "@sindresorhus/tsconfig": "^8.0.1",
     "@types/benchmark": "^2.1.5",
-    "@types/node": "^20.10.4",
-    "ava": "^5.3.1",
+    "@types/node": "^25.6.0",
     "benchmark": "^2.1.4",
-    "del-cli": "^5.1.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",
+    "p-defer": "^4.0.1",
+    "random-int": "^3.1.0",
     "time-span": "^5.1.0",
-    "tsd": "^0.29.0",
-    "tsx": "^4.6.2",
-    "typescript": "^5.3.3",
-    "xo": "^0.56.0"
-  },
-  "ava": {
-    "workerThreads": false,
-    "files": [
-      "test/**"
-    ],
-    "extensions": {
-      "ts": "module"
-    },
-    "nodeArguments": [
-      "--import=tsx/esm"
-    ]
+    "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",