Add status property to the result (#9)

Co-authored-by: Sindre Sorhus <[email protected]>

Author: ch-jobor

index.d.ts

@@ -1,13 +1,15 @@
 export interface PromiseFulfilledResult<ValueType> {
+	status: 'fulfilled';
+	value: ValueType;
 	isFulfilled: true;
 	isRejected: false;
-	value: ValueType;
 }
 
 export interface PromiseRejectedResult {
+	status: 'rejected';
+	reason: unknown;
 	isFulfilled: false;
 	isRejected: true;
-	reason: unknown;
 }
 
 export type PromiseResult<ValueType> =
@@ -38,19 +40,22 @@ console.log(results);
 /*
 [
 	{
-		isFulfilled: true,
-		isRejected: false,
+		status: 'fulfilled',
 		value: '🦄'
+		isFulfilled: true,
+		isRejected: false
 	},
 	{
-		isFulfilled: false,
-		isRejected: true,
+		status: 'rejected',
 		reason: [Error: 👹]
+		isFulfilled: false,
+		isRejected: true
 	},
 	{
-		isFulfilled: true,
-		isRejected: false,
+		status: 'fulfilled',
 		value: '🐴'
+		isFulfilled: true,
+		isRejected: false
 	}
 ]
 *\/
@@ -67,3 +72,13 @@ console.log(resolvedString);
 export default function pReflect<ValueType>(promise: PromiseLike<ValueType>): Promise<
 PromiseResult<ValueType>
 >;
+
+/**
+Narrows a variable of type `PromiseResult` to type `PromiseFulfilledResult` if the variable has the property `value`, otherwise narrows it to the `PromiseRejectedResult` type.
+*/
+export function isFulfilled<T>(promiseResult: PromiseResult<T>): promiseResult is PromiseFulfilledResult<T>;
+
+/**
+Narrows a variable of type `PromiseResult` to type `PromiseRejectedResult` if the variable has the property `reason`, otherwise narrows it to the `PromiseFulfilledResult` type.
+*/
+export function isRejected<T>(promiseResult: PromiseResult<T>): promiseResult is PromiseRejectedResult;

index.js

@@ -3,15 +3,25 @@ export default async function pReflect(promise) {
 		const value = await promise;
 
 		return {
+			status: 'fulfilled',
+			value,
 			isFulfilled: true,
-			isRejected: false,
-			value
+			isRejected: false
 		};
 	} catch (error) {
 		return {
+			status: 'rejected',
+			reason: error,
 			isFulfilled: false,
-			isRejected: true,
-			reason: error
+			isRejected: true
 		};
 	}
 }
+
+export function isFulfilled(promiseResult) {
+	return 'value' in promiseResult;
+}
+
+export function isRejected(promiseResult) {
+	return 'reason' in promiseResult;
+}

index.test-d.ts

@@ -1,14 +1,16 @@
 import {expectType} from 'tsd';
-import pReflect from './index.js';
+import pReflect, {isFulfilled} from './index.js';
 
 const result = await pReflect(Promise.resolve('foo'));
 
-if (result.isFulfilled) {
+if (isFulfilled(result)) {
+	expectType<'fulfilled'>(result.status);
+	expectType<string>(result.value);
 	expectType<true>(result.isFulfilled);
 	expectType<false>(result.isRejected);
-	expectType<string>(result.value);
 } else {
+	expectType<'rejected'>(result.status);
+	expectType<unknown>(result.reason);
 	expectType<false>(result.isFulfilled);
 	expectType<true>(result.isRejected);
-	expectType<unknown>(result.reason);
 }

readme.md

@@ -29,19 +29,22 @@ console.log(results);
 /*
 [
 	{
-		isFulfilled: true,
-		isRejected: false,
+		status: 'fulfilled',
 		value: '🦄'
+		isFulfilled: true,
+		isRejected: false
 	},
 	{
-		isFulfilled: false,
-		isRejected: true,
+		status: 'rejected',
 		reason: [Error: 👹]
+		isFulfilled: false,
+		isRejected: true
 	},
 	{
-		isFulfilled: true,
-		isRejected: false,
+		status: 'fulfilled',
 		value: '🐴'
+		isFulfilled: true,
+		isRejected: false
 	}
 ]
 */
@@ -65,16 +68,36 @@ 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`
-- `value` or `reason` *(Depending on whether the promise fulfilled or rejected)*
 
 #### 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](https://github.com/microsoft/TypeScript/issues/32399)
+- reference documentation [Using type predicates](https://www.typescriptlang.org/docs/handbook/2/narrowing.html)
+
+### 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](https://github.com/sindresorhus/p-settle) - Settle promises concurrently and get their fulfillment value or rejection reason

test.js

@@ -7,18 +7,20 @@ test('main', async t => {
 	t.deepEqual(
 		await pReflect(Promise.resolve(fixture)),
 		{
+			status: 'fulfilled',
+			value: fixture,
 			isFulfilled: true,
-			isRejected: false,
-			value: fixture
+			isRejected: false
 		}
 	);
 
 	t.deepEqual(
 		await pReflect(Promise.reject(fixture)),
 		{
+			status: 'rejected',
+			reason: fixture,
 			isFulfilled: false,
-			isRejected: true,
-			reason: fixture
+			isRejected: true
 		}
 	);
 });