### Install Promise Pool

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

Installs the @supercharge/promise-pool package using npm. This is the first step to using the library in your Node.js project.

```bash
npm i @supercharge/promise-pool
```

--------------------------------

### Custom Error Handling and Collection

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

Provides an example of custom error handling using `.handleError()`. This approach requires manual collection of errors. It also shows how to exit the pool early by throwing an error within the handler.

```javascript
import { PromisePool } from '@supercharge/promise-pool'

try {
  const errors = []

  const { results } = await PromisePool
    .for(users)
    .withConcurrency(4)
    .handleError(async (error, user) => {
      if (error instanceof ValidationError) {
        errors.push(error) // you must collect errors yourself
        return
      }

      if (error instanceof ThrottleError) { // Execute error handling on specific errors
        await retryUser(user)
        return
      }

      throw error // Uncaught errors will immediately stop PromisePool
    })
    .process(async data => {
      // the harder you work for something,
      // the greater you’ll feel when you achieve it
    })

  await handleCollected(errors) // this may throw

  return { results }
} catch (error) {
  await handleThrown(error)
}
```

--------------------------------

### Default Concurrency Processing

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

Shows how to use the PromisePool with its default concurrency setting (10) to process an array of data. This is a simpler usage pattern when explicit concurrency control is not needed.

```javascript
await PromisePool
  .for(users)
  .process(async data => {
    // processes 10 items in parallel by default
  })
```

--------------------------------

### Chain Multiple Task Lifecycle Callbacks

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

Demonstrates the ability to chain multiple onTaskStarted and onTaskFinished callbacks to separate different functionalities within the task lifecycle event handling.

```javascript
import { PromisePool } from '@supercharge/promise-pool'

await PromisePool
  .for(users)
  .onTaskStarted(() => {}) // First started callback
  .onTaskStarted(() => {}) // Second started callback
  .onTaskFinished(() => {}) // First finished callback
  .onTaskFinished(() => {}) // Second finished callback
  .process(async (user, index, pool) => {
    // processes the `user` data
  })
```

--------------------------------

### Process Promises with Concurrency

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

Demonstrates how to use the PromisePool to process an array of users concurrently. It sets a concurrency limit of 2 and processes each user asynchronously. The results and errors are collected.

```javascript
import { PromisePool } from '@supercharge/promise-pool'

const users = [
  { name: 'Marcus' },
  { name: 'Norman' },
  { name: 'Christian' }
]

const { results, errors } = await PromisePool
  .withConcurrency(2)
  .for(users)
  .process(async (userData, index, pool) => {
    const user = await User.createIfNotExisting(userData)

    return user
  })
```

--------------------------------

### Hook into Task Lifecycle with Callbacks

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

Utilize onTaskStarted and onTaskFinished methods to execute custom logic when tasks begin or complete processing. These callbacks receive the current item and the promise pool instance, allowing access to pool statistics like processed percentage and active task count.

```javascript
import { PromisePool } from '@supercharge/promise-pool'

await PromisePool
  .for(users)
  .onTaskStarted((item, pool) => {
    console.log(`Progress: ${pool.processedPercentage()}%`)
    console.log(`Active tasks: ${pool.processedItems().length}`)
    console.log(`Active tasks: ${pool.activeTasksCount()}`)
    console.log(`Finished tasks: ${pool.processedItems().length}`)
    console.log(`Finished tasks: ${pool.processedCount()}`)
  })
  .onTaskFinished((item, pool) => {
    // update a progress bar or something else :)
  })
  .process(async (user, index, pool) => {
    // processes the `user` data
  })
```

--------------------------------

### Align Processed Results with Source Items

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

Use the useCorrespondingResults method to ensure that the processed results in the output array maintain the same order as their corresponding items in the source array. This is useful for direct mapping between input and output.

```javascript
import { setTimeout } from 'node:timers/promises'
import { PromisePool } from '@supercharge/promise-pool'

const { results } = await PromisePool
  .for([1, 2, 3])
  .withConcurrency(5)
  .useCorrespondingResults()
  .process(async (number, index) => {
    const value = number * 2

    return await setTimeout(10 - index, value)
  })

/**
 * source array: [1, 2, 3]
 * result array: [2, 4 ,6]
 * --> result values match the position of their source items
 */
```

--------------------------------

### Manually Stop Promise Pool

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

Illustrates how to manually stop an active PromisePool from within the `.process()` method. The `pool.stop()` method can be called based on a condition to halt further processing.

```javascript
await PromisePool
  .for(users)
  .process(async (user, index, pool) => {
    if (condition) {
      return pool.stop()
    }

    // processes the `user` data
  })
```

--------------------------------

### Handle NotRun and Failed Tasks with Corresponding Results

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

When useCorrespondingResults is enabled, the results array can contain actual values, PromisePool.notRun symbols for tasks that did not execute, or PromisePool.failed symbols for tasks that encountered errors. This allows for selective reprocessing of failed or skipped tasks.

```javascript
import { PromisePool } from '@supercharge/promise-pool'

const { results, errors } = await PromisePool
  .for([1, 2, 3])
  .withConcurrency(5)
  .useCorrespondingResults()
  .process(async (number) => {
    // …
  })

const itemsNotRun = results.filter(result => {
  return result === PromisePool.notRun
})

const failedItems = results.filter(result => {
  return result === PromisePool.failed
})
```

--------------------------------

### Stop Promise Pool from Error Handler

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

Demonstrates stopping a PromisePool from within the `.handleError()` method. This is useful for halting execution when specific error types are encountered during processing.

```javascript
import { PromisePool } from '@supercharge/promise-pool'

await PromisePool
  .for(users)
  .handleError(async (error, user, pool) => {
    if (error instanceof SomethingBadHappenedError) {
      return pool.stop()
    }

    // handle the given `error`
  })
  .process(async (user, index, pool) => {
    // processes the `user` data
  })
```

--------------------------------

### Set Task Timeouts with withTaskTimeout

Source: https://github.com/supercharge/promise-pool/blob/main/README.md

Configure a maximum duration for individual tasks to complete using the withTaskTimeout method. Tasks exceeding this specified time in milliseconds will be marked as failed. This timeout applies per task, not to the entire pool.

```javascript
import { PromisePool } from '@supercharge/promise-pool'

await PromisePool
  .for(users)
  .withTaskTimeout(2000) // 2-second timeout per task
  .process(async (user, index, pool) => {
    // processes the `user` data
  })
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.