p-reflect

What is p-reflect?

The p-reflect npm package is a utility for reflecting a promise, meaning it allows you to handle both resolved and rejected promises in a uniform way. It wraps a promise and returns an object with the status and value or reason of the promise, making it easier to handle errors and results in a consistent manner.

What are p-reflect's main functionalities?

Reflecting a Promise

This feature allows you to reflect a resolved promise. The returned object contains the status of the promise and its value.

const pReflect = require('p-reflect');

(async () => {
  const result = await pReflect(Promise.resolve('Success'));
  console.log(result); // { isFulfilled: true, isRejected: false, value: 'Success' }
})();

Handling Rejected Promises

This feature allows you to reflect a rejected promise. The returned object contains the status of the promise and the reason for rejection.

const pReflect = require('p-reflect');

(async () => {
  const result = await pReflect(Promise.reject(new Error('Failure')));
  console.log(result); // { isFulfilled: false, isRejected: true, reason: Error: Failure }
})();

Combining Multiple Promises

This feature allows you to handle multiple promises and get their statuses and results in a consistent manner.

const pReflect = require('p-reflect');

(async () => {
  const promises = [
    pReflect(Promise.resolve('Success 1')),
    pReflect(Promise.reject(new Error('Failure 1'))),
    pReflect(Promise.resolve('Success 2')),
  ];
  const results = await Promise.all(promises);
  console.log(results);
  // [
  //   { isFulfilled: true, isRejected: false, value: 'Success 1' },
  //   { isFulfilled: false, isRejected: true, reason: Error: Failure 1 },
  //   { isFulfilled: true, isRejected: false, value: 'Success 2' }
  // ]
})();

Other packages similar to p-reflect

promise-reflect

The promise-reflect package provides similar functionality by reflecting promises and returning their status and value or reason. It is a lightweight alternative to p-reflect with a similar API.

p-settle

The p-settle package settles multiple promises and returns an array of objects with the status and value or reason of each promise. It is useful for handling multiple promises in a consistent way, similar to p-reflect.

settle-promise

The settle-promise package provides a way to settle a single promise and get its status and value or reason. It offers similar functionality to p-reflect but focuses on individual promises.

README

p-reflect

Make a promise always fulfill with its actual fulfillment value or rejection reason

Useful when you want a promise to fulfill no matter what and would rather handle the actual state afterwards.

Install

$ npm install p-reflect

Usage

Here, Promise.all would normally fail early because one of the promises rejects, but by using p-reflect, we can ignore the rejection and handle it later on.

import pReflect from 'p-reflect';

const promises = [
	getPromise(),
	getPromiseThatRejects(),
	getPromise()
];

const results = await Promise.all(promises.map(pReflect));

console.log(results);
/*
[
	{
		status: 'fulfilled',
		value: '🦄'
		isFulfilled: true,
		isRejected: false
	},
	{
		status: 'rejected',
		reason: [Error: 👹]
		isFulfilled: false,
		isRejected: true
	},
	{
		status: 'fulfilled',
		value: '🐴'
		isFulfilled: true,
		isRejected: false
	}
]
*/

const resolvedString = results
	.filter(result => result.isFulfilled)
	.map(result => result.value)
	.join('');

console.log(resolvedString);
//=> '🦄🐴'

The above is just an example. Use p-settle if you need exactly that.

API

pReflect(promise)

Returns a Promise<Object>.

The object has 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

promise

Type: Promise

A promise to reflect upon.

isFulfilled(object)

This is a type guard for TypeScript users.

Returns true if the object has the property value, false otherwise.

This is useful since await pReflect(promise) always returns a PromiseResult. This function can be used to determine whether PromiseResult is PromiseFulfilledResult or PromiseRejectedResult.

This is a workaround for microsoft/TypeScript#32399

• reference documentation Using type predicates

isRejected(object)

This is a type guard for TypeScript users.

Returns true if the object has the property reason, false otherwise.

This is useful since await pReflect(promise) always returns a PromiseResult. This function can be used to determine whether PromiseResult is PromiseRejectedResult or PromiseFulfilledResult.

Related

• p-settle - Settle promises concurrently and get their fulfillment value or rejection reason
• More…