From 9564c048a3238d10414f6701d1d6bb5f93977357 Mon Sep 17 00:00:00 2001
From: Alec Larson <1925840+aleclarson@users.noreply.github.com>
Date: Wed, 10 Jul 2024 16:33:24 -0400
Subject: [PATCH] feat: add `errorFirst` function

---
 src/async/errorFirst.ts | 34 ++++++++++++++++++++++++++++++++++
 src/mod.ts              |  1 +
 2 files changed, 35 insertions(+)
 create mode 100644 src/async/errorFirst.ts

diff --git a/src/async/errorFirst.ts b/src/async/errorFirst.ts
new file mode 100644
index 00000000..099d696a
--- /dev/null
+++ b/src/async/errorFirst.ts
@@ -0,0 +1,34 @@
+import { isFunction } from 'radashi'
+
+const left = <Error>(error: Error): [Error, null] => [error, null]
+const right = <T>(value: T): [null, T] => [null, value]
+
+export type ErrorFirst<T, Error = unknown> = [null, T] | [Error, null]
+
+/**
+ * Call an async function and return a promise that resolves to an
+ * array of the error and the value.
+ *
+ * - If the promise resolves, the result is `[null, value]`.
+ * - If the promise rejects, the result is `[error, null]`.
+ */
+export function errorFirst<T, Args extends any[]>(
+  fn: (...args: Args) => Promise<T>,
+  ...args: Args
+): Promise<ErrorFirst<T>>
+
+export function errorFirst<T>(promise: Promise<T>): Promise<ErrorFirst<T>>
+
+export function errorFirst<T>(
+  promise: Promise<T> | ((...args: any[]) => Promise<T>),
+  ...args: any[]
+): Promise<ErrorFirst<T>> {
+  if (isFunction(promise)) {
+    try {
+      promise = promise(...args)
+    } catch (error) {
+      promise = Promise.reject(error)
+    }
+  }
+  return promise.then(right, left)
+}
diff --git a/src/mod.ts b/src/mod.ts
index 25238f89..ef862f0d 100644
--- a/src/mod.ts
+++ b/src/mod.ts
@@ -34,6 +34,7 @@ export * from './array/zipToObject.ts'
 export * from './async/AggregateError.ts'
 export * from './async/all.ts'
 export * from './async/defer.ts'
+export * from './async/errorFirst.ts'
 export * from './async/guard.ts'
 export * from './async/map.ts'
 export * from './async/parallel.ts'