p-settle

p-settle

Settle promises concurrently and get their fulfillment value or rejection reason with optional limited concurrency

Install

npm install p-settle

Usage

import fs from 'node:fs/promises';
import pSettle from 'p-settle';

const files = [
	'a.txt',
	'b.txt' // Doesn't exist
].map(filename => fs.readFile(filename, 'utf8'));

console.log(await pSettle(files));
/*
[
	{
		status: 'fulfilled',
		value: '🦄',
		isFulfilled: true,
		isRejected: false,
	},
	{
		status: 'rejected',
		reason: [Error: ENOENT: no such file or directory, open 'b.txt'],
		isFulfilled: false,
		isRejected: true,
	}
]
*/

With a mapper function:

import fs from 'node:fs/promises';
import pSettle from 'p-settle';

const files = ['a.txt', 'b.txt']; // Filenames

console.log(await pSettle(files, {
	mapper: filename => fs.readFile(filename, 'utf8'),
	concurrency: 2
}));
/*
[
	{
		status: 'fulfilled',
		value: '🦄',
		isFulfilled: true,
		isRejected: false,
	},
	{
		status: 'rejected',
		reason: [Error: ENOENT: no such file or directory, open 'b.txt'],
		isFulfilled: false,
		isRejected: true,
	}
]
*/

API

pSettle(array, options?)

Returns a Promise<object[]> that is fulfilled when all promises from the array argument are settled.

The objects in the array have the following properties:

• status ('fulfilled' or 'rejected', depending on how the promise resolved)
• value or reason (Depending on whether the promise fulfilled or rejected)
• isFulfilled
• isRejected

array

Type: Array<ValueType | PromiseLike<ValueType> | ((...args: any[]) => PromiseLike<ValueType>)>

The array can contain a mix of any value, promise, and async function. Promises are awaited. Async functions are executed and awaited. The concurrency option only works for elements that are async functions.

When using the mapper option, array can be of any type since the mapper function will transform each element.

options

Type: object

concurrency

Type: number (Integer)
Default: Infinity
Minimum: 1

The number of concurrently pending promises.

Note: This only limits concurrency for elements that are async functions, not promises. When using the mapper option, concurrency applies to the mapped functions.

mapper

Type: Function

Function which is called for every item in array. Expected to return a promise or value.

The mapper function receives two arguments:

• element - The current element being processed
• index - The index of the element in the source array

When provided, the mapper function transforms each element in the array before settling it. This allows you to work with arrays of any type of data.

isFulfilled(object)

This is a type guard for TypeScript users.

This is useful since await pSettle(promiseArray) always returns a PromiseResult[]. This function can be used to determine whether PromiseResult is PromiseFulfilledResult or PromiseRejectedResult.

isRejected(object)

This is a type guard for TypeScript users.

This is useful since await pSettle(promiseArray) always returns a PromiseResult[]. This function can be used to determine whether PromiseResult is PromiseRejectedResult or PromiseFulfilledResult.

Related

• p-reflect - Make a promise always fulfill with its actual fulfillment value or rejection reason
• p-map - Map over promises concurrently
• More…

Similar packages

Other packages similar to p-settle

promise-settle

The promise-settle package provides similar functionality to p-settle by settling multiple promises and returning their results. It also returns an array of objects with the state and value/reason of each promise. However, p-settle is more actively maintained and has a more modern API.

settle-promise

The settle-promise package is another alternative that settles multiple promises and returns their results. It is less popular and less actively maintained compared to p-settle, but it offers similar functionality.

promise.allsettled

The promise.allsettled package is a polyfill for the Promise.allSettled method, which is now a standard part of JavaScript. It provides the same functionality as p-settle but is built into the language itself, making it a more native solution.