Add isFulfilled and isRejected guards for use with Promise.allSettled (…

…#25)

.changeset/rude-games-try.md

@@ -0,0 +1,5 @@
+---
+'emery': minor
+---
+
+Added `isFulfilled` and `isRejected` guards for use with `Promise.allSettled`

docs/pages/docs/guards.md

@@ -98,3 +98,33 @@ Checks whether an array is **not** empty.
 ```ts
 function isNonEmptyArray<T>(value: T[]): value is [T, ...T[]];
 ```
+
+## Promise
+
+Guards for [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) related types.
+
+### isFulfilled
+
+Checks whether a result from [`Promise.allSettled`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) is fulfilled
+
+```ts
+function isFulfilled<T>(result: PromiseSettledResult<T>): result is PromiseFulfilledResult<T>;
+```
+
+```ts
+const results = await Promise.allSettled(promises);
+const fulfilledValues = results.filter(isFulfilled).map(result => result.value);
+```
+
+### isRejected
+
+Checks whether a result from [`Promise.allSettled`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) is rejected.
+
+```ts
+function isRejected(result: PromiseSettledResult<unknown>): result is PromiseRejectedResult;
+```
+
+```ts
+const results = await Promise.allSettled(promises);
+const rejectionReasons = results.filter(isRejected).map(result => result.reason);
+```

src/guards.test.ts

@@ -1,10 +1,12 @@
 import {
   isBoolean,
   isDefined,
+  isFulfilled,
   isNonEmptyArray,
   isNull,
   isNullish,
   isNumber,
+  isRejected,
   isString,
   isUndefined,
 } from './guards';
@@ -85,4 +87,17 @@ describe('guards', () => {
       });
     });
   });
+
+  describe('promise', () => {
+    it('isFulfilled should validate assumed values', async () => {
+      expect(
+        (await Promise.allSettled([Promise.resolve(), Promise.reject()])).map(x => isFulfilled(x)),
+      ).toEqual([true, false]);
+    });
+    it('isRejected should validate assumed values', async () => {
+      expect(
+        (await Promise.allSettled([Promise.resolve(), Promise.reject()])).map(x => isRejected(x)),
+      ).toEqual([false, true]);
+    });
+  });
 });

src/guards.ts

@@ -1,3 +1,4 @@
+/// <reference lib="es2020.promise" />
 import { Nullish } from './types';
 
 // Primitives
@@ -48,3 +49,32 @@ export function isNullish(value: unknown): value is Nullish {
 export function isDefined<T>(value: T): value is NonNullable<T> {
   return !isNullish(value);
 }
+
+// Promise
+// ------------------------------
+
+/**
+ * Checks whether a result from `Promise.allSettled` is fulfilled
+ *
+ * ```ts
+ * const results = await Promise.allSettled(promises);
+ * const fulfilledValues = results.filter(isFulfilled).map(result => result.value);
+ * ```
+ */
+export function isFulfilled<T>(
+  result: PromiseSettledResult<T>,
+): result is PromiseFulfilledResult<T> {
+  return result.status === 'fulfilled';
+}
+
+/**
+ * Checks whether a result from `Promise.allSettled` is rejected
+ *
+ * ```ts
+ * const results = await Promise.allSettled(promises);
+ * const rejectionReasons = results.filter(isRejected).map(result => result.reason);
+ * ```
+ */
+export function isRejected(result: PromiseSettledResult<unknown>): result is PromiseRejectedResult {
+  return result.status === 'rejected';
+}

tsconfig.json

@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "target": "es2016",
+    "target": "es2020",
     "module": "commonjs",
     "declaration": true,
     "declarationMap": true,