✨ feat!: Rename Effected#map to andThen for improved API conciseness

Author: Snowflyt

README.md

@@ -713,9 +713,9 @@ When you run `program.runSync()`, the output will be:
 "world"
 ```
 
-### Handling return values
+### Chaining effected programs with `.andThen()` and `.tap()`
 
-Sometimes, you may want to transform a program’s return value. Let’s revisit the `safeDivide` example:
+Sometimes, you may want to transform a program’s return value, or chain another effected program after the current one. Let’s revisit the `safeDivide` example:
 
 ```typescript
 type Raise = Unresumable<Effect<"raise", [error: unknown], never>>;
@@ -737,18 +737,20 @@ const some = <T>(value: T): Option<T> => ({ kind: "some", value });
 const none: Option<never> = { kind: "none" };
 ```
 
-We want to transform the return value of `safeDivide` into an `Option` type: if `safeDivide` returns a value normally, we return `some(value)`, otherwise, we return `none` (if the raise effect is triggered). This can be achieved with the map method:
+We want to transform the return value of `safeDivide` into an `Option` type: if `safeDivide` returns a value normally, we return `some(value)`, otherwise, we return `none` (if the raise effect is triggered). This can be achieved with the `.andThen()` method:
 
 ```typescript
 const safeDivide2 = (a: number, b: number): Effected<never, Option<number>> =>
   safeDivide(a, b)
-    .map((value) => some(value))
+    .andThen((value) => some(value))
     .terminate("raise", () => none);
 ```
 
 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.
+Similar to most other methods in tinyeffect, `.andThen()` can also be used with a generator function to chain another effected program, which can be incredibly useful in many scenarios. We’ll see many more examples of this in the following sections.
+
+Besides `.andThen(handler)`, the `.tap(handler)` method offers a useful alternative when you want to execute side effects without altering the return value. Unlike `.andThen()`, `.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:
 
@@ -883,7 +885,7 @@ const handleErrorAsResult = <R, E extends Effect, ErrorName extends string>(
   };
 
   return effected
-    .map((value) => ok(value))
+    .andThen((value) => ok(value))
     .handle(isErrorEffect, ({ effect, terminate }, message) => {
       terminate(err({ error: effect.name.slice("error:".length), message }));
     });
@@ -912,7 +914,7 @@ The `handleErrorAsResult` helper function shown above is mainly for illustration
 ```typescript
 const range3 = (start: number, stop: number) =>
   range(start, stop)
-    .map((value) => ok(value))
+    .andThen((value) => ok(value))
     .catchAll((error, message) => err({ error, message }));
 ```
 
@@ -1111,11 +1113,11 @@ const some = <T>(value: T): Option<T> => ({ kind: "some", value });
 const none: Option<never> = { kind: "none" };
 ```
 
-In previous examples, we used `.map()` and `.terminate()` to transform the return value of `safeDivide` to an `Option` type. Now, we can abstract this logic into a reusable handler:
+In previous examples, we used `.andThen()` and `.terminate()` to transform the return value of `safeDivide` to an `Option` type. Now, we can abstract this logic into a reusable handler:
 
 ```typescript
 const raiseOption = defineHandlerFor<Raise>().with((effected) =>
-  effected.map((value) => some(value)).terminate("raise", () => none),
+  effected.andThen((value) => some(value)).terminate("raise", () => none),
 );
 
 const safeDivide2 = (a: number, b: number) => safeDivide(a, b).with(raiseOption);
@@ -1154,14 +1156,14 @@ const fib2 = (n: number): Effected<never, number> => {
   if (n <= 1) return Effected.of(n);
   // Or use `Effected.from` with a getter:
   // if (n <= 1) return Effected.from(() => n);
-  return fib2(n - 1).map((a) => fib2(n - 2).map((b) => a + b));
+  return fib2(n - 1).andThen((a) => fib2(n - 2).andThen((b) => a + b));
 };
 ```
 
 > [!NOTE]
 >
 > The above example is purely for illustrative purposes and _should not_ be used in practice. While it demonstrates how effects can be handled, it mimics the behavior of a simple fib function with unnecessary complexity and overhead, which could greatly degrade performance.
 
-Understanding the definition of `fib2` may take some time, but it serves as an effective demonstration of working with effects without generators. The expression `fib2(n - 1).map((a) => fib2(n - 2).map((b) => a + b))` can be interpreted as follows: “After resolving `fib2(n - 1)`, assign the result to `a`, then resolve `fib2(n - 2)` and assign the result to `b`. Finally, return `a + b`.”
+Understanding the definition of `fib2` may take some time, but it serves as an effective demonstration of working with effects without generators. The expression `fib2(n - 1).andThen((a) => fib2(n - 2).andThen((b) => a + b))` can be interpreted as follows: “After resolving `fib2(n - 1)`, assign the result to `a`, then resolve `fib2(n - 2)` and assign the result to `b`. Finally, return `a + b`.”
 
-It’s important to note that the first `.map()` call behaves like a `flatMap` operation, as it takes a function that returns another `Effected` instance and “flattens” the result. However, in tinyeffect, the distinction between `map` and `flatMap` is not explicit — `.map()` will automatically flatten the result if it’s an `Effected` instance. This allows for seamless chaining of `.map()` calls as needed.
+It’s important to note that the first `.andThen()` call behaves like a `flatMap` operation, as it takes a function that returns another `Effected` instance and “flattens” the result. However, in tinyeffect, the distinction between `map` and `flatMap` is not explicit — `.andThen()` will automatically flatten the result if it’s an `Effected` instance, just like `Promise.prototype.then()` in JavaScript. This allows for seamless chaining of `.andThen()` calls as needed.

src/README.example.proof.ts

@@ -360,7 +360,7 @@ test("Handling return values", () => {
 
     const safeDivide2 = (a: number, b: number) =>
       safeDivide(a, b)
-        .map((value) => some(value))
+        .andThen((value) => some(value))
         .terminate("raise", () => none);
 
     expect(safeDivide2).to(equal<(a: number, b: number) => Effected<never, Option<number>>>);
@@ -470,7 +470,7 @@ test("Handling multiple effects in one handler", () => {
       };
 
       return effected
-        .map((value) => ok(value))
+        .andThen((value) => ok(value))
         .handle(isErrorEffect, ({ effect, terminate }: any, message: any) => {
           terminate(err({ error: effect.name.slice("error:".length), message }));
         });
@@ -493,7 +493,7 @@ test("Handling multiple effects in one handler", () => {
 
     const range4 = (start: number, stop: number) =>
       range(start, stop)
-        .map((value) => ok(value))
+        .andThen((value) => ok(value))
         .catchAll((error, ...args) =>
           err({ error, ...(args.length === 0 ? {} : { message: args[0] }) }),
         );
@@ -641,7 +641,7 @@ test("Abstracting handlers", () => {
     const none: Option<never> = { kind: "none" };
 
     const raiseOption = defineHandlerFor<Raise>().with((effected) =>
-      effected.map((value) => some(value)).terminate("raise", () => none),
+      effected.andThen((value) => some(value)).terminate("raise", () => none),
     );
 
     const safeDivide2 = (a: number, b: number) => safeDivide(a, b).with(raiseOption);

src/README.example.spec.ts

@@ -643,7 +643,7 @@ test("Handling return values", () => {
 
     const safeDivide2 = (a: number, b: number): Effected<never, Option<number>> =>
       safeDivide(a, b)
-        .map((value) => some(value))
+        .andThen((value) => some(value))
         .terminate("raise", () => none);
 
     expect(safeDivide2(1, 0).runSync()).toEqual(none);
@@ -753,7 +753,7 @@ test("Handling multiple effects in one handler", () => {
       };
 
       return effected
-        .map((value) => ok(value))
+        .andThen((value) => ok(value))
         .handle(isErrorEffect, ({ effect, terminate }: any, message: any) => {
           terminate(err({ error: effect.name.slice("error:".length), message }));
         });
@@ -843,7 +843,7 @@ test("Handling multiple effects in one handler", () => {
 
     const range4 = (start: number, stop: number) =>
       range(start, stop)
-        .map((value) => ok(value))
+        .andThen((value) => ok(value))
         .catchAll((error, message) => err({ error, message }));
 
     expect(
@@ -1157,7 +1157,7 @@ test("Abstracting handlers", () => {
     const none: Option<never> = { kind: "none" };
 
     const raiseOption = defineHandlerFor<Raise>().with((effected) =>
-      effected.map((value) => some(value)).terminate("raise", () => none),
+      effected.andThen((value) => some(value)).terminate("raise", () => none),
     );
 
     const safeDivide2 = (a: number, b: number) => safeDivide(a, b).with(raiseOption);
@@ -1176,12 +1176,12 @@ test("Effects without generators", () => {
 
   const fib2 = (n: number): Effected<never, number> => {
     if (n <= 1) return Effected.of(n);
-    return fib2(n - 1).map((a) => fib2(n - 2).map((b) => a + b));
+    return fib2(n - 1).andThen((a) => fib2(n - 2).andThen((b) => a + b));
   };
 
   const fib3 = (n: number): Effected<never, number> => {
     if (n <= 1) return Effected.from(() => n);
-    return fib2(n - 1).map((a) => fib2(n - 2).map((b) => a + b));
+    return fib2(n - 1).andThen((a) => fib2(n - 2).andThen((b) => a + b));
   };
 
   expect(fib1(10).runSync()).toBe(55);

src/effected.spec.ts

@@ -327,20 +327,20 @@ describe("effected", () => {
 
     expect(
       raise42(42)
-        .map(some)
+        .andThen(some)
         .catch("myError", () => none)
         .runSync(),
     ).toEqual(none);
     expect(
       raise42(21)
-        .map(some)
+        .andThen(some)
         .catch("myError", () => none)
         .runSync(),
     ).toEqual(some(21));
 
     expect(
       raise42(42)
-        .map(function* () {
+        .andThen(function* () {
           return yield* random();
         })
         .catchAll((name, msg) => ({ name, msg }))
@@ -349,7 +349,7 @@ describe("effected", () => {
     ).toEqual({ name: "myError", msg: "42 is not allowed" });
     expect(
       raise42(21)
-        .map(function* () {
+        .andThen(function* () {
           return yield* random();
         })
         .catch("myError", () => none)
@@ -359,7 +359,7 @@ describe("effected", () => {
 
     expect(
       await raise42(42)
-        .map(function* (n) {
+        .andThen(function* (n) {
           return yield* effectify(new Promise((resolve) => setTimeout(() => resolve(some(n)), 0)));
         })
         .catchAll(function* (name, msg) {
@@ -371,7 +371,7 @@ describe("effected", () => {
     ).toEqual({ name: "myError", msg: "42 is not allowed" });
     expect(
       await raise42(21)
-        .map(function* (n) {
+        .andThen(function* (n) {
           return yield* effectify(new Promise((resolve) => setTimeout(() => resolve(some(n)), 0)));
         })
         .catch("myError", () => none)
@@ -388,7 +388,7 @@ describe("effected", () => {
     const none: Option<never> = { type: "None" };
 
     const raiseOption = defineHandlerFor<Raise>().with((effected) =>
-      effected.map(some).terminate("raise", () => none),
+      effected.andThen(some).terminate("raise", () => none),
     );
 
     const raise42 = (n: number) =>

src/effected.ts

@@ -180,7 +180,7 @@ type DependencyName<E extends Effect> =
  * const none: Option<never> = { kind: "none" };
  *
  * const raiseOption = defineHandlerFor<Raise>().with((effected) =>
- *   effected.map((value) => some(value)).terminate("raise", () => none),
+ *   effected.andThen((value) => some(value)).terminate("raise", () => none),
  * );
  *
  * const safeDivide2 = (a: number, b: number) => safeDivide(a, b).with(raiseOption);
@@ -547,15 +547,16 @@ export class Effected<out E extends Effect, out R> implements Iterable<E, R, unk
   }
 
   /**
-   * Map the return value of the effected program.
-   * @param handler The function to map the return value.
+   * Chains another function or effected program after the current one, where the chained function
+   * or effected program will receive the return value of the current one.
+   * @param handler The function or effected program to chain after the current one.
    * @returns
    */
-  map<S, F extends Effect = never>(
+  andThen<S, F extends Effect = never>(
     handler: (value: R) => Generator<F, S, unknown> | Effected<F, S>,
   ): Effected<E | F, S>;
-  map<S>(handler: (value: R) => S): Effected<E, S>;
-  map(handler: (value: R) => unknown): Effected<Effect, unknown> {
+  andThen<S>(handler: (value: R) => S): Effected<E, S>;
+  andThen(handler: (value: R) => unknown): Effected<Effect, unknown> {
     const iterator = this[Symbol.iterator]();
 
     return effected(() => {
@@ -587,7 +588,7 @@ export class Effected<out E extends Effect, out R> implements Iterable<E, R, unk
   tap<F extends Effect = never>(
     handler: (value: R) => void | Generator<F, void, unknown> | Effected<F, void>,
   ): Effected<E | F, R> {
-    return this.map((value) => {
+    return this.andThen((value) => {
       const it = handler(value);
       if (!(it instanceof Effected) && !isGenerator(it)) return value;
       const iterator = it[Symbol.iterator]();
@@ -824,10 +825,10 @@ interface EffectedDraft<
     handler: E extends Effect<Name, infer Payloads> ? (...payloads: Payloads) => T : never,
   ): EffectedDraft<P, Exclude<E, Effect<Name>>, R | T>;
 
-  map<S, F extends Effect = never>(
+  andThen<S, F extends Effect = never>(
     handler: (value: R) => Generator<F, S, unknown> | Effected<F, S>,
   ): EffectedDraft<P, E | F, S>;
-  map<S>(handler: (value: R) => S): EffectedDraft<P, E, S>;
+  andThen<S>(handler: (value: R) => S): EffectedDraft<P, E, S>;
 
   tap<F extends Effect = never>(
     handler: (value: R) => void | Generator<F, void, unknown> | Effected<F, void>,

src/fib.bench.ts

@@ -32,7 +32,7 @@ const fibGenT = (n: number): Effected<never, number> =>
 
 const fibPipeT = (n: number): Effected<never, number> => {
   if (n <= 1) return Effected.of(n);
-  return fibPipeT(n - 1).map((a) => fibPipeT(n - 2).map((b) => a + b));
+  return fibPipeT(n - 1).andThen((a) => fibPipeT(n - 2).andThen((b) => a + b));
 };
 
 /* Effect */

src/koka-samples.spec.ts

@@ -65,7 +65,7 @@ const just = <T>(value: T): Maybe<T> => ({ _tag: "Just", value });
 const nothing: Maybe<never> = { _tag: "Nothing" };
 
 const raiseMaybe = defineHandlerFor<Raise>().with((effected) =>
-  effected.map((r) => just(r)).terminate("raise", () => nothing),
+  effected.andThen((r) => just(r)).terminate("raise", () => nothing),
 );
 
 test("3.2.3. Polymorphic effects", () => {
@@ -231,7 +231,7 @@ const pState = <T>(init: T) =>
   defineHandlerFor<State<T>>().with((effected) => {
     let st = init;
     return effected
-      .map((x) => [x, st] as const)
+      .andThen((x) => [x, st] as const)
       .resume("state.get", () => st)
       .resume("state.set", (x) => {
         st = x;