Add Effect.transposeMapOption (#4597)

Author: LaureRC

.changeset/small-ties-love.md

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

packages/effect/dtslint/Effect.tst.ts

@@ -1392,4 +1392,37 @@ describe("Effect", () => {
       Effect.Effect<Option.Option<string>, "err-1", "dep-1">
     >()
   })
+
+  it("transposeMapOption", () => {
+    expect(Effect.transposeMapOption(Option.none(), (value) => {
+      expect(value).type.toBe<never>()
+      return string
+    })).type.toBe<
+      Effect.Effect<Option.Option<string>, "err-1", "dep-1">
+    >()
+    expect(pipe(
+      Option.none(),
+      Effect.transposeMapOption((value) => {
+        expect(value).type.toBe<never>()
+        return string
+      })
+    )).type.toBe<
+      Effect.Effect<Option.Option<string>, "err-1", "dep-1">
+    >()
+    expect(Effect.transposeMapOption(Option.some(42), (value) => {
+      expect(value).type.toBe<number>()
+      return string
+    })).type.toBe<
+      Effect.Effect<Option.Option<string>, "err-1", "dep-1">
+    >()
+    expect(pipe(
+      Option.some(42),
+      Effect.transposeMapOption((value) => {
+        expect(value).type.toBe<number>()
+        return string
+      })
+    )).type.toBe<
+      Effect.Effect<Option.Option<string>, "err-1", "dep-1">
+    >()
+  })
 })

packages/effect/src/Effect.ts

@@ -13263,6 +13263,50 @@ export const transposeOption = <A = never, E = never, R = never>(
   return option_.isNone(self) ? succeedNone : map(self.value, option_.some)
 }
 
+/**
+ * Applies an `Effect` on an `Option` and transposes the result.
+ *
+ * **Details**
+ *
+ * If the `Option` is `None`, the resulting `Effect` will immediately succeed with a `None` value.
+ * If the `Option` is `Some`, the effectful operation will be executed on the inner value, and its result wrapped in a `Some`.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option, pipe } from "effect"
+ *
+ * //          ┌─── Effect<Option<number>, never, never>>
+ * //          ▼
+ * const noneResult = pipe(
+ *   Option.none(),
+ *   Effect.transposeMapOption(() => Effect.succeed(42)) // will not be executed
+ * )
+ * console.log(Effect.runSync(noneResult))
+ * // Output: { _id: 'Option', _tag: 'None' }
+ *
+ * //          ┌─── Effect<Option<number>, never, never>>
+ * //          ▼
+ * const someSuccessResult = pipe(
+ *   Option.some(42),
+ *   Effect.transposeMapOption((value) => Effect.succeed(value * 2))
+ * )
+ * console.log(Effect.runSync(someSuccessResult))
+ * // Output: { _id: 'Option', _tag: 'Some', value: 84 }
+ * ```
+ *
+ * @since 3.14.0
+ * @category Optional Wrapping & Unwrapping
+ */
+export const transposeMapOption = dual<
+  <A, B, E = never, R = never>(
+    f: (self: A) => Effect<B, E, R>
+  ) => (self: Option.Option<A>) => Effect<Option.Option<B>, E, R>,
+  <A, B, E = never, R = never>(
+    self: Option.Option<A>,
+    f: (self: A) => Effect<B, E, R>
+  ) => Effect<Option.Option<B>, E, R>
+>(2, (self, f) => option_.isNone(self) ? succeedNone : map(f(self.value), option_.some))
+
 /**
  * @since 2.0.0
  * @category Models

packages/effect/test/Effect/optional-wrapping-unwrapping.test.ts

@@ -1,6 +1,7 @@
 import { assert, describe, it } from "@effect/vitest"
 import * as Effect from "effect/Effect"
 import * as Either from "effect/Either"
+import { pipe } from "effect/Function"
 import * as Option from "effect/Option"
 
 describe("Effect", () => {
@@ -17,6 +18,66 @@ describe("Effect", () => {
         assert.deepStrictEqual(result, Option.some(42))
       }))
   })
+  describe("transposeMapOption", () => {
+    describe("None", () => {
+      it.effect("Success", () =>
+        Effect.gen(function*() {
+          const resultDataFirst = yield* Effect.transposeMapOption(Option.none(), () => Effect.succeed(42))
+          assert.ok(Option.isNone(resultDataFirst))
+
+          const resultDataLast = yield* pipe(
+            Option.none(),
+            Effect.transposeMapOption(() => Effect.succeed(42))
+          )
+          assert.ok(Option.isNone(resultDataLast))
+        }))
+      it.effect("Failure", () =>
+        Effect.gen(function*() {
+          const resultDataFirst = yield* Effect.transposeMapOption(Option.none(), () => Effect.fail("Error"))
+          assert.ok(Option.isNone(resultDataFirst))
+
+          const resultDataLast = yield* pipe(
+            Option.none(),
+            Effect.transposeMapOption(() => Effect.fail("Error"))
+          )
+          assert.ok(Option.isNone(resultDataLast))
+        }))
+    })
+
+    describe("Some", () => {
+      describe("None", () => {
+        it.effect("Success", () =>
+          Effect.gen(function*() {
+            const resultDataFirst = yield* Effect.transposeMapOption(Option.some(42), (value) =>
+              Effect.succeed(value * 2))
+            assert.deepStrictEqual(resultDataFirst, Option.some(84))
+
+            const resultDataLast = yield* pipe(
+              Option.some(42),
+              Effect.transposeMapOption((value) =>
+                Effect.succeed(value * 2)
+              )
+            )
+            assert.deepStrictEqual(resultDataLast, Option.some(84))
+          }))
+        it.effect("Failure", () =>
+          Effect.gen(function*() {
+            const resultDataFirst = yield* pipe(
+              Effect.transposeMapOption(Option.some(42), () => Effect.fail("error")),
+              Effect.flip
+            )
+            assert.equal(resultDataFirst, "error")
+
+            const resultDataLast = yield* pipe(
+              Option.some(42),
+              Effect.transposeMapOption(() => Effect.fail("error")),
+              Effect.flip
+            )
+            assert.equal(resultDataLast, "error")
+          }))
+      })
+    })
+  })
 })
 
 describe("Either", () => {