Either: add orElse, closes #500 (#501)

.changeset/happy-houses-camp.md

@@ -0,0 +1,5 @@
+---
+"@effect/data": patch
+---
+
+Either: add orElse, closes #500

docs/modules/Either.ts.md

@@ -23,6 +23,8 @@ Added in v1.0.0
   - [try](#try)
 - [equivalence](#equivalence)
   - [getEquivalence](#getequivalence)
+- [error handling](#error-handling)
+  - [orElse](#orelse)
 - [generators](#generators)
   - [gen](#gen)
 - [getters](#getters)
@@ -229,6 +231,23 @@ export declare const getEquivalence: <E, A>(
 
 Added in v1.0.0
 
+# error handling
+
+## orElse
+
+Returns `self` if it is a `Right` or `that` otherwise.
+
+**Signature**
+
+```ts
+export declare const orElse: {
+  <E1, E2, B>(that: (e1: E1) => Either<E2, B>): <A>(self: Either<E1, A>) => Either<E2, B | A>
+  <E1, A, E2, B>(self: Either<E1, A>, that: (e1: E1) => Either<E2, B>): Either<E2, A | B>
+}
+```
+
+Added in v1.0.0
+
 # generators
 
 ## gen

src/Either.ts

@@ -470,6 +470,24 @@ export const getOrThrow: <E, A>(self: Either<E, A>) => A = getOrThrowWith(() =>
   new Error("getOrThrow called on a Left")
 )
 
+/**
+ * Returns `self` if it is a `Right` or `that` otherwise.
+ *
+ * @param self - The input `Either` value to check and potentially return.
+ * @param that - A function that takes the error value from `self` (if it's a `Left`) and returns a new `Either` value.
+ *
+ * @category error handling
+ * @since 1.0.0
+ */
+export const orElse: {
+  <E1, E2, B>(that: (e1: E1) => Either<E2, B>): <A>(self: Either<E1, A>) => Either<E2, A | B>
+  <E1, A, E2, B>(self: Either<E1, A>, that: (e1: E1) => Either<E2, B>): Either<E2, A | B>
+} = dual(
+  2,
+  <E1, A, E2, B>(self: Either<E1, A>, that: (e1: E1) => Either<E2, B>): Either<E2, A | B> =>
+    isLeft(self) ? that(self.left) : right(self.right)
+)
+
 /**
  * @category combining
  * @since 1.0.0

test/Either.ts

@@ -251,4 +251,11 @@ describe.concurrent("Either", () => {
     Util.deepStrictEqual(Either.all({ a: Either.right(1), b: Either.right(true) }), Either.right({ a: 1, b: true }))
     Util.deepStrictEqual(Either.all({ a: Either.right(1), b: Either.left("e") }), Either.left("e"))
   })
+
+  it("orElse", () => {
+    Util.deepStrictEqual(pipe(Either.right(1), Either.orElse(() => Either.right(2))), Either.right(1))
+    Util.deepStrictEqual(pipe(Either.right(1), Either.orElse(() => Either.left("b"))), Either.right(1))
+    Util.deepStrictEqual(pipe(Either.left("a"), Either.orElse(() => Either.right(2))), Either.right(2))
+    Util.deepStrictEqual(pipe(Either.left("a"), Either.orElse(() => Either.left("b"))), Either.left("b"))
+  })
 })