✨ feat: Add Effected#tap(handler)

1. Add `Effected#tap(handler)` for side effects without altering return value.

Author: Snowflyt

README.md

@@ -748,6 +748,39 @@ const safeDivide2 = (a: number, b: number): Effected<never, Option<number>> =>
 
 Now, running `safeDivide2(1, 0).runSync()` will return `none`, while `safeDivide2(1, 2).runSync()` will return `some(0.5)`.
 
+Besides `.map(handler)`, the `.tap(handler)` method offers a useful alternative when you want to execute side effects without altering the return value. Unlike `.map()`, `.tap()` ignores the return value of the handler function, ensuring the original value is preserved. This makes it ideal for operations like logging, where the action doesn’t modify the main data flow.
+
+For instance, you can use `.tap()` to simulate a `defer` effect similar to Go’s `defer` statement:
+
+```typescript
+type Defer = Effect<"defer", [fn: () => void], void>;
+const defer: EffectFactory<Defer> = effect("defer");
+
+const deferHandler = defineHandlerFor<Defer>().with((effected) => {
+  const deferredActions: Array<() => void> = [];
+
+  return effected
+    .resume("defer", (fn) => {
+      deferredActions.push(fn);
+    })
+    .tap(() => {
+      deferredActions.forEach((fn) => fn());
+    });
+});
+
+const program = effected(function* () {
+  yield* defer(() => console.log("Deferred action"));
+  console.log("Normal action");
+}).with(deferHandler);
+```
+
+When you run `program.runSync()`, you’ll see the following output:
+
+```text
+Normal action
+Deferred action
+```
+
 ### Handling multiple effects in one handler
 
 Imagine we have the following setup:

src/README.example.proof.ts

@@ -331,28 +331,54 @@ test("Handling effects with another effected program", () => {
 });
 
 test("Handling return values", () => {
-  type Raise = Unresumable<Effect<"raise", [error: unknown], never>>;
-  const raise: EffectFactory<Raise> = effect("raise", { resumable: false });
+  {
+    type Raise = Unresumable<Effect<"raise", [error: unknown], never>>;
+    const raise: EffectFactory<Raise> = effect("raise", { resumable: false });
 
-  const safeDivide = (a: number, b: number) =>
-    effected(function* () {
-      if (b === 0) return yield* raise("Division by zero");
-      return a / b;
-    });
+    const safeDivide = (a: number, b: number) =>
+      effected(function* () {
+        if (b === 0) return yield* raise("Division by zero");
+        return a / b;
+      });
 
-  expect(safeDivide).to(equal<(a: number, b: number) => Effected<Raise, number>>);
+    expect(safeDivide).to(equal<(a: number, b: number) => Effected<Raise, number>>);
 
-  type Option<T> = { kind: "some"; value: T } | { kind: "none" };
+    type Option<T> = { kind: "some"; value: T } | { kind: "none" };
 
-  const some = <T>(value: T): Option<T> => ({ kind: "some", value });
-  const none: Option<never> = { kind: "none" };
+    const some = <T>(value: T): Option<T> => ({ kind: "some", value });
+    const none: Option<never> = { kind: "none" };
 
-  const safeDivide2 = (a: number, b: number) =>
-    safeDivide(a, b)
-      .map((value) => some(value))
-      .terminate("raise", () => none);
+    const safeDivide2 = (a: number, b: number) =>
+      safeDivide(a, b)
+        .map((value) => some(value))
+        .terminate("raise", () => none);
 
-  expect(safeDivide2).to(equal<(a: number, b: number) => Effected<never, Option<number>>>);
+    expect(safeDivide2).to(equal<(a: number, b: number) => Effected<never, Option<number>>>);
+  }
+
+  {
+    type Defer = Effect<"defer", [fn: () => void], void>;
+    const defer: EffectFactory<Defer> = effect("defer");
+
+    const deferHandler = defineHandlerFor<Defer>().with((effected) => {
+      const deferredActions: Array<() => void> = [];
+
+      return effected
+        .resume("defer", (fn) => {
+          deferredActions.push(fn);
+        })
+        .tap(() => {
+          deferredActions.forEach((fn) => fn());
+        });
+    });
+
+    const program = effected(function* () {
+      yield* defer(() => console.log("Deferred action"));
+      console.log("Normal action");
+    }).with(deferHandler);
+
+    expect(program).to(equal<Effected<never, void>>);
+  }
 });
 
 test("Handling multiple effects in one handler", () => {

src/README.example.spec.ts

@@ -624,27 +624,65 @@ test("Handling effects with another effected program", () => {
 });
 
 test("Handling return values", () => {
-  type Raise = Unresumable<Effect<"raise", [error: unknown], never>>;
-  const raise: EffectFactory<Raise> = effect("raise", { resumable: false });
+  {
+    type Raise = Unresumable<Effect<"raise", [error: unknown], never>>;
+    const raise: EffectFactory<Raise> = effect("raise", { resumable: false });
 
-  const safeDivide = (a: number, b: number): Effected<Raise, number> =>
-    effected(function* () {
-      if (b === 0) return yield* raise("Division by zero");
-      return a / b;
-    });
+    const safeDivide = (a: number, b: number): Effected<Raise, number> =>
+      effected(function* () {
+        if (b === 0) return yield* raise("Division by zero");
+        return a / b;
+      });
 
-  type Option<T> = { kind: "some"; value: T } | { kind: "none" };
+    type Option<T> = { kind: "some"; value: T } | { kind: "none" };
+
+    const some = <T>(value: T): Option<T> => ({ kind: "some", value });
+    const none: Option<never> = { kind: "none" };
+
+    const safeDivide2 = (a: number, b: number): Effected<never, Option<number>> =>
+      safeDivide(a, b)
+        .map((value) => some(value))
+        .terminate("raise", () => none);
 
-  const some = <T>(value: T): Option<T> => ({ kind: "some", value });
-  const none: Option<never> = { kind: "none" };
+    expect(safeDivide2(1, 0).runSync()).toEqual(none);
+    expect(safeDivide2(1, 2).runSync()).toEqual(some(0.5));
+  }
+
+  {
+    type Defer = Effect<"defer", [fn: () => void], void>;
+    const defer: EffectFactory<Defer> = effect("defer");
 
-  const safeDivide2 = (a: number, b: number): Effected<never, Option<number>> =>
-    safeDivide(a, b)
-      .map((value) => some(value))
-      .terminate("raise", () => none);
+    const deferHandler = defineHandlerFor<Defer>().with((effected) => {
+      const deferredActions: Array<() => void> = [];
 
-  expect(safeDivide2(1, 0).runSync()).toEqual(none);
-  expect(safeDivide2(1, 2).runSync()).toEqual(some(0.5));
+      return effected
+        .resume("defer", (fn) => {
+          deferredActions.push(fn);
+        })
+        .tap(() => {
+          deferredActions.forEach((fn) => fn());
+        });
+    });
+
+    const program = effected(function* () {
+      yield* defer(() => console.log("Deferred action"));
+      console.log("Normal action");
+    }).with(deferHandler);
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    program.runSync();
+    expect(logSpy.mock.calls).toMatchInlineSnapshot(`
+      [
+        [
+          "Normal action",
+        ],
+        [
+          "Deferred action",
+        ],
+      ]
+    `);
+    logSpy.mockRestore();
+  }
 });
 
 test("Handling multiple effects in one handler", () => {

src/effected.spec.ts

@@ -621,6 +621,49 @@ describe("effected", () => {
   });
 });
 
+describe("Effected#tap", () => {
+  it("should run a side effect and return the original value", () => {
+    const logs: unknown[][] = [];
+    expect(
+      Effected.of(42)
+        .tap((value) => {
+          logs.push(["tap", value]);
+          return value + 1;
+        })
+        .runSync(),
+    ).toBe(42);
+    expect(logs).toEqual([["tap", 42]]);
+  });
+
+  it("should run a side effect with other effects", () => {
+    const logs: unknown[][] = [];
+    expect(
+      Effected.of(42)
+        .tap(function* (value) {
+          yield* log("tap", value);
+          return (value + 1) as unknown as void;
+        })
+        .resume("log", (...args) => Array.prototype.push.apply(logs, args))
+        .runSync(),
+    ).toBe(42);
+    expect(logs).toEqual(["tap", 42]);
+
+    logs.length = 0;
+    expect(
+      Effected.of(42)
+        .tap((value) =>
+          effected(function* () {
+            yield* log("tap", value);
+            return (value + 1) as unknown as void;
+          }),
+        )
+        .resume("log", (...args) => Array.prototype.push.apply(logs, args))
+        .runSync(),
+    ).toBe(42);
+    expect(logs).toEqual(["tap", 42]);
+  });
+});
+
 describe("Effected#catchAndThrow", () => {
   const typeError = error("type");
 

src/effected.ts

@@ -670,6 +670,29 @@ export class Effected<out E extends Effect, out R> implements Iterable<E, R, unk
     });
   }
 
+  /**
+   * Tap the return value of the effected program.
+   * @param handler The function to tap the return value.
+   * @returns
+   *
+   * @since 0.2.1
+   */
+  tap<F extends Effect = never>(handler: (value: R) => Effected<F, void>): Effected<E | F, R>;
+  tap<F extends Effect = never>(
+    handler: (value: R) => Generator<F, void, unknown>,
+  ): Effected<E | F, R>;
+  tap(handler: (value: R) => void): Effected<E, R>;
+  tap(handler: (value: R) => unknown): Effected<E, unknown> {
+    return this.map((value) => {
+      const it = handler(value);
+      if (!(it instanceof Effected) && !isGenerator(it)) return value;
+      return (function* () {
+        yield* it;
+        return value;
+      })();
+    });
+  }
+
   /**
    * Catch an error effect with a handler.
    *
@@ -1062,6 +1085,16 @@ interface EffectedDraft<
     <S>(handler: (value: R) => S): EffectedDraft<P, E, S>;
   };
 
+  readonly tap: {
+    <F extends Effect = never>(
+      handler: (value: R) => Effected<F, void>,
+    ): EffectedDraft<P, E | F, R>;
+    <F extends Effect = never>(
+      handler: (value: R) => Generator<F, void, unknown>,
+    ): EffectedDraft<P, E | F, R>;
+    (handler: (value: R) => void): EffectedDraft<P, E, R>;
+  };
+
   readonly catch: {
     <Name extends ErrorName<E>, T, F extends Effect = never>(
       effect: Name,