├── .editorconfig ├── .gitattributes ├── .github ├── security.md └── workflows │ └── main.yml ├── .gitignore ├── .npmrc ├── bench.ts ├── license ├── package.json ├── readme.md ├── source ├── index.ts ├── lower-bound.ts ├── options.ts ├── priority-queue.ts └── queue.ts ├── test-d └── index.test-d.ts ├── test └── test.ts └── tsconfig.json /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = tab 5 | end_of_line = lf 6 | charset = utf-8 7 | trim_trailing_whitespace = true 8 | insert_final_newline = true 9 | 10 | [*.yml] 11 | indent_style = space 12 | indent_size = 2 13 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=auto eol=lf 2 | -------------------------------------------------------------------------------- /.github/security.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure. 4 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | on: 3 | - push 4 | - pull_request 5 | jobs: 6 | test: 7 | name: Node.js ${{ matrix.node-version }} 8 | runs-on: ubuntu-latest 9 | strategy: 10 | fail-fast: false 11 | matrix: 12 | node-version: 13 | - 20 14 | - 18 15 | steps: 16 | - uses: actions/checkout@v4 17 | - uses: actions/setup-node@v4 18 | with: 19 | node-version: ${{ matrix.node-version }} 20 | - run: npm install 21 | - run: npm test 22 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | yarn.lock 3 | .nyc_output 4 | dist 5 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | package-lock=false 2 | -------------------------------------------------------------------------------- /bench.ts: -------------------------------------------------------------------------------- 1 | import Benchmark, {type Deferred, type Event} from 'benchmark'; 2 | import PQueue from './source/index.js'; 3 | 4 | const suite = new Benchmark.Suite(); 5 | 6 | // Benchmark typings aren't up to date, let's help out manually 7 | type Resolvable = Deferred & {resolve: () => void}; 8 | 9 | suite 10 | .add('baseline', { 11 | defer: true, 12 | 13 | async fn(deferred: Resolvable) { 14 | const queue = new PQueue(); 15 | 16 | for (let i = 0; i < 100; i++) { 17 | // eslint-disable-next-line @typescript-eslint/no-empty-function 18 | queue.add(async () => {}); 19 | } 20 | 21 | await queue.onEmpty(); 22 | deferred.resolve(); 23 | }, 24 | }) 25 | .add('operation with random priority', { 26 | defer: true, 27 | 28 | async fn(deferred: Resolvable) { 29 | const queue = new PQueue(); 30 | 31 | for (let i = 0; i < 100; i++) { 32 | // eslint-disable-next-line @typescript-eslint/no-empty-function 33 | queue.add(async () => {}, { 34 | priority: Math.trunc(Math.random() * 100), 35 | }); 36 | } 37 | 38 | await queue.onEmpty(); 39 | deferred.resolve(); 40 | }, 41 | }) 42 | .add('operation with increasing priority', { 43 | defer: true, 44 | 45 | async fn(deferred: Resolvable) { 46 | const queue = new PQueue(); 47 | 48 | for (let i = 0; i < 100; i++) { 49 | // eslint-disable-next-line @typescript-eslint/no-empty-function 50 | queue.add(async () => {}, { 51 | priority: i, 52 | }); 53 | } 54 | 55 | await queue.onEmpty(); 56 | deferred.resolve(); 57 | }, 58 | }) 59 | .on('cycle', (event: Event) => { 60 | console.log(String(event.target)); 61 | }) 62 | .on('complete', function () { 63 | // @ts-expect-error benchmark typings incorrect 64 | console.log(`Fastest is ${(this as Benchmark.Suite).filter('fastest').map('name') as string}`); 65 | }) 66 | .run({ 67 | async: true, 68 | }); 69 | -------------------------------------------------------------------------------- /license: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) Sindre Sorhus (https://sindresorhus.com) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 6 | 7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 10 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "p-queue", 3 | "version": "8.1.0", 4 | "description": "Promise queue with concurrency control", 5 | "license": "MIT", 6 | "repository": "sindresorhus/p-queue", 7 | "funding": "https://github.com/sponsors/sindresorhus", 8 | "type": "module", 9 | "exports": { 10 | "types": "./dist/index.d.ts", 11 | "default": "./dist/index.js" 12 | }, 13 | "sideEffects": false, 14 | "engines": { 15 | "node": ">=18" 16 | }, 17 | "scripts": { 18 | "build": "del-cli dist && tsc", 19 | "test": "xo && ava && del-cli dist && tsc && tsd", 20 | "bench": "node --import=tsx/esm bench.ts", 21 | "prepublishOnly": "del-cli dist && tsc" 22 | }, 23 | "files": [ 24 | "dist" 25 | ], 26 | "types": "dist/index.d.ts", 27 | "keywords": [ 28 | "promise", 29 | "queue", 30 | "enqueue", 31 | "limit", 32 | "limited", 33 | "concurrency", 34 | "throttle", 35 | "throat", 36 | "rate", 37 | "batch", 38 | "ratelimit", 39 | "priority", 40 | "priorityqueue", 41 | "fifo", 42 | "job", 43 | "task", 44 | "async", 45 | "await", 46 | "promises", 47 | "bluebird" 48 | ], 49 | "dependencies": { 50 | "eventemitter3": "^5.0.1", 51 | "p-timeout": "^6.1.2" 52 | }, 53 | "devDependencies": { 54 | "@sindresorhus/tsconfig": "^5.0.0", 55 | "@types/benchmark": "^2.1.5", 56 | "@types/node": "^20.10.4", 57 | "ava": "^5.3.1", 58 | "benchmark": "^2.1.4", 59 | "del-cli": "^5.1.0", 60 | "delay": "^6.0.0", 61 | "in-range": "^3.0.0", 62 | "p-defer": "^4.0.0", 63 | "random-int": "^3.0.0", 64 | "time-span": "^5.1.0", 65 | "tsd": "^0.29.0", 66 | "tsx": "^4.6.2", 67 | "typescript": "^5.3.3", 68 | "xo": "^0.56.0" 69 | }, 70 | "ava": { 71 | "workerThreads": false, 72 | "files": [ 73 | "test/**" 74 | ], 75 | "extensions": { 76 | "ts": "module" 77 | }, 78 | "nodeArguments": [ 79 | "--import=tsx/esm" 80 | ] 81 | }, 82 | "xo": { 83 | "rules": { 84 | "@typescript-eslint/member-ordering": "off", 85 | "@typescript-eslint/no-floating-promises": "off", 86 | "@typescript-eslint/no-invalid-void-type": "off" 87 | } 88 | } 89 | } 90 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # p-queue 2 | 3 | > Promise queue with concurrency control 4 | 5 | Useful for rate-limiting async (or sync) operations. For example, when interacting with a REST API or when doing CPU/memory intensive tasks. 6 | 7 | For servers, you probably want a Redis-backed [job queue](https://github.com/sindresorhus/awesome-nodejs#job-queues) instead. 8 | 9 | Note that the project is feature complete. We are happy to review pull requests, but we don't plan any further development. We are also not answering email support questions. 10 | 11 | --- 12 | 13 |
14 |
15 |

16 |

17 | 18 | Sindre's open source work is supported by the community
Special thanks to: 19 | 20 |

21 |
22 |
23 | 24 |
25 | 26 |
27 | Scrape anything with FetchFox 28 |
29 | FetchFox is an AI powered scraping tool that lets you scrape data from any website 30 |
31 | 32 |

33 |
34 |
35 |
36 | 37 | --- 38 | 39 | ## Install 40 | 41 | ```sh 42 | npm install p-queue 43 | ``` 44 | 45 | **Warning:** This package is native [ESM](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and no longer provides a CommonJS export. If your project uses CommonJS, you'll have to [convert to ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). Please don't open issues for questions regarding CommonJS / ESM. 46 | 47 | ## Usage 48 | 49 | Here we run only one promise at the time. For example, set `concurrency` to 4 to run four promises at the same time. 50 | 51 | ```js 52 | import PQueue from 'p-queue'; 53 | import got from 'got'; 54 | 55 | const queue = new PQueue({concurrency: 1}); 56 | 57 | (async () => { 58 | await queue.add(() => got('https://sindresorhus.com')); 59 | console.log('Done: sindresorhus.com'); 60 | })(); 61 | 62 | (async () => { 63 | await queue.add(() => got('https://avajs.dev')); 64 | console.log('Done: avajs.dev'); 65 | })(); 66 | ``` 67 | 68 | ## API 69 | 70 | ### PQueue(options?) 71 | 72 | Returns a new `queue` instance, which is an [`EventEmitter3`](https://github.com/primus/eventemitter3) subclass. 73 | 74 | #### options 75 | 76 | Type: `object` 77 | 78 | ##### concurrency 79 | 80 | Type: `number`\ 81 | Default: `Infinity`\ 82 | Minimum: `1` 83 | 84 | Concurrency limit. 85 | 86 | ##### timeout 87 | 88 | Type: `number` 89 | 90 | Per-operation timeout in milliseconds. Operations fulfill once `timeout` elapses if they haven't already. 91 | 92 | ##### throwOnTimeout 93 | 94 | Type: `boolean`\ 95 | Default: `false` 96 | 97 | Whether or not a timeout is considered an exception. 98 | 99 | ##### autoStart 100 | 101 | Type: `boolean`\ 102 | Default: `true` 103 | 104 | Whether queue tasks within concurrency limit, are auto-executed as soon as they're added. 105 | 106 | ##### queueClass 107 | 108 | Type: `Function` 109 | 110 | Class with a `enqueue` and `dequeue` method, and a `size` getter. See the [Custom QueueClass](#custom-queueclass) section. 111 | 112 | ##### intervalCap 113 | 114 | Type: `number`\ 115 | Default: `Infinity`\ 116 | Minimum: `1` 117 | 118 | The max number of runs in the given interval of time. 119 | 120 | ##### interval 121 | 122 | Type: `number`\ 123 | Default: `0`\ 124 | Minimum: `0` 125 | 126 | The length of time in milliseconds before the interval count resets. Must be finite. 127 | 128 | ##### carryoverConcurrencyCount 129 | 130 | Type: `boolean`\ 131 | Default: `false` 132 | 133 | If `true`, specifies that any [pending](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) Promises, should be carried over into the next interval and counted against the `intervalCap`. If `false`, any of those pending Promises will not count towards the next `intervalCap`. 134 | 135 | ### queue 136 | 137 | `PQueue` instance. 138 | 139 | #### .add(fn, options?) 140 | 141 | Adds a sync or async task to the queue. 142 | 143 | Returns a promise with the return value of `fn`. 144 | 145 | Note: If your items can potentially throw an exception, you must handle those errors from the returned Promise or they may be reported as an unhandled Promise rejection and potentially cause your process to exit immediately. 146 | 147 | ##### fn 148 | 149 | Type: `Function` 150 | 151 | Promise-returning/async function. When executed, it will receive `{signal}` as the first argument. 152 | 153 | #### options 154 | 155 | Type: `object` 156 | 157 | ##### priority 158 | 159 | Type: `number`\ 160 | Default: `0` 161 | 162 | Priority of operation. Operations with greater priority will be scheduled first. 163 | 164 | ##### id 165 | 166 | Type `string` 167 | 168 | 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`. 169 | 170 | ##### signal 171 | 172 | [`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 [error](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/reason). If the operation is already running, the signal will need to be handled by the operation itself. 173 | 174 | ```js 175 | import PQueue from 'p-queue'; 176 | import got, {CancelError} from 'got'; 177 | 178 | const queue = new PQueue(); 179 | 180 | const controller = new AbortController(); 181 | 182 | try { 183 | await queue.add(({signal}) => { 184 | const request = got('https://sindresorhus.com'); 185 | 186 | signal.addEventListener('abort', () => { 187 | request.cancel(); 188 | }); 189 | 190 | try { 191 | return await request; 192 | } catch (error) { 193 | if (!(error instanceof CancelError)) { 194 | throw error; 195 | } 196 | } 197 | }, {signal: controller.signal}); 198 | } catch (error) { 199 | if (!(error instanceof DOMException)) { 200 | throw error; 201 | } 202 | } 203 | ``` 204 | 205 | #### .addAll(fns, options?) 206 | 207 | Same as `.add()`, but accepts an array of sync or async functions and returns a promise that resolves when all functions are resolved. 208 | 209 | #### .pause() 210 | 211 | Put queue execution on hold. 212 | 213 | #### .start() 214 | 215 | Start (or resume) executing enqueued tasks within concurrency limit. No need to call this if queue is not paused (via `options.autoStart = false` or by `.pause()` method.) 216 | 217 | Returns `this` (the instance). 218 | 219 | #### .onEmpty() 220 | 221 | Returns a promise that settles when the queue becomes empty. 222 | 223 | Can be called multiple times. Useful if you for example add additional items at a later time. 224 | 225 | #### .onIdle() 226 | 227 | Returns a promise that settles when the queue becomes empty, and all promises have completed; `queue.size === 0 && queue.pending === 0`. 228 | 229 | The difference with `.onEmpty` is that `.onIdle` guarantees that all work from the queue has finished. `.onEmpty` merely signals that the queue is empty, but it could mean that some promises haven't completed yet. 230 | 231 | #### .onSizeLessThan(limit) 232 | 233 | Returns a promise that settles when the queue size is less than the given limit: `queue.size < limit`. 234 | 235 | If you want to avoid having the queue grow beyond a certain size you can `await queue.onSizeLessThan()` before adding a new item. 236 | 237 | Note that this only limits the number of items waiting to start. There could still be up to `concurrency` jobs already running that this call does not include in its calculation. 238 | 239 | #### .clear() 240 | 241 | Clear the queue. 242 | 243 | #### .size 244 | 245 | Size of the queue, the number of queued items waiting to run. 246 | 247 | #### .sizeBy(options) 248 | 249 | Size of the queue, filtered by the given options. 250 | 251 | For example, this can be used to find the number of items remaining in the queue with a specific priority level. 252 | 253 | ```js 254 | import PQueue from 'p-queue'; 255 | 256 | const queue = new PQueue(); 257 | 258 | queue.add(async () => '🦄', {priority: 1}); 259 | queue.add(async () => '🦄', {priority: 0}); 260 | queue.add(async () => '🦄', {priority: 1}); 261 | 262 | console.log(queue.sizeBy({priority: 1})); 263 | //=> 2 264 | 265 | console.log(queue.sizeBy({priority: 0})); 266 | //=> 1 267 | ``` 268 | 269 | #### .setPriority(id, priority) 270 | 271 | Updates the priority of a promise function by its id, affecting its execution order. Requires a defined concurrency limit to take effect. 272 | 273 | For example, this can be used to prioritize a promise function to run earlier. 274 | 275 | ```js 276 | import PQueue from 'p-queue'; 277 | 278 | const queue = new PQueue({concurrency: 1}); 279 | 280 | queue.add(async () => '🦄', {priority: 1}); 281 | queue.add(async () => '🦀', {priority: 0, id: '🦀'}); 282 | queue.add(async () => '🦄', {priority: 1}); 283 | queue.add(async () => '🦄', {priority: 1}); 284 | 285 | queue.setPriority('🦀', 2); 286 | ``` 287 | 288 | In this case, the promise function with `id: '🦀'` runs second. 289 | 290 | You can also deprioritize a promise function to delay its execution: 291 | 292 | ```js 293 | import PQueue from 'p-queue'; 294 | 295 | const queue = new PQueue({concurrency: 1}); 296 | 297 | queue.add(async () => '🦄', {priority: 1}); 298 | queue.add(async () => '🦀', {priority: 1, id: '🦀'}); 299 | queue.add(async () => '🦄'); 300 | queue.add(async () => '🦄', {priority: 0}); 301 | 302 | queue.setPriority('🦀', -1); 303 | ``` 304 | 305 | Here, the promise function with `id: '🦀'` executes last. 306 | 307 | #### .pending 308 | 309 | Number of running items (no longer in the queue). 310 | 311 | #### [.timeout](#timeout) 312 | 313 | #### [.concurrency](#concurrency) 314 | 315 | #### .isPaused 316 | 317 | Whether the queue is currently paused. 318 | 319 | ## Events 320 | 321 | #### active 322 | 323 | Emitted as each item is processed in the queue for the purpose of tracking progress. 324 | 325 | ```js 326 | import delay from 'delay'; 327 | import PQueue from 'p-queue'; 328 | 329 | const queue = new PQueue({concurrency: 2}); 330 | 331 | let count = 0; 332 | queue.on('active', () => { 333 | console.log(`Working on item #${++count}. Size: ${queue.size} Pending: ${queue.pending}`); 334 | }); 335 | 336 | queue.add(() => Promise.resolve()); 337 | queue.add(() => delay(2000)); 338 | queue.add(() => Promise.resolve()); 339 | queue.add(() => Promise.resolve()); 340 | queue.add(() => delay(500)); 341 | ``` 342 | 343 | #### completed 344 | 345 | Emitted when an item completes without error. 346 | 347 | ```js 348 | import delay from 'delay'; 349 | import PQueue from 'p-queue'; 350 | 351 | const queue = new PQueue({concurrency: 2}); 352 | 353 | queue.on('completed', result => { 354 | console.log(result); 355 | }); 356 | 357 | queue.add(() => Promise.resolve('hello, world!')); 358 | ``` 359 | 360 | #### error 361 | 362 | Emitted if an item throws an error. 363 | 364 | ```js 365 | import delay from 'delay'; 366 | import PQueue from 'p-queue'; 367 | 368 | const queue = new PQueue({concurrency: 2}); 369 | 370 | queue.on('error', error => { 371 | console.error(error); 372 | }); 373 | 374 | queue.add(() => Promise.reject(new Error('error'))); 375 | ``` 376 | 377 | #### empty 378 | 379 | Emitted every time the queue becomes empty. 380 | 381 | Useful if you for example add additional items at a later time. 382 | 383 | #### idle 384 | 385 | Emitted every time the queue becomes empty and all promises have completed; `queue.size === 0 && queue.pending === 0`. 386 | 387 | The difference with `empty` is that `idle` guarantees that all work from the queue has finished. `empty` merely signals that the queue is empty, but it could mean that some promises haven't completed yet. 388 | 389 | ```js 390 | import delay from 'delay'; 391 | import PQueue from 'p-queue'; 392 | 393 | const queue = new PQueue(); 394 | 395 | queue.on('idle', () => { 396 | console.log(`Queue is idle. Size: ${queue.size} Pending: ${queue.pending}`); 397 | }); 398 | 399 | const job1 = queue.add(() => delay(2000)); 400 | const job2 = queue.add(() => delay(500)); 401 | 402 | await job1; 403 | await job2; 404 | // => 'Queue is idle. Size: 0 Pending: 0' 405 | 406 | await queue.add(() => delay(600)); 407 | // => 'Queue is idle. Size: 0 Pending: 0' 408 | ``` 409 | 410 | The `idle` event is emitted every time the queue reaches an idle state. On the other hand, the promise the `onIdle()` function returns resolves once the queue becomes idle instead of every time the queue is idle. 411 | 412 | #### add 413 | 414 | Emitted every time the add method is called and the number of pending or queued tasks is increased. 415 | 416 | #### next 417 | 418 | Emitted every time a task is completed and the number of pending or queued tasks is decreased. This is emitted regardless of whether the task completed normally or with an error. 419 | 420 | ```js 421 | import delay from 'delay'; 422 | import PQueue from 'p-queue'; 423 | 424 | const queue = new PQueue(); 425 | 426 | queue.on('add', () => { 427 | console.log(`Task is added. Size: ${queue.size} Pending: ${queue.pending}`); 428 | }); 429 | 430 | queue.on('next', () => { 431 | console.log(`Task is completed. Size: ${queue.size} Pending: ${queue.pending}`); 432 | }); 433 | 434 | const job1 = queue.add(() => delay(2000)); 435 | const job2 = queue.add(() => delay(500)); 436 | 437 | await job1; 438 | await job2; 439 | //=> 'Task is added. Size: 0 Pending: 1' 440 | //=> 'Task is added. Size: 0 Pending: 2' 441 | 442 | await queue.add(() => delay(600)); 443 | //=> 'Task is completed. Size: 0 Pending: 1' 444 | //=> 'Task is completed. Size: 0 Pending: 0' 445 | ``` 446 | 447 | ## Advanced example 448 | 449 | A more advanced example to help you understand the flow. 450 | 451 | ```js 452 | import delay from 'delay'; 453 | import PQueue from 'p-queue'; 454 | 455 | const queue = new PQueue({concurrency: 1}); 456 | 457 | (async () => { 458 | await delay(200); 459 | 460 | console.log(`8. Pending promises: ${queue.pending}`); 461 | //=> '8. Pending promises: 0' 462 | 463 | (async () => { 464 | await queue.add(async () => '🐙'); 465 | console.log('11. Resolved') 466 | })(); 467 | 468 | console.log('9. Added 🐙'); 469 | 470 | console.log(`10. Pending promises: ${queue.pending}`); 471 | //=> '10. Pending promises: 1' 472 | 473 | await queue.onIdle(); 474 | console.log('12. All work is done'); 475 | })(); 476 | 477 | (async () => { 478 | await queue.add(async () => '🦄'); 479 | console.log('5. Resolved') 480 | })(); 481 | console.log('1. Added 🦄'); 482 | 483 | (async () => { 484 | await queue.add(async () => '🐴'); 485 | console.log('6. Resolved') 486 | })(); 487 | console.log('2. Added 🐴'); 488 | 489 | (async () => { 490 | await queue.onEmpty(); 491 | console.log('7. Queue is empty'); 492 | })(); 493 | 494 | console.log(`3. Queue size: ${queue.size}`); 495 | //=> '3. Queue size: 1` 496 | 497 | console.log(`4. Pending promises: ${queue.pending}`); 498 | //=> '4. Pending promises: 1' 499 | ``` 500 | 501 | ``` 502 | $ node example.js 503 | 1. Added 🦄 504 | 2. Added 🐴 505 | 3. Queue size: 1 506 | 4. Pending promises: 1 507 | 5. Resolved 🦄 508 | 6. Resolved 🐴 509 | 7. Queue is empty 510 | 8. Pending promises: 0 511 | 9. Added 🐙 512 | 10. Pending promises: 1 513 | 11. Resolved 🐙 514 | 12. All work is done 515 | ``` 516 | 517 | ## Custom QueueClass 518 | 519 | For implementing more complex scheduling policies, you can provide a QueueClass in the options: 520 | 521 | ```js 522 | import PQueue from 'p-queue'; 523 | 524 | class QueueClass { 525 | constructor() { 526 | this._queue = []; 527 | } 528 | 529 | enqueue(run, options) { 530 | this._queue.push(run); 531 | } 532 | 533 | dequeue() { 534 | return this._queue.shift(); 535 | } 536 | 537 | get size() { 538 | return this._queue.length; 539 | } 540 | 541 | filter(options) { 542 | return this._queue; 543 | } 544 | } 545 | 546 | const queue = new PQueue({queueClass: QueueClass}); 547 | ``` 548 | 549 | `p-queue` will call corresponding methods to put and get operations from this queue. 550 | 551 | ## FAQ 552 | 553 | #### How do the `concurrency` and `intervalCap` options affect each other? 554 | 555 | They are just different constraints. The `concurrency` option limits how many things run at the same time. The `intervalCap` option limits how many things run in total during the interval (over time). 556 | 557 | ## Maintainers 558 | 559 | - [Sindre Sorhus](https://github.com/sindresorhus) 560 | - [Richie Bendall](https://github.com/Richienb) 561 | 562 | ## Related 563 | 564 | - [p-limit](https://github.com/sindresorhus/p-limit) - Run multiple promise-returning & async functions with limited concurrency 565 | - [p-throttle](https://github.com/sindresorhus/p-throttle) - Throttle promise-returning & async functions 566 | - [p-debounce](https://github.com/sindresorhus/p-debounce) - Debounce promise-returning & async functions 567 | - [p-all](https://github.com/sindresorhus/p-all) - Run promise-returning & async functions concurrently with optional limited concurrency 568 | - [More…](https://github.com/sindresorhus/promise-fun) 569 | -------------------------------------------------------------------------------- /source/index.ts: -------------------------------------------------------------------------------- 1 | import {EventEmitter} from 'eventemitter3'; 2 | import pTimeout, {TimeoutError} from 'p-timeout'; 3 | import {type Queue, type RunFunction} from './queue.js'; 4 | import PriorityQueue from './priority-queue.js'; 5 | import {type QueueAddOptions, type Options, type TaskOptions} from './options.js'; 6 | 7 | type Task = 8 | | ((options: TaskOptions) => PromiseLike) 9 | | ((options: TaskOptions) => TaskResultType); 10 | 11 | type EventName = 'active' | 'idle' | 'empty' | 'add' | 'next' | 'completed' | 'error'; 12 | 13 | /** 14 | Promise queue with concurrency control. 15 | */ 16 | export default class PQueue = PriorityQueue, EnqueueOptionsType extends QueueAddOptions = QueueAddOptions> extends EventEmitter { // eslint-disable-line @typescript-eslint/naming-convention, unicorn/prefer-event-target 17 | readonly #carryoverConcurrencyCount: boolean; 18 | 19 | readonly #isIntervalIgnored: boolean; 20 | 21 | #intervalCount = 0; 22 | 23 | readonly #intervalCap: number; 24 | 25 | readonly #interval: number; 26 | 27 | #intervalEnd = 0; 28 | 29 | #intervalId?: NodeJS.Timeout; 30 | 31 | #timeoutId?: NodeJS.Timeout; 32 | 33 | #queue: QueueType; 34 | 35 | readonly #queueClass: new () => QueueType; 36 | 37 | #pending = 0; 38 | 39 | // The `!` is needed because of https://github.com/microsoft/TypeScript/issues/32194 40 | #concurrency!: number; 41 | 42 | #isPaused: boolean; 43 | 44 | readonly #throwOnTimeout: boolean; 45 | 46 | // Use to assign a unique identifier to a promise function, if not explicitly specified 47 | #idAssigner = 1n; 48 | 49 | /** 50 | Per-operation timeout in milliseconds. Operations fulfill once `timeout` elapses if they haven't already. 51 | 52 | Applies to each future operation. 53 | */ 54 | timeout?: number; 55 | 56 | // TODO: The `throwOnTimeout` option should affect the return types of `add()` and `addAll()` 57 | constructor(options?: Options) { 58 | super(); 59 | 60 | // eslint-disable-next-line @typescript-eslint/consistent-type-assertions 61 | options = { 62 | carryoverConcurrencyCount: false, 63 | intervalCap: Number.POSITIVE_INFINITY, 64 | interval: 0, 65 | concurrency: Number.POSITIVE_INFINITY, 66 | autoStart: true, 67 | queueClass: PriorityQueue, 68 | ...options, 69 | } as Options; 70 | 71 | if (!(typeof options.intervalCap === 'number' && options.intervalCap >= 1)) { 72 | throw new TypeError(`Expected \`intervalCap\` to be a number from 1 and up, got \`${options.intervalCap?.toString() ?? ''}\` (${typeof options.intervalCap})`); 73 | } 74 | 75 | if (options.interval === undefined || !(Number.isFinite(options.interval) && options.interval >= 0)) { 76 | throw new TypeError(`Expected \`interval\` to be a finite number >= 0, got \`${options.interval?.toString() ?? ''}\` (${typeof options.interval})`); 77 | } 78 | 79 | this.#carryoverConcurrencyCount = options.carryoverConcurrencyCount!; 80 | this.#isIntervalIgnored = options.intervalCap === Number.POSITIVE_INFINITY || options.interval === 0; 81 | this.#intervalCap = options.intervalCap; 82 | this.#interval = options.interval; 83 | this.#queue = new options.queueClass!(); 84 | this.#queueClass = options.queueClass!; 85 | this.concurrency = options.concurrency!; 86 | this.timeout = options.timeout; 87 | this.#throwOnTimeout = options.throwOnTimeout === true; 88 | this.#isPaused = options.autoStart === false; 89 | } 90 | 91 | get #doesIntervalAllowAnother(): boolean { 92 | return this.#isIntervalIgnored || this.#intervalCount < this.#intervalCap; 93 | } 94 | 95 | get #doesConcurrentAllowAnother(): boolean { 96 | return this.#pending < this.#concurrency; 97 | } 98 | 99 | #next(): void { 100 | this.#pending--; 101 | this.#tryToStartAnother(); 102 | this.emit('next'); 103 | } 104 | 105 | #onResumeInterval(): void { 106 | this.#onInterval(); 107 | this.#initializeIntervalIfNeeded(); 108 | this.#timeoutId = undefined; 109 | } 110 | 111 | get #isIntervalPaused(): boolean { 112 | const now = Date.now(); 113 | 114 | if (this.#intervalId === undefined) { 115 | const delay = this.#intervalEnd - now; 116 | if (delay < 0) { 117 | // Act as the interval was done 118 | // We don't need to resume it here because it will be resumed on line 160 119 | this.#intervalCount = (this.#carryoverConcurrencyCount) ? this.#pending : 0; 120 | } else { 121 | // Act as the interval is pending 122 | if (this.#timeoutId === undefined) { 123 | this.#timeoutId = setTimeout( 124 | () => { 125 | this.#onResumeInterval(); 126 | }, 127 | delay, 128 | ); 129 | } 130 | 131 | return true; 132 | } 133 | } 134 | 135 | return false; 136 | } 137 | 138 | #tryToStartAnother(): boolean { 139 | if (this.#queue.size === 0) { 140 | // We can clear the interval ("pause") 141 | // Because we can redo it later ("resume") 142 | if (this.#intervalId) { 143 | clearInterval(this.#intervalId); 144 | } 145 | 146 | this.#intervalId = undefined; 147 | 148 | this.emit('empty'); 149 | 150 | if (this.#pending === 0) { 151 | this.emit('idle'); 152 | } 153 | 154 | return false; 155 | } 156 | 157 | if (!this.#isPaused) { 158 | const canInitializeInterval = !this.#isIntervalPaused; 159 | if (this.#doesIntervalAllowAnother && this.#doesConcurrentAllowAnother) { 160 | const job = this.#queue.dequeue(); 161 | if (!job) { 162 | return false; 163 | } 164 | 165 | this.emit('active'); 166 | job(); 167 | 168 | if (canInitializeInterval) { 169 | this.#initializeIntervalIfNeeded(); 170 | } 171 | 172 | return true; 173 | } 174 | } 175 | 176 | return false; 177 | } 178 | 179 | #initializeIntervalIfNeeded(): void { 180 | if (this.#isIntervalIgnored || this.#intervalId !== undefined) { 181 | return; 182 | } 183 | 184 | this.#intervalId = setInterval( 185 | () => { 186 | this.#onInterval(); 187 | }, 188 | this.#interval, 189 | ); 190 | 191 | this.#intervalEnd = Date.now() + this.#interval; 192 | } 193 | 194 | #onInterval(): void { 195 | if (this.#intervalCount === 0 && this.#pending === 0 && this.#intervalId) { 196 | clearInterval(this.#intervalId); 197 | this.#intervalId = undefined; 198 | } 199 | 200 | this.#intervalCount = this.#carryoverConcurrencyCount ? this.#pending : 0; 201 | this.#processQueue(); 202 | } 203 | 204 | /** 205 | Executes all queued functions until it reaches the limit. 206 | */ 207 | #processQueue(): void { 208 | // eslint-disable-next-line no-empty 209 | while (this.#tryToStartAnother()) {} 210 | } 211 | 212 | get concurrency(): number { 213 | return this.#concurrency; 214 | } 215 | 216 | set concurrency(newConcurrency: number) { 217 | if (!(typeof newConcurrency === 'number' && newConcurrency >= 1)) { 218 | throw new TypeError(`Expected \`concurrency\` to be a number from 1 and up, got \`${newConcurrency}\` (${typeof newConcurrency})`); 219 | } 220 | 221 | this.#concurrency = newConcurrency; 222 | 223 | this.#processQueue(); 224 | } 225 | 226 | async #throwOnAbort(signal: AbortSignal): Promise { 227 | return new Promise((_resolve, reject) => { 228 | signal.addEventListener('abort', () => { 229 | reject(signal.reason); 230 | }, {once: true}); 231 | }); 232 | } 233 | 234 | /** 235 | Updates the priority of a promise function by its id, affecting its execution order. Requires a defined concurrency limit to take effect. 236 | 237 | For example, this can be used to prioritize a promise function to run earlier. 238 | 239 | ```js 240 | import PQueue from 'p-queue'; 241 | 242 | const queue = new PQueue({concurrency: 1}); 243 | 244 | queue.add(async () => '🦄', {priority: 1}); 245 | queue.add(async () => '🦀', {priority: 0, id: '🦀'}); 246 | queue.add(async () => '🦄', {priority: 1}); 247 | queue.add(async () => '🦄', {priority: 1}); 248 | 249 | queue.setPriority('🦀', 2); 250 | ``` 251 | 252 | In this case, the promise function with `id: '🦀'` runs second. 253 | 254 | You can also deprioritize a promise function to delay its execution: 255 | 256 | ```js 257 | import PQueue from 'p-queue'; 258 | 259 | const queue = new PQueue({concurrency: 1}); 260 | 261 | queue.add(async () => '🦄', {priority: 1}); 262 | queue.add(async () => '🦀', {priority: 1, id: '🦀'}); 263 | queue.add(async () => '🦄'); 264 | queue.add(async () => '🦄', {priority: 0}); 265 | 266 | queue.setPriority('🦀', -1); 267 | ``` 268 | Here, the promise function with `id: '🦀'` executes last. 269 | */ 270 | setPriority(id: string, priority: number) { 271 | this.#queue.setPriority(id, priority); 272 | } 273 | 274 | /** 275 | Adds a sync or async task to the queue. Always returns a promise. 276 | */ 277 | async add(function_: Task, options: {throwOnTimeout: true} & Exclude): Promise; 278 | async add(function_: Task, options?: Partial): Promise; 279 | async add(function_: Task, options: Partial = {}): Promise { 280 | // In case `id` is not defined. 281 | options.id ??= (this.#idAssigner++).toString(); 282 | 283 | options = { 284 | timeout: this.timeout, 285 | throwOnTimeout: this.#throwOnTimeout, 286 | ...options, 287 | }; 288 | 289 | return new Promise((resolve, reject) => { 290 | this.#queue.enqueue(async () => { 291 | this.#pending++; 292 | this.#intervalCount++; 293 | 294 | try { 295 | options.signal?.throwIfAborted(); 296 | 297 | let operation = function_({signal: options.signal}); 298 | 299 | if (options.timeout) { 300 | operation = pTimeout(Promise.resolve(operation), {milliseconds: options.timeout}); 301 | } 302 | 303 | if (options.signal) { 304 | operation = Promise.race([operation, this.#throwOnAbort(options.signal)]); 305 | } 306 | 307 | const result = await operation; 308 | resolve(result); 309 | this.emit('completed', result); 310 | } catch (error: unknown) { 311 | if (error instanceof TimeoutError && !options.throwOnTimeout) { 312 | resolve(); 313 | return; 314 | } 315 | 316 | reject(error); 317 | this.emit('error', error); 318 | } finally { 319 | this.#next(); 320 | } 321 | }, options); 322 | 323 | this.emit('add'); 324 | 325 | this.#tryToStartAnother(); 326 | }); 327 | } 328 | 329 | /** 330 | Same as `.add()`, but accepts an array of sync or async functions. 331 | 332 | @returns A promise that resolves when all functions are resolved. 333 | */ 334 | async addAll( 335 | functions: ReadonlyArray>, 336 | options?: {throwOnTimeout: true} & Partial>, 337 | ): Promise; 338 | async addAll( 339 | functions: ReadonlyArray>, 340 | options?: Partial, 341 | ): Promise>; 342 | async addAll( 343 | functions: ReadonlyArray>, 344 | options?: Partial, 345 | ): Promise> { 346 | return Promise.all(functions.map(async function_ => this.add(function_, options))); 347 | } 348 | 349 | /** 350 | Start (or resume) executing enqueued tasks within concurrency limit. No need to call this if queue is not paused (via `options.autoStart = false` or by `.pause()` method.) 351 | */ 352 | start(): this { 353 | if (!this.#isPaused) { 354 | return this; 355 | } 356 | 357 | this.#isPaused = false; 358 | 359 | this.#processQueue(); 360 | return this; 361 | } 362 | 363 | /** 364 | Put queue execution on hold. 365 | */ 366 | pause(): void { 367 | this.#isPaused = true; 368 | } 369 | 370 | /** 371 | Clear the queue. 372 | */ 373 | clear(): void { 374 | this.#queue = new this.#queueClass(); 375 | } 376 | 377 | /** 378 | Can be called multiple times. Useful if you for example add additional items at a later time. 379 | 380 | @returns A promise that settles when the queue becomes empty. 381 | */ 382 | async onEmpty(): Promise { 383 | // Instantly resolve if the queue is empty 384 | if (this.#queue.size === 0) { 385 | return; 386 | } 387 | 388 | await this.#onEvent('empty'); 389 | } 390 | 391 | /** 392 | @returns A promise that settles when the queue size is less than the given limit: `queue.size < limit`. 393 | 394 | If you want to avoid having the queue grow beyond a certain size you can `await queue.onSizeLessThan()` before adding a new item. 395 | 396 | Note that this only limits the number of items waiting to start. There could still be up to `concurrency` jobs already running that this call does not include in its calculation. 397 | */ 398 | async onSizeLessThan(limit: number): Promise { 399 | // Instantly resolve if the queue is empty. 400 | if (this.#queue.size < limit) { 401 | return; 402 | } 403 | 404 | await this.#onEvent('next', () => this.#queue.size < limit); 405 | } 406 | 407 | /** 408 | The difference with `.onEmpty` is that `.onIdle` guarantees that all work from the queue has finished. `.onEmpty` merely signals that the queue is empty, but it could mean that some promises haven't completed yet. 409 | 410 | @returns A promise that settles when the queue becomes empty, and all promises have completed; `queue.size === 0 && queue.pending === 0`. 411 | */ 412 | async onIdle(): Promise { 413 | // Instantly resolve if none pending and if nothing else is queued 414 | if (this.#pending === 0 && this.#queue.size === 0) { 415 | return; 416 | } 417 | 418 | await this.#onEvent('idle'); 419 | } 420 | 421 | async #onEvent(event: EventName, filter?: () => boolean): Promise { 422 | return new Promise(resolve => { 423 | const listener = () => { 424 | if (filter && !filter()) { 425 | return; 426 | } 427 | 428 | this.off(event, listener); 429 | resolve(); 430 | }; 431 | 432 | this.on(event, listener); 433 | }); 434 | } 435 | 436 | /** 437 | Size of the queue, the number of queued items waiting to run. 438 | */ 439 | get size(): number { 440 | return this.#queue.size; 441 | } 442 | 443 | /** 444 | Size of the queue, filtered by the given options. 445 | 446 | For example, this can be used to find the number of items remaining in the queue with a specific priority level. 447 | */ 448 | sizeBy(options: Readonly>): number { 449 | // eslint-disable-next-line unicorn/no-array-callback-reference 450 | return this.#queue.filter(options).length; 451 | } 452 | 453 | /** 454 | Number of running items (no longer in the queue). 455 | */ 456 | get pending(): number { 457 | return this.#pending; 458 | } 459 | 460 | /** 461 | Whether the queue is currently paused. 462 | */ 463 | get isPaused(): boolean { 464 | return this.#isPaused; 465 | } 466 | } 467 | 468 | export type {Queue} from './queue.js'; 469 | export {type QueueAddOptions, type Options} from './options.js'; 470 | -------------------------------------------------------------------------------- /source/lower-bound.ts: -------------------------------------------------------------------------------- 1 | // Port of lower_bound from https://en.cppreference.com/w/cpp/algorithm/lower_bound 2 | // Used to compute insertion index to keep queue sorted after insertion 3 | export default function lowerBound(array: readonly T[], value: T, comparator: (a: T, b: T) => number): number { 4 | let first = 0; 5 | let count = array.length; 6 | 7 | while (count > 0) { 8 | const step = Math.trunc(count / 2); 9 | let it = first + step; 10 | 11 | if (comparator(array[it]!, value) <= 0) { 12 | first = ++it; 13 | count -= step + 1; 14 | } else { 15 | count = step; 16 | } 17 | } 18 | 19 | return first; 20 | } 21 | -------------------------------------------------------------------------------- /source/options.ts: -------------------------------------------------------------------------------- 1 | import {type Queue, type RunFunction} from './queue.js'; 2 | 3 | type TimeoutOptions = { 4 | /** 5 | Per-operation timeout in milliseconds. Operations fulfill once `timeout` elapses if they haven't already. 6 | */ 7 | timeout?: number; 8 | 9 | /** 10 | Whether or not a timeout is considered an exception. 11 | 12 | @default false 13 | */ 14 | throwOnTimeout?: boolean; 15 | }; 16 | 17 | export type Options, QueueOptions extends QueueAddOptions> = { 18 | /** 19 | Concurrency limit. 20 | 21 | Minimum: `1`. 22 | 23 | @default Infinity 24 | */ 25 | readonly concurrency?: number; 26 | 27 | /** 28 | Whether queue tasks within concurrency limit, are auto-executed as soon as they're added. 29 | 30 | @default true 31 | */ 32 | readonly autoStart?: boolean; 33 | 34 | /** 35 | Class with a `enqueue` and `dequeue` method, and a `size` getter. See the [Custom QueueClass](https://github.com/sindresorhus/p-queue#custom-queueclass) section. 36 | */ 37 | readonly queueClass?: new () => QueueType; 38 | 39 | /** 40 | The max number of runs in the given interval of time. 41 | 42 | Minimum: `1`. 43 | 44 | @default Infinity 45 | */ 46 | readonly intervalCap?: number; 47 | 48 | /** 49 | The length of time in milliseconds before the interval count resets. Must be finite. 50 | 51 | Minimum: `0`. 52 | 53 | @default 0 54 | */ 55 | readonly interval?: number; 56 | 57 | /** 58 | Whether the task must finish in the given interval or will be carried over into the next interval count. 59 | 60 | @default false 61 | */ 62 | readonly carryoverConcurrencyCount?: boolean; 63 | } & TimeoutOptions; 64 | 65 | export type QueueAddOptions = { 66 | /** 67 | Priority of operation. Operations with greater priority will be scheduled first. 68 | 69 | @default 0 70 | */ 71 | readonly priority?: number; 72 | 73 | /** 74 | 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`. 75 | */ 76 | id?: string; 77 | } & TaskOptions & TimeoutOptions; 78 | 79 | export type TaskOptions = { 80 | /** 81 | [`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. 82 | 83 | @example 84 | ``` 85 | import PQueue, {AbortError} from 'p-queue'; 86 | import got, {CancelError} from 'got'; 87 | 88 | const queue = new PQueue(); 89 | 90 | const controller = new AbortController(); 91 | 92 | try { 93 | await queue.add(({signal}) => { 94 | const request = got('https://sindresorhus.com'); 95 | 96 | signal.addEventListener('abort', () => { 97 | request.cancel(); 98 | }); 99 | 100 | try { 101 | return await request; 102 | } catch (error) { 103 | if (!(error instanceof CancelError)) { 104 | throw error; 105 | } 106 | } 107 | }, {signal: controller.signal}); 108 | } catch (error) { 109 | if (!(error instanceof AbortError)) { 110 | throw error; 111 | } 112 | } 113 | ``` 114 | */ 115 | readonly signal?: AbortSignal; 116 | }; 117 | -------------------------------------------------------------------------------- /source/priority-queue.ts: -------------------------------------------------------------------------------- 1 | import {type Queue, type RunFunction} from './queue.js'; 2 | import lowerBound from './lower-bound.js'; 3 | import {type QueueAddOptions} from './options.js'; 4 | 5 | export type PriorityQueueOptions = { 6 | priority?: number; 7 | } & QueueAddOptions; 8 | 9 | export default class PriorityQueue implements Queue { 10 | readonly #queue: Array = []; 11 | 12 | enqueue(run: RunFunction, options?: Partial): void { 13 | options = { 14 | priority: 0, 15 | ...options, 16 | }; 17 | 18 | const element = { 19 | priority: options.priority, 20 | id: options.id, 21 | run, 22 | }; 23 | 24 | if (this.size === 0 || this.#queue[this.size - 1]!.priority! >= options.priority!) { 25 | this.#queue.push(element); 26 | return; 27 | } 28 | 29 | const index = lowerBound( 30 | this.#queue, element, 31 | (a: Readonly, b: Readonly) => b.priority! - a.priority!, 32 | ); 33 | this.#queue.splice(index, 0, element); 34 | } 35 | 36 | setPriority(id: string, priority: number) { 37 | const index: number = this.#queue.findIndex((element: Readonly) => element.id === id); 38 | if (index === -1) { 39 | throw new ReferenceError(`No promise function with the id "${id}" exists in the queue.`); 40 | } 41 | 42 | const [item] = this.#queue.splice(index, 1); 43 | this.enqueue(item!.run, {priority, id}); 44 | } 45 | 46 | dequeue(): RunFunction | undefined { 47 | const item = this.#queue.shift(); 48 | return item?.run; 49 | } 50 | 51 | filter(options: Readonly>): RunFunction[] { 52 | return this.#queue.filter( 53 | (element: Readonly) => element.priority === options.priority, 54 | ).map((element: Readonly<{run: RunFunction}>) => element.run); 55 | } 56 | 57 | get size(): number { 58 | return this.#queue.length; 59 | } 60 | } 61 | -------------------------------------------------------------------------------- /source/queue.ts: -------------------------------------------------------------------------------- 1 | export type RunFunction = () => Promise; 2 | 3 | export type Queue = { 4 | size: number; 5 | filter: (options: Readonly>) => Element[]; 6 | dequeue: () => Element | undefined; 7 | enqueue: (run: Element, options?: Partial) => void; 8 | setPriority: (id: string, priority: number) => void; 9 | }; 10 | -------------------------------------------------------------------------------- /test-d/index.test-d.ts: -------------------------------------------------------------------------------- 1 | import {expectType} from 'tsd'; 2 | import PQueue from '../source/index.js'; 3 | 4 | const queue = new PQueue(); 5 | 6 | expectType>(queue.add(async () => '🦄')); 7 | expectType>(queue.add(async () => '🦄', {throwOnTimeout: true})); 8 | -------------------------------------------------------------------------------- /test/test.ts: -------------------------------------------------------------------------------- 1 | /* eslint-disable no-new */ 2 | import EventEmitter from 'eventemitter3'; 3 | import test from 'ava'; 4 | import delay from 'delay'; 5 | import inRange from 'in-range'; 6 | import timeSpan from 'time-span'; 7 | import randomInt from 'random-int'; 8 | import pDefer from 'p-defer'; 9 | import PQueue from '../source/index.js'; 10 | 11 | const fixture = Symbol('fixture'); 12 | 13 | test('.add()', async t => { 14 | const queue = new PQueue(); 15 | const promise = queue.add(async () => fixture); 16 | t.is(queue.size, 0); 17 | t.is(queue.pending, 1); 18 | t.is(await promise, fixture); 19 | }); 20 | 21 | test('.add() - limited concurrency', async t => { 22 | const queue = new PQueue({concurrency: 2}); 23 | const promise = queue.add(async () => fixture); 24 | const promise2 = queue.add(async () => { 25 | await delay(100); 26 | return fixture; 27 | }); 28 | const promise3 = queue.add(async () => fixture); 29 | t.is(queue.size, 1); 30 | t.is(queue.pending, 2); 31 | t.is(await promise, fixture); 32 | t.is(await promise2, fixture); 33 | t.is(await promise3, fixture); 34 | }); 35 | 36 | test('.add() - concurrency: 1', async t => { 37 | const input = [ 38 | [10, 300], 39 | [20, 200], 40 | [30, 100], 41 | ]; 42 | 43 | const end = timeSpan(); 44 | const queue = new PQueue({concurrency: 1}); 45 | 46 | const mapper = async ([value, ms]: readonly number[]) => queue.add(async () => { 47 | await delay(ms!); 48 | return value!; 49 | }); 50 | 51 | // eslint-disable-next-line unicorn/no-array-callback-reference 52 | t.deepEqual(await Promise.all(input.map(mapper)), [10, 20, 30]); 53 | t.true(inRange(end(), {start: 590, end: 650})); 54 | }); 55 | 56 | test('.add() - concurrency: 5', async t => { 57 | const concurrency = 5; 58 | const queue = new PQueue({concurrency}); 59 | let running = 0; 60 | 61 | const input = Array.from({length: 100}).fill(0).map(async () => queue.add(async () => { 62 | running++; 63 | t.true(running <= concurrency); 64 | t.true(queue.pending <= concurrency); 65 | await delay(randomInt(30, 200)); 66 | running--; 67 | })); 68 | 69 | await Promise.all(input); 70 | }); 71 | 72 | test('.add() - update concurrency', async t => { 73 | let concurrency = 5; 74 | const queue = new PQueue({concurrency}); 75 | let running = 0; 76 | 77 | const input = Array.from({length: 100}).fill(0).map(async (_value, index) => queue.add(async () => { 78 | running++; 79 | 80 | t.true(running <= concurrency); 81 | t.true(queue.pending <= concurrency); 82 | 83 | await delay(randomInt(30, 200)); 84 | running--; 85 | 86 | if (index % 30 === 0) { 87 | queue.concurrency = --concurrency; 88 | t.is(queue.concurrency, concurrency); 89 | } 90 | })); 91 | 92 | await Promise.all(input); 93 | }); 94 | 95 | test('.add() - priority', async t => { 96 | const result: number[] = []; 97 | const queue = new PQueue({concurrency: 1}); 98 | queue.add(async () => result.push(1), {priority: 1}); 99 | queue.add(async () => result.push(0), {priority: 0}); 100 | queue.add(async () => result.push(1), {priority: 1}); 101 | queue.add(async () => result.push(2), {priority: 1}); 102 | queue.add(async () => result.push(3), {priority: 2}); 103 | queue.add(async () => result.push(0), {priority: -1}); 104 | await queue.onEmpty(); 105 | t.deepEqual(result, [1, 3, 1, 2, 0, 0]); 106 | }); 107 | 108 | test('.sizeBy() - priority', async t => { 109 | const queue = new PQueue(); 110 | queue.pause(); 111 | queue.add(async () => 0, {priority: 1}); 112 | queue.add(async () => 0, {priority: 0}); 113 | queue.add(async () => 0, {priority: 1}); 114 | t.is(queue.sizeBy({priority: 1}), 2); 115 | t.is(queue.sizeBy({priority: 0}), 1); 116 | queue.clear(); 117 | await queue.onEmpty(); 118 | t.is(queue.sizeBy({priority: 1}), 0); 119 | t.is(queue.sizeBy({priority: 0}), 0); 120 | }); 121 | 122 | test('.add() - timeout without throwing', async t => { 123 | const result: string[] = []; 124 | const queue = new PQueue({timeout: 300, throwOnTimeout: false}); 125 | queue.add(async () => { 126 | await delay(400); 127 | result.push('🐌'); 128 | }); 129 | queue.add(async () => { 130 | await delay(250); 131 | result.push('🦆'); 132 | }); 133 | queue.add(async () => { 134 | await delay(310); 135 | result.push('🐢'); 136 | }); 137 | queue.add(async () => { 138 | await delay(100); 139 | result.push('🐅'); 140 | }); 141 | queue.add(async () => { 142 | result.push('⚡️'); 143 | }); 144 | await queue.onIdle(); 145 | t.deepEqual(result, ['⚡️', '🐅', '🦆']); 146 | }); 147 | 148 | test.failing('.add() - timeout with throwing', async t => { 149 | const result: string[] = []; 150 | const queue = new PQueue({timeout: 300, throwOnTimeout: true}); 151 | await t.throwsAsync(queue.add(async () => { 152 | await delay(400); 153 | result.push('🐌'); 154 | })); 155 | queue.add(async () => { 156 | await delay(200); 157 | result.push('🦆'); 158 | }); 159 | await queue.onIdle(); 160 | t.deepEqual(result, ['🦆']); 161 | }); 162 | 163 | test('.add() - change timeout in between', async t => { 164 | const result: string[] = []; 165 | const initialTimeout = 50; 166 | const newTimeout = 200; 167 | const queue = new PQueue({timeout: initialTimeout, throwOnTimeout: false, concurrency: 2}); 168 | queue.add(async () => { 169 | const {timeout} = queue; 170 | t.deepEqual(timeout, initialTimeout); 171 | await delay(300); 172 | result.push('🐌'); 173 | }); 174 | queue.timeout = newTimeout; 175 | queue.add(async () => { 176 | const {timeout} = queue; 177 | t.deepEqual(timeout, newTimeout); 178 | await delay(100); 179 | result.push('🐅'); 180 | }); 181 | await queue.onIdle(); 182 | t.deepEqual(result, ['🐅']); 183 | }); 184 | 185 | test('.onEmpty()', async t => { 186 | const queue = new PQueue({concurrency: 1}); 187 | 188 | queue.add(async () => 0); 189 | queue.add(async () => 0); 190 | t.is(queue.size, 1); 191 | t.is(queue.pending, 1); 192 | await queue.onEmpty(); 193 | t.is(queue.size, 0); 194 | 195 | queue.add(async () => 0); 196 | queue.add(async () => 0); 197 | t.is(queue.size, 1); 198 | t.is(queue.pending, 1); 199 | await queue.onEmpty(); 200 | t.is(queue.size, 0); 201 | 202 | // Test an empty queue 203 | await queue.onEmpty(); 204 | t.is(queue.size, 0); 205 | }); 206 | 207 | test('.onIdle()', async t => { 208 | const queue = new PQueue({concurrency: 2}); 209 | 210 | queue.add(async () => delay(100)); 211 | queue.add(async () => delay(100)); 212 | queue.add(async () => delay(100)); 213 | t.is(queue.size, 1); 214 | t.is(queue.pending, 2); 215 | await queue.onIdle(); 216 | t.is(queue.size, 0); 217 | t.is(queue.pending, 0); 218 | 219 | queue.add(async () => delay(100)); 220 | queue.add(async () => delay(100)); 221 | queue.add(async () => delay(100)); 222 | t.is(queue.size, 1); 223 | t.is(queue.pending, 2); 224 | await queue.onIdle(); 225 | t.is(queue.size, 0); 226 | t.is(queue.pending, 0); 227 | }); 228 | 229 | test('.onSizeLessThan()', async t => { 230 | const queue = new PQueue({concurrency: 1}); 231 | 232 | queue.add(async () => delay(100)); 233 | queue.add(async () => delay(100)); 234 | queue.add(async () => delay(100)); 235 | queue.add(async () => delay(100)); 236 | queue.add(async () => delay(100)); 237 | 238 | await queue.onSizeLessThan(4); 239 | t.is(queue.size, 3); 240 | t.is(queue.pending, 1); 241 | 242 | await queue.onSizeLessThan(2); 243 | t.is(queue.size, 1); 244 | t.is(queue.pending, 1); 245 | 246 | await queue.onSizeLessThan(10); 247 | t.is(queue.size, 1); 248 | t.is(queue.pending, 1); 249 | 250 | await queue.onSizeLessThan(1); 251 | t.is(queue.size, 0); 252 | t.is(queue.pending, 1); 253 | }); 254 | 255 | test('.onIdle() - no pending', async t => { 256 | const queue = new PQueue(); 257 | t.is(queue.size, 0); 258 | t.is(queue.pending, 0); 259 | 260 | // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression 261 | t.is(await queue.onIdle(), undefined); 262 | }); 263 | 264 | test('.clear()', t => { 265 | const queue = new PQueue({concurrency: 2}); 266 | queue.add(async () => delay(20_000)); 267 | queue.add(async () => delay(20_000)); 268 | queue.add(async () => delay(20_000)); 269 | queue.add(async () => delay(20_000)); 270 | queue.add(async () => delay(20_000)); 271 | queue.add(async () => delay(20_000)); 272 | t.is(queue.size, 4); 273 | t.is(queue.pending, 2); 274 | queue.clear(); 275 | t.is(queue.size, 0); 276 | }); 277 | 278 | test('.addAll()', async t => { 279 | const queue = new PQueue(); 280 | const fn = async (): Promise => fixture; 281 | const functions = [fn, fn]; 282 | const promise = queue.addAll(functions); 283 | t.is(queue.size, 0); 284 | t.is(queue.pending, 2); 285 | t.deepEqual(await promise, [fixture, fixture]); 286 | }); 287 | 288 | test('enforce number in options.concurrency', t => { 289 | t.throws( 290 | () => { 291 | new PQueue({concurrency: 0}); 292 | }, 293 | {instanceOf: TypeError}, 294 | ); 295 | 296 | t.throws( 297 | () => { 298 | new PQueue({concurrency: undefined}); 299 | }, 300 | {instanceOf: TypeError}, 301 | ); 302 | 303 | t.notThrows(() => { 304 | new PQueue({concurrency: 1}); 305 | }); 306 | 307 | t.notThrows(() => { 308 | new PQueue({concurrency: 10}); 309 | }); 310 | 311 | t.notThrows(() => { 312 | new PQueue({concurrency: Number.POSITIVE_INFINITY}); 313 | }); 314 | }); 315 | 316 | test('enforce number in queue.concurrency', t => { 317 | t.throws( 318 | () => { 319 | (new PQueue()).concurrency = 0; 320 | }, 321 | {instanceOf: TypeError}, 322 | ); 323 | 324 | t.throws( 325 | () => { 326 | // @ts-expect-error Testing 327 | (new PQueue()).concurrency = undefined; 328 | }, 329 | {instanceOf: TypeError}, 330 | ); 331 | 332 | t.notThrows(() => { 333 | (new PQueue()).concurrency = 1; 334 | }); 335 | 336 | t.notThrows(() => { 337 | (new PQueue()).concurrency = 10; 338 | }); 339 | 340 | t.notThrows(() => { 341 | (new PQueue()).concurrency = Number.POSITIVE_INFINITY; 342 | }); 343 | }); 344 | 345 | test('enforce number in options.intervalCap', t => { 346 | t.throws( 347 | () => { 348 | new PQueue({intervalCap: 0}); 349 | }, 350 | {instanceOf: TypeError}, 351 | ); 352 | 353 | t.throws( 354 | () => { 355 | new PQueue({intervalCap: undefined}); 356 | }, 357 | {instanceOf: TypeError}, 358 | ); 359 | 360 | t.notThrows(() => { 361 | new PQueue({intervalCap: 1}); 362 | }); 363 | 364 | t.notThrows(() => { 365 | new PQueue({intervalCap: 10}); 366 | }); 367 | 368 | t.notThrows(() => { 369 | new PQueue({intervalCap: Number.POSITIVE_INFINITY}); 370 | }); 371 | }); 372 | 373 | test('enforce finite in options.interval', t => { 374 | t.throws( 375 | () => { 376 | new PQueue({interval: -1}); 377 | }, 378 | {instanceOf: TypeError}, 379 | ); 380 | 381 | t.throws( 382 | () => { 383 | new PQueue({interval: undefined}); 384 | }, 385 | {instanceOf: TypeError}, 386 | ); 387 | 388 | t.throws(() => { 389 | new PQueue({interval: Number.POSITIVE_INFINITY}); 390 | }); 391 | 392 | t.notThrows(() => { 393 | new PQueue({interval: 0}); 394 | }); 395 | 396 | t.notThrows(() => { 397 | new PQueue({interval: 10}); 398 | }); 399 | 400 | t.throws(() => { 401 | new PQueue({interval: Number.POSITIVE_INFINITY}); 402 | }); 403 | }); 404 | 405 | test('autoStart: false', t => { 406 | const queue = new PQueue({concurrency: 2, autoStart: false}); 407 | 408 | queue.add(async () => delay(20_000)); 409 | queue.add(async () => delay(20_000)); 410 | queue.add(async () => delay(20_000)); 411 | queue.add(async () => delay(20_000)); 412 | t.is(queue.size, 4); 413 | t.is(queue.pending, 0); 414 | t.is(queue.isPaused, true); 415 | 416 | queue.start(); 417 | t.is(queue.size, 2); 418 | t.is(queue.pending, 2); 419 | t.is(queue.isPaused, false); 420 | 421 | queue.clear(); 422 | t.is(queue.size, 0); 423 | }); 424 | 425 | test('.start() - return this', async t => { 426 | const queue = new PQueue({concurrency: 2, autoStart: false}); 427 | 428 | queue.add(async () => delay(100)); 429 | queue.add(async () => delay(100)); 430 | queue.add(async () => delay(100)); 431 | t.is(queue.size, 3); 432 | t.is(queue.pending, 0); 433 | await queue.start().onIdle(); 434 | t.is(queue.size, 0); 435 | t.is(queue.pending, 0); 436 | }); 437 | 438 | test('.start() - not paused', t => { 439 | const queue = new PQueue(); 440 | 441 | t.falsy(queue.isPaused); 442 | 443 | queue.start(); 444 | 445 | t.falsy(queue.isPaused); 446 | }); 447 | 448 | test('.pause()', t => { 449 | const queue = new PQueue({concurrency: 2}); 450 | 451 | queue.pause(); 452 | queue.add(async () => delay(20_000)); 453 | queue.add(async () => delay(20_000)); 454 | queue.add(async () => delay(20_000)); 455 | queue.add(async () => delay(20_000)); 456 | queue.add(async () => delay(20_000)); 457 | t.is(queue.size, 5); 458 | t.is(queue.pending, 0); 459 | t.is(queue.isPaused, true); 460 | 461 | queue.start(); 462 | t.is(queue.size, 3); 463 | t.is(queue.pending, 2); 464 | t.is(queue.isPaused, false); 465 | 466 | queue.add(async () => delay(20_000)); 467 | queue.pause(); 468 | t.is(queue.size, 4); 469 | t.is(queue.pending, 2); 470 | t.is(queue.isPaused, true); 471 | 472 | queue.start(); 473 | t.is(queue.size, 4); 474 | t.is(queue.pending, 2); 475 | t.is(queue.isPaused, false); 476 | 477 | queue.clear(); 478 | t.is(queue.size, 0); 479 | }); 480 | 481 | test('.add() sync/async mixed tasks', async t => { 482 | const queue = new PQueue({concurrency: 1}); 483 | queue.add(() => 'sync 1'); 484 | queue.add(async () => delay(1000)); 485 | queue.add(() => 'sync 2'); 486 | queue.add(() => fixture); 487 | t.is(queue.size, 3); 488 | t.is(queue.pending, 1); 489 | await queue.onIdle(); 490 | t.is(queue.size, 0); 491 | t.is(queue.pending, 0); 492 | }); 493 | 494 | test.failing('.add() - handle task throwing error', async t => { 495 | const queue = new PQueue({concurrency: 1}); 496 | 497 | queue.add(() => 'sync 1'); 498 | await t.throwsAsync( 499 | queue.add( 500 | () => { 501 | throw new Error('broken'); 502 | }, 503 | ), 504 | {message: 'broken'}, 505 | ); 506 | queue.add(() => 'sync 2'); 507 | 508 | t.is(queue.size, 2); 509 | 510 | await queue.onIdle(); 511 | }); 512 | 513 | test('.add() - handle task promise failure', async t => { 514 | const queue = new PQueue({concurrency: 1}); 515 | 516 | await t.throwsAsync( 517 | queue.add( 518 | async () => { 519 | throw new Error('broken'); 520 | }, 521 | ), 522 | {message: 'broken'}, 523 | ); 524 | 525 | queue.add(() => 'task #1'); 526 | 527 | t.is(queue.pending, 1); 528 | 529 | await queue.onIdle(); 530 | 531 | t.is(queue.pending, 0); 532 | }); 533 | 534 | test('.addAll() sync/async mixed tasks', async t => { 535 | const queue = new PQueue(); 536 | 537 | const functions: Array<() => (string | Promise | Promise)> = [ 538 | () => 'sync 1', 539 | async () => delay(2000), 540 | () => 'sync 2', 541 | async () => fixture, 542 | ]; 543 | 544 | const promise = queue.addAll(functions); 545 | 546 | t.is(queue.size, 0); 547 | t.is(queue.pending, 4); 548 | t.deepEqual(await promise, ['sync 1', undefined, 'sync 2', fixture]); 549 | }); 550 | 551 | test('should resolve empty when size is zero', async t => { 552 | const queue = new PQueue({concurrency: 1, autoStart: false}); 553 | 554 | // It should take 1 seconds to resolve all tasks 555 | for (let index = 0; index < 100; index++) { 556 | queue.add(async () => delay(10)); 557 | } 558 | 559 | (async () => { 560 | await queue.onEmpty(); 561 | t.is(queue.size, 0); 562 | })(); 563 | 564 | queue.start(); 565 | 566 | // Pause at 0.5 second 567 | setTimeout( 568 | async () => { 569 | queue.pause(); 570 | await delay(10); 571 | queue.start(); 572 | }, 573 | 500, 574 | ); 575 | 576 | await queue.onIdle(); 577 | }); 578 | 579 | test('.add() - throttled', async t => { 580 | const result: number[] = []; 581 | const queue = new PQueue({ 582 | intervalCap: 1, 583 | interval: 500, 584 | autoStart: false, 585 | }); 586 | queue.add(async () => result.push(1)); 587 | queue.start(); 588 | await delay(250); 589 | queue.add(async () => result.push(2)); 590 | t.deepEqual(result, [1]); 591 | await delay(300); 592 | t.deepEqual(result, [1, 2]); 593 | }); 594 | 595 | test('.add() - throttled, carryoverConcurrencyCount false', async t => { 596 | const result: number[] = []; 597 | 598 | const queue = new PQueue({ 599 | intervalCap: 1, 600 | carryoverConcurrencyCount: false, 601 | interval: 500, 602 | autoStart: false, 603 | }); 604 | 605 | const values = [0, 1]; 606 | for (const value of values) { 607 | queue.add(async () => { 608 | await delay(600); 609 | result.push(value); 610 | }); 611 | } 612 | 613 | queue.start(); 614 | 615 | (async () => { 616 | await delay(550); 617 | t.is(queue.pending, 2); 618 | t.deepEqual(result, []); 619 | })(); 620 | 621 | (async () => { 622 | await delay(650); 623 | t.is(queue.pending, 1); 624 | t.deepEqual(result, [0]); 625 | })(); 626 | 627 | await delay(1250); 628 | t.deepEqual(result, values); 629 | }); 630 | 631 | test('.add() - throttled, carryoverConcurrencyCount true', async t => { 632 | const result: number[] = []; 633 | 634 | const queue = new PQueue({ 635 | carryoverConcurrencyCount: true, 636 | intervalCap: 1, 637 | interval: 500, 638 | autoStart: false, 639 | }); 640 | 641 | const values = [0, 1]; 642 | for (const value of values) { 643 | queue.add(async () => { 644 | await delay(600); 645 | result.push(value); 646 | }); 647 | } 648 | 649 | queue.start(); 650 | 651 | (async () => { 652 | await delay(100); 653 | t.deepEqual(result, []); 654 | t.is(queue.pending, 1); 655 | })(); 656 | 657 | (async () => { 658 | await delay(550); 659 | t.deepEqual(result, []); 660 | t.is(queue.pending, 1); 661 | })(); 662 | 663 | (async () => { 664 | await delay(650); 665 | t.deepEqual(result, [0]); 666 | t.is(queue.pending, 0); 667 | })(); 668 | 669 | (async () => { 670 | await delay(1550); 671 | t.deepEqual(result, [0]); 672 | })(); 673 | 674 | await delay(1650); 675 | t.deepEqual(result, values); 676 | }); 677 | 678 | test('.add() - throttled 10, concurrency 5', async t => { 679 | const result: number[] = []; 680 | 681 | const queue = new PQueue({ 682 | concurrency: 5, 683 | intervalCap: 10, 684 | interval: 1000, 685 | autoStart: false, 686 | }); 687 | 688 | const firstValue = [...Array.from({length: 5}).keys()]; 689 | const secondValue = [...Array.from({length: 10}).keys()]; 690 | const thirdValue = [...Array.from({length: 13}).keys()]; 691 | 692 | for (const value of thirdValue) { 693 | queue.add(async () => { 694 | await delay(300); 695 | result.push(value); 696 | }); 697 | } 698 | 699 | queue.start(); 700 | 701 | t.deepEqual(result, []); 702 | 703 | (async () => { 704 | await delay(400); 705 | t.deepEqual(result, firstValue); 706 | t.is(queue.pending, 5); 707 | })(); 708 | 709 | (async () => { 710 | await delay(700); 711 | t.deepEqual(result, secondValue); 712 | })(); 713 | 714 | (async () => { 715 | await delay(1200); 716 | t.is(queue.pending, 3); 717 | t.deepEqual(result, secondValue); 718 | })(); 719 | 720 | await delay(1400); 721 | t.deepEqual(result, thirdValue); 722 | }); 723 | 724 | test('.add() - throttled finish and resume', async t => { 725 | const result: number[] = []; 726 | 727 | const queue = new PQueue({ 728 | concurrency: 1, 729 | intervalCap: 2, 730 | interval: 2000, 731 | autoStart: false, 732 | }); 733 | 734 | const values = [0, 1]; 735 | const firstValue = [0, 1]; 736 | const secondValue = [0, 1, 2]; 737 | 738 | for (const value of values) { 739 | queue.add(async () => { 740 | await delay(100); 741 | result.push(value); 742 | }); 743 | } 744 | 745 | queue.start(); 746 | 747 | (async () => { 748 | await delay(1000); 749 | t.deepEqual(result, firstValue); 750 | 751 | queue.add(async () => { 752 | await delay(100); 753 | result.push(2); 754 | }); 755 | })(); 756 | 757 | (async () => { 758 | await delay(1500); 759 | t.deepEqual(result, firstValue); 760 | })(); 761 | 762 | await delay(2200); 763 | t.deepEqual(result, secondValue); 764 | }); 765 | 766 | test('pause should work when throttled', async t => { 767 | const result: number[] = []; 768 | 769 | const queue = new PQueue({ 770 | concurrency: 2, 771 | intervalCap: 2, 772 | interval: 1000, 773 | autoStart: false, 774 | }); 775 | 776 | const values = [0, 1, 2, 3]; 777 | const firstValue = [0, 1]; 778 | const secondValue = [0, 1, 2, 3]; 779 | 780 | for (const value of values) { 781 | queue.add(async () => { 782 | await delay(100); 783 | result.push(value); 784 | }); 785 | } 786 | 787 | queue.start(); 788 | 789 | (async () => { 790 | await delay(300); 791 | t.deepEqual(result, firstValue); 792 | })(); 793 | 794 | (async () => { 795 | await delay(600); 796 | queue.pause(); 797 | })(); 798 | 799 | (async () => { 800 | await delay(1400); 801 | t.deepEqual(result, firstValue); 802 | })(); 803 | 804 | (async () => { 805 | await delay(1500); 806 | queue.start(); 807 | })(); 808 | 809 | (async () => { 810 | await delay(2200); 811 | t.deepEqual(result, secondValue); 812 | })(); 813 | 814 | await delay(2500); 815 | }); 816 | 817 | test('clear interval on pause', async t => { 818 | const queue = new PQueue({ 819 | interval: 100, 820 | intervalCap: 1, 821 | }); 822 | 823 | queue.add(() => { 824 | queue.pause(); 825 | }); 826 | 827 | queue.add(() => 'task #1'); 828 | 829 | await delay(300); 830 | 831 | t.is(queue.size, 1); 832 | }); 833 | 834 | test('should be an event emitter', t => { 835 | const queue = new PQueue(); 836 | t.true(queue instanceof EventEmitter); 837 | }); 838 | 839 | test('should emit active event per item', async t => { 840 | const items = [0, 1, 2, 3, 4]; 841 | const queue = new PQueue(); 842 | 843 | let eventCount = 0; 844 | queue.on('active', () => { 845 | eventCount++; 846 | }); 847 | 848 | for (const item of items) { 849 | queue.add(() => item); 850 | } 851 | 852 | await queue.onIdle(); 853 | 854 | t.is(eventCount, items.length); 855 | }); 856 | 857 | test('should emit idle event when idle', async t => { 858 | const queue = new PQueue({concurrency: 1}); 859 | 860 | let timesCalled = 0; 861 | queue.on('idle', () => { 862 | timesCalled++; 863 | }); 864 | 865 | const job1 = queue.add(async () => delay(100)); 866 | const job2 = queue.add(async () => delay(100)); 867 | 868 | t.is(queue.pending, 1); 869 | t.is(queue.size, 1); 870 | t.is(timesCalled, 0); 871 | 872 | await job1; 873 | 874 | t.is(queue.pending, 1); 875 | t.is(queue.size, 0); 876 | t.is(timesCalled, 0); 877 | 878 | await job2; 879 | 880 | t.is(queue.pending, 0); 881 | t.is(queue.size, 0); 882 | t.is(timesCalled, 1); 883 | 884 | const job3 = queue.add(async () => delay(100)); 885 | 886 | t.is(queue.pending, 1); 887 | t.is(queue.size, 0); 888 | t.is(timesCalled, 1); 889 | 890 | await job3; 891 | t.is(queue.pending, 0); 892 | t.is(queue.size, 0); 893 | t.is(timesCalled, 2); 894 | }); 895 | 896 | test('should emit empty event when empty', async t => { 897 | const queue = new PQueue({concurrency: 1}); 898 | 899 | let timesCalled = 0; 900 | queue.on('empty', () => { 901 | timesCalled++; 902 | }); 903 | 904 | const {resolve: resolveJob1, promise: job1Promise} = pDefer(); 905 | const {resolve: resolveJob2, promise: job2Promise} = pDefer(); 906 | 907 | const job1 = queue.add(async () => job1Promise); 908 | const job2 = queue.add(async () => job2Promise); 909 | t.is(queue.size, 1); 910 | t.is(queue.pending, 1); 911 | t.is(timesCalled, 0); 912 | 913 | resolveJob1(); 914 | await job1; 915 | 916 | t.is(queue.size, 0); 917 | t.is(queue.pending, 1); 918 | t.is(timesCalled, 0); 919 | 920 | resolveJob2(); 921 | await job2; 922 | 923 | t.is(queue.size, 0); 924 | t.is(queue.pending, 0); 925 | t.is(timesCalled, 1); 926 | }); 927 | 928 | test('should emit add event when adding task', async t => { 929 | const queue = new PQueue({concurrency: 1}); 930 | 931 | let timesCalled = 0; 932 | queue.on('add', () => { 933 | timesCalled++; 934 | }); 935 | 936 | const job1 = queue.add(async () => delay(100)); 937 | 938 | t.is(queue.pending, 1); 939 | t.is(queue.size, 0); 940 | t.is(timesCalled, 1); 941 | 942 | const job2 = queue.add(async () => delay(100)); 943 | 944 | t.is(queue.pending, 1); 945 | t.is(queue.size, 1); 946 | t.is(timesCalled, 2); 947 | 948 | await job1; 949 | 950 | t.is(queue.pending, 1); 951 | t.is(queue.size, 0); 952 | t.is(timesCalled, 2); 953 | 954 | await job2; 955 | 956 | t.is(queue.pending, 0); 957 | t.is(queue.size, 0); 958 | t.is(timesCalled, 2); 959 | 960 | const job3 = queue.add(async () => delay(100)); 961 | 962 | t.is(queue.pending, 1); 963 | t.is(queue.size, 0); 964 | t.is(timesCalled, 3); 965 | 966 | await job3; 967 | t.is(queue.pending, 0); 968 | t.is(queue.size, 0); 969 | t.is(timesCalled, 3); 970 | }); 971 | 972 | test('should emit next event when completing task', async t => { 973 | const queue = new PQueue({concurrency: 1}); 974 | 975 | let timesCalled = 0; 976 | queue.on('next', () => { 977 | timesCalled++; 978 | }); 979 | 980 | const job1 = queue.add(async () => delay(100)); 981 | 982 | t.is(queue.pending, 1); 983 | t.is(queue.size, 0); 984 | t.is(timesCalled, 0); 985 | 986 | const job2 = queue.add(async () => delay(100)); 987 | 988 | t.is(queue.pending, 1); 989 | t.is(queue.size, 1); 990 | t.is(timesCalled, 0); 991 | 992 | await job1; 993 | 994 | t.is(queue.pending, 1); 995 | t.is(queue.size, 0); 996 | t.is(timesCalled, 1); 997 | 998 | await job2; 999 | 1000 | t.is(queue.pending, 0); 1001 | t.is(queue.size, 0); 1002 | t.is(timesCalled, 2); 1003 | 1004 | const job3 = queue.add(async () => delay(100)); 1005 | 1006 | t.is(queue.pending, 1); 1007 | t.is(queue.size, 0); 1008 | t.is(timesCalled, 2); 1009 | 1010 | await job3; 1011 | t.is(queue.pending, 0); 1012 | t.is(queue.size, 0); 1013 | t.is(timesCalled, 3); 1014 | }); 1015 | 1016 | test('should emit completed / error events', async t => { 1017 | const queue = new PQueue({concurrency: 1}); 1018 | 1019 | let errorEvents = 0; 1020 | let completedEvents = 0; 1021 | queue.on('error', () => { 1022 | errorEvents++; 1023 | }); 1024 | queue.on('completed', () => { 1025 | completedEvents++; 1026 | }); 1027 | 1028 | const job1 = queue.add(async () => delay(100)); 1029 | 1030 | t.is(queue.pending, 1); 1031 | t.is(queue.size, 0); 1032 | t.is(errorEvents, 0); 1033 | t.is(completedEvents, 0); 1034 | 1035 | const job2 = queue.add(async () => { 1036 | await delay(1); 1037 | throw new Error('failure'); 1038 | }); 1039 | 1040 | t.is(queue.pending, 1); 1041 | t.is(queue.size, 1); 1042 | t.is(errorEvents, 0); 1043 | t.is(completedEvents, 0); 1044 | 1045 | await job1; 1046 | 1047 | t.is(queue.pending, 1); 1048 | t.is(queue.size, 0); 1049 | t.is(errorEvents, 0); 1050 | t.is(completedEvents, 1); 1051 | 1052 | await t.throwsAsync(job2); 1053 | 1054 | t.is(queue.pending, 0); 1055 | t.is(queue.size, 0); 1056 | t.is(errorEvents, 1); 1057 | t.is(completedEvents, 1); 1058 | 1059 | const job3 = queue.add(async () => delay(100)); 1060 | 1061 | t.is(queue.pending, 1); 1062 | t.is(queue.size, 0); 1063 | t.is(errorEvents, 1); 1064 | t.is(completedEvents, 1); 1065 | 1066 | await job3; 1067 | t.is(queue.pending, 0); 1068 | t.is(queue.size, 0); 1069 | t.is(errorEvents, 1); 1070 | t.is(completedEvents, 2); 1071 | }); 1072 | 1073 | test('should verify timeout overrides passed to add', async t => { 1074 | const queue = new PQueue({timeout: 200, throwOnTimeout: true}); 1075 | 1076 | await t.throwsAsync(queue.add(async () => { 1077 | await delay(400); 1078 | })); 1079 | 1080 | await t.notThrowsAsync(queue.add(async () => { 1081 | await delay(400); 1082 | }, {throwOnTimeout: false})); 1083 | 1084 | await t.notThrowsAsync(queue.add(async () => { 1085 | await delay(400); 1086 | }, {timeout: 600})); 1087 | 1088 | await t.notThrowsAsync(queue.add(async () => { 1089 | await delay(100); 1090 | })); 1091 | 1092 | await t.throwsAsync(queue.add(async () => { 1093 | await delay(100); 1094 | }, {timeout: 50})); 1095 | 1096 | await queue.onIdle(); 1097 | }); 1098 | 1099 | test('should skip an aborted job', async t => { 1100 | const queue = new PQueue(); 1101 | const controller = new AbortController(); 1102 | 1103 | controller.abort(); 1104 | // eslint-disable-next-line @typescript-eslint/no-empty-function 1105 | await t.throwsAsync(queue.add(() => {}, {signal: controller.signal}), { 1106 | instanceOf: DOMException, 1107 | }); 1108 | }); 1109 | 1110 | test('should pass AbortSignal instance to job', async t => { 1111 | const queue = new PQueue(); 1112 | const controller = new AbortController(); 1113 | 1114 | await queue.add(async ({signal}) => { 1115 | t.is(controller.signal, signal!); 1116 | }, {signal: controller.signal}); 1117 | }); 1118 | 1119 | test('aborting multiple jobs at the same time', async t => { 1120 | const queue = new PQueue({concurrency: 1}); 1121 | 1122 | const controller1 = new AbortController(); 1123 | const controller2 = new AbortController(); 1124 | 1125 | const task1 = queue.add(async () => new Promise(() => {}), {signal: controller1.signal}); // eslint-disable-line @typescript-eslint/no-empty-function 1126 | const task2 = queue.add(async () => new Promise(() => {}), {signal: controller2.signal}); // eslint-disable-line @typescript-eslint/no-empty-function 1127 | 1128 | setTimeout(() => { 1129 | controller1.abort(); 1130 | controller2.abort(); 1131 | }, 0); 1132 | 1133 | await t.throwsAsync(task1, {instanceOf: DOMException}); 1134 | await t.throwsAsync(task2, {instanceOf: DOMException}); 1135 | t.like(queue, {size: 0, pending: 0}); 1136 | }); 1137 | 1138 | test('.setPriority() - execute a promise before planned', async t => { 1139 | const result: string[] = []; 1140 | const queue = new PQueue({concurrency: 1}); 1141 | queue.add(async () => { 1142 | await delay(400); 1143 | result.push('🐌'); 1144 | }, {id: '🐌'}); 1145 | queue.add(async () => { 1146 | await delay(400); 1147 | result.push('🦆'); 1148 | }, {id: '🦆'}); 1149 | queue.add(async () => { 1150 | await delay(400); 1151 | result.push('🐢'); 1152 | }, {id: '🐢'}); 1153 | queue.setPriority('🐢', 1); 1154 | await queue.onIdle(); 1155 | t.deepEqual(result, ['🐌', '🐢', '🦆']); 1156 | }); 1157 | 1158 | test('.setPriority() - execute a promise after planned', async t => { 1159 | const result: string[] = []; 1160 | const queue = new PQueue({concurrency: 1}); 1161 | queue.add(async () => { 1162 | await delay(400); 1163 | result.push('🐌'); 1164 | }, {id: '🐌'}); 1165 | queue.add(async () => { 1166 | await delay(400); 1167 | result.push('🦆'); 1168 | }, {id: '🦆'}); 1169 | queue.add(async () => { 1170 | await delay(400); 1171 | result.push('🦆'); 1172 | }, {id: '🦆'}); 1173 | queue.add(async () => { 1174 | await delay(400); 1175 | result.push('🐢'); 1176 | }, {id: '🐢'}); 1177 | queue.add(async () => { 1178 | await delay(400); 1179 | result.push('🦆'); 1180 | }, {id: '🦆'}); 1181 | queue.add(async () => { 1182 | await delay(400); 1183 | result.push('🦆'); 1184 | }, {id: '🦆'}); 1185 | queue.setPriority('🐢', -1); 1186 | await queue.onIdle(); 1187 | t.deepEqual(result, ['🐌', '🦆', '🦆', '🦆', '🦆', '🐢']); 1188 | }); 1189 | 1190 | test('.setPriority() - execute a promise before planned - concurrency 2', async t => { 1191 | const result: string[] = []; 1192 | const queue = new PQueue({concurrency: 2}); 1193 | queue.add(async () => { 1194 | await delay(400); 1195 | result.push('🐌'); 1196 | }, {id: '🐌'}); 1197 | queue.add(async () => { 1198 | await delay(400); 1199 | result.push('🦆'); 1200 | }, {id: '🦆'}); 1201 | queue.add(async () => { 1202 | await delay(400); 1203 | result.push('🐢'); 1204 | }, {id: '🐢'}); 1205 | queue.add(async () => { 1206 | await delay(400); 1207 | result.push('⚡️'); 1208 | }, {id: '⚡️'}); 1209 | queue.setPriority('⚡️', 1); 1210 | await queue.onIdle(); 1211 | t.deepEqual(result, ['🐌', '🦆', '⚡️', '🐢']); 1212 | }); 1213 | 1214 | test('.setPriority() - execute a promise before planned - concurrency 3', async t => { 1215 | const result: string[] = []; 1216 | const queue = new PQueue({concurrency: 3}); 1217 | queue.add(async () => { 1218 | await delay(400); 1219 | result.push('🐌'); 1220 | }, {id: '🐌'}); 1221 | queue.add(async () => { 1222 | await delay(400); 1223 | result.push('🦆'); 1224 | }, {id: '🦆'}); 1225 | queue.add(async () => { 1226 | await delay(400); 1227 | result.push('🐢'); 1228 | }, {id: '🐢'}); 1229 | queue.add(async () => { 1230 | await delay(400); 1231 | result.push('⚡️'); 1232 | }, {id: '⚡️'}); 1233 | queue.add(async () => { 1234 | await delay(400); 1235 | result.push('🦀'); 1236 | }, {id: '🦀'}); 1237 | queue.setPriority('🦀', 1); 1238 | await queue.onIdle(); 1239 | t.deepEqual(result, ['🐌', '🦆', '🐢', '🦀', '⚡️']); 1240 | }); 1241 | 1242 | test('.setPriority() - execute a multiple promise before planned, with variable priority', async t => { 1243 | const result: string[] = []; 1244 | const queue = new PQueue({concurrency: 2}); 1245 | queue.add(async () => { 1246 | await delay(400); 1247 | result.push('🐌'); 1248 | }, {id: '🐌'}); 1249 | queue.add(async () => { 1250 | await delay(400); 1251 | result.push('🦆'); 1252 | }, {id: '🦆'}); 1253 | queue.add(async () => { 1254 | await delay(400); 1255 | result.push('🐢'); 1256 | }, {id: '🐢'}); 1257 | queue.add(async () => { 1258 | await delay(400); 1259 | result.push('⚡️'); 1260 | }, {id: '⚡️'}); 1261 | queue.add(async () => { 1262 | await delay(400); 1263 | result.push('🦀'); 1264 | }, {id: '🦀'}); 1265 | queue.setPriority('⚡️', 1); 1266 | queue.setPriority('🦀', 2); 1267 | await queue.onIdle(); 1268 | t.deepEqual(result, ['🐌', '🦆', '🦀', '⚡️', '🐢']); 1269 | }); 1270 | 1271 | test('.setPriority() - execute a promise before planned - concurrency 3 and unspecified `id`', async t => { 1272 | const result: string[] = []; 1273 | const queue = new PQueue({concurrency: 3}); 1274 | queue.add(async () => { 1275 | await delay(400); 1276 | result.push('🐌'); 1277 | }); 1278 | queue.add(async () => { 1279 | await delay(400); 1280 | result.push('🦆'); 1281 | }); 1282 | queue.add(async () => { 1283 | await delay(400); 1284 | result.push('🐢'); 1285 | }); 1286 | queue.add(async () => { 1287 | await delay(400); 1288 | result.push('⚡️'); 1289 | }); 1290 | queue.add(async () => { 1291 | await delay(400); 1292 | result.push('🦀'); 1293 | }); 1294 | queue.setPriority('5', 1); 1295 | await queue.onIdle(); 1296 | t.deepEqual(result, ['🐌', '🦆', '🐢', '🦀', '⚡️']); 1297 | }); 1298 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "@sindresorhus/tsconfig", 3 | "compilerOptions": { 4 | "outDir": "dist" 5 | }, 6 | "include": [ 7 | "source" 8 | ] 9 | } 10 | --------------------------------------------------------------------------------