\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```\r\nnpm i @supercharge/promise-pool\r\n```\r\n\r\n\r\n## Docs\r\n\r\n- 📖 [Documentation](https://superchargejs.com/docs/promise-pool)\r\n\r\n\r\n## Usage\r\nUsing the promise pool is pretty straightforward. The package exposes a class and you can create a promise pool instance using the fluent interface.\r\n\r\nHere’s an example using a concurrency of 2:\r\n\r\n```js\r\nimport { PromisePool } from '@supercharge/promise-pool'\r\n\r\nconst users = [\r\n { name: 'Marcus' },\r\n { name: 'Norman' },\r\n { name: 'Christian' }\r\n]\r\n\r\nconst { results, errors } = await PromisePool\r\n .withConcurrency(2)\r\n .for(users)\r\n .process(async (userData, index, pool) => {\r\n const user = await User.createIfNotExisting(userData)\r\n\r\n return user\r\n })\r\n```\r\n\r\nThe promise pool uses a default concurrency of 10:\r\n\r\n```js\r\nawait PromisePool\r\n .for(users)\r\n .process(async data => {\r\n // processes 10 items in parallel by default\r\n })\r\n```\r\n\r\n\r\n## Manually Stop the Pool\r\nYou can stop the processing of a promise pool using the `pool` instance provided to the `.process()` and `.handleError()` methods. Here’s an example how you can stop an active promise pool from within the `.process()` method:\r\n\r\n```js\r\nawait PromisePool\r\n .for(users)\r\n .process(async (user, index, pool) => {\r\n if (condition) {\r\n return pool.stop()\r\n }\r\n\r\n // processes the `user` data\r\n })\r\n```\r\n\r\nYou may also stop the pool from within the `.handleError()` method in case you need to:\r\n\r\n```js\r\nimport { PromisePool } from '@supercharge/promise-pool'\r\n\r\nawait PromisePool\r\n .for(users)\r\n .handleError(async (error, user, pool) => {\r\n if (error instanceof SomethingBadHappenedError) {\r\n return pool.stop()\r\n }\r\n\r\n // handle the given `error`\r\n })\r\n .process(async (user, index, pool) => {\r\n // processes the `user` data\r\n })\r\n```\r\n\r\n\r\n## Bring Your Own Error Handling\r\nThe promise pool allows for custom error handling. You can take over the error handling by implementing an error handler using the `.handleError(handler)`.\r\n\r\n> If you provide an error handler, the promise pool doesn’t collect any errors. You must then collect errors yourself.\r\n\r\nProviding a custom error handler allows you to exit the promise pool early by throwing inside the error handler function. Throwing errors is in line with Node.js error handling using async/await.\r\n\r\n```js\r\nimport { PromisePool } from '@supercharge/promise-pool'\r\n\r\ntry {\r\n const errors = []\r\n\r\n const { results } = await PromisePool\r\n .for(users)\r\n .withConcurrency(4)\r\n .handleError(async (error, user) => {\r\n if (error instanceof ValidationError) {\r\n errors.push(error) // you must collect errors yourself\r\n return\r\n }\r\n\r\n if (error instanceof ThrottleError) { // Execute error handling on specific errors\r\n await retryUser(user)\r\n return\r\n }\r\n\r\n throw error // Uncaught errors will immediately stop PromisePool\r\n })\r\n .process(async data => {\r\n // the harder you work for something,\r\n // the greater you’ll feel when you achieve it\r\n })\r\n\r\n await handleCollected(errors) // this may throw\r\n\r\n return { results }\r\n} catch (error) {\r\n await handleThrown(error)\r\n}\r\n```\r\n\r\n\r\n## Callback for Started and Finished Tasks\r\nYou can use the `onTaskStarted` and `onTaskFinished` methods to hook into the processing of tasks. The provided callback for each method will be called when a task started/finished processing:\r\n\r\n\r\n```js\r\nimport { PromisePool } from '@supercharge/promise-pool'\r\n\r\nawait PromisePool\r\n .for(users)\r\n .onTaskStarted((item, pool) => {\r\n console.log(`Progress: ${pool.processedPercentage()}%`)\r\n console.log(`Active tasks: ${pool.processedItems().length}`)\r\n console.log(`Active tasks: ${pool.activeTasksCount()}`)\r\n console.log(`Finished tasks: ${pool.processedItems().length}`)\r\n console.log(`Finished tasks: ${pool.processedCount()}`)\r\n })\r\n .onTaskFinished((item, pool) => {\r\n // update a progress bar or something else :)\r\n })\r\n .process(async (user, index, pool) => {\r\n // processes the `user` data\r\n })\r\n```\r\n\r\nYou can also chain multiple `onTaskStarted` and `onTaskFinished` handling (in case you want to separate some functionality):\r\n\r\n```js\r\nimport { PromisePool } from '@supercharge/promise-pool'\r\n\r\nawait PromisePool\r\n .for(users)\r\n .onTaskStarted(() => {})\r\n .onTaskStarted(() => {})\r\n .onTaskFinished(() => {})\r\n .onTaskFinished(() => {})\r\n .process(async (user, index, pool) => {\r\n // processes the `user` data\r\n })\r\n```\r\n\r\n\r\n## Task Timeouts\r\nSometimes it’s useful to configure a timeout in which a task must finish processing. A task that times out is marked as failed. You may use the `withTaskTimeout(![](\"https://superchargejs.com/images/supercharge-text.svg\")
\r\n \r\n ![\"Latest](\"https://img.shields.io/npm/v/@supercharge/promise-pool.svg\")
\r\n ![\"Monthly](\"https://img.shields.io/npm/dm/@supercharge/promise-pool.svg\")
\r\n