Add Either.transposeMapOption (#4741)

Author: titouancreach

.changeset/dirty-lemons-lie.md

@@ -0,0 +1,5 @@
+---
+"effect": minor
+---
+
+Add Either.transposeMapOption

packages/effect/dtslint/Either.tst.ts

@@ -1,4 +1,4 @@
-import { Array, Either, hole, pipe, Predicate } from "effect"
+import { Array, Either, hole, Option, pipe, Predicate } from "effect"
 import { describe, expect, it } from "tstyche"
 
 declare const string$string: Either.Either<string, string>
@@ -317,3 +317,36 @@ describe("Either", () => {
     ).type.toBe<Either.Either<{ a: number; b: string; c: boolean }, never>>()
   })
 })
+
+it("transposeMapOption", () => {
+  expect(Either.transposeMapOption(Option.none(), (value) => {
+    expect(value).type.toBe<never>()
+    return string$string
+  })).type.toBe<
+    Either.Either<Option.Option<string>, string>
+  >()
+  expect(pipe(
+    Option.none(),
+    Either.transposeMapOption((value) => {
+      expect(value).type.toBe<never>()
+      return string$string
+    })
+  )).type.toBe<
+    Either.Either<Option.Option<string>, string>
+  >()
+  expect(Either.transposeMapOption(Option.some(42), (value) => {
+    expect(value).type.toBe<number>()
+    return string$string
+  })).type.toBe<
+    Either.Either<Option.Option<string>, string>
+  >()
+  expect(pipe(
+    Option.some(42),
+    Either.transposeMapOption((value) => {
+      expect(value).type.toBe<number>()
+      return string$string
+    })
+  )).type.toBe<
+    Either.Either<Option.Option<string>, string>
+  >()
+})

packages/effect/src/Either.ts

@@ -994,3 +994,47 @@ export const transposeOption = <A = never, E = never>(
 ): Either<Option<A>, E> => {
   return option_.isNone(self) ? right(option_.none) : map(self.value, option_.some)
 }
+
+/**
+ * Applies an `Either` on an `Option` and transposes the result.
+ *
+ * **Details**
+ *
+ * If the `Option` is `None`, the resulting `Either` will immediately succeed with a `Right` value of `None`.
+ * If the `Option` is `Some`, the transformation function will be applied to the inner value, and its result wrapped in a `Some`.
+ *
+ * @example
+ * ```ts
+ * import { Either, Option, pipe } from "effect"
+ *
+ * //          ┌─── Either<Option<number>, never>>
+ * //          ▼
+ * const noneResult = pipe(
+ *   Option.none(),
+ *   Either.transposeMapOption(() => Either.right(42)) // will not be executed
+ * )
+ * console.log(noneResult)
+ * // Output: { _id: 'Either', _tag: 'Right', right: { _id: 'Option', _tag: 'None' } }
+ *
+ * //          ┌─── Either<Option<number>, never>>
+ * //          ▼
+ * const someRightResult = pipe(
+ *   Option.some(42),
+ *   Either.transposeMapOption((value) => Either.right(value * 2))
+ * )
+ * console.log(someRightResult)
+ * // Output: { _id: 'Either', _tag: 'Right', right: { _id: 'Option', _tag: 'Some', value: 84 } }
+ * ```
+ *
+ * @since 3.15.0
+ * @category Optional Wrapping & Unwrapping
+ */
+export const transposeMapOption = dual<
+  <A, B, E = never>(
+    f: (self: A) => Either<B, E>
+  ) => (self: Option<A>) => Either<Option<B>, E>,
+  <A, B, E = never>(
+    self: Option<A>,
+    f: (self: A) => Either<B, E>
+  ) => Either<Option<B>, E>
+>(2, (self, f) => option_.isNone(self) ? right(option_.none) : map(f(self.value), option_.some))