✨ feat: Add Effected#pipe

Author: Snowflyt

README.md

@@ -1394,6 +1394,35 @@ const welcomeMessage = getUserName.zip(
 
 Just like `.andThen()`, `.zip()` also allows you to use a generator function or another effected program as the handler, which will be flattened automatically.
 
+When built-in methods aren’t sufficient for your needs, you can create custom transformers and chain them with existing effected programs using the `.pipe(...fs)` method. This allows you to apply multiple transformations in a clean, functional style (inspired by [Effect](https://effect.website/docs/getting-started/building-pipelines/#the-pipe-method)):
+
+```typescript
+const delay =
+  (ms: number) =>
+  <E extends Effect, R>(
+    effected: Effected<E, R>,
+  ): Effected<E | Default<Effect<"delay", [ms: number], void>>, R> =>
+    effect<[ms: number], void>()("delay", {
+      defaultHandler: ({ resume }, ms) => {
+        setTimeout(resume, ms);
+      },
+    })(ms).andThen(() => effected);
+
+const withLog =
+  (message: string) =>
+  <E extends Effect, R>(effected: Effected<E, R>): Effected<E, R> =>
+    effected.tap((value) => {
+      console.log(`${message}: ${String(value)}`);
+    });
+
+// Add a delay of 1000ms to the effected program
+console.log(await Effected.of(42).pipe(delay(1000)).runAsync());
+
+// You can use multiple transformers in `.pipe()`
+await Effected.of(42).pipe(delay(1000), withLog("Result")).runAsync();
+// Result: 42
+```
+
 ### Pipeline Syntax V.S. Generator Syntax
 
 Both pipeline syntax and generator syntax are valid approaches for working with effected programs in tinyeffect. Each approach has distinct advantages:

package-lock.json

@@ -47,17 +47,17 @@
   },
   "devDependencies": {
     "@commitlint/cli": "^19.8.0",
-    "@typescript-eslint/parser": "^8.27.0",
+    "@typescript-eslint/parser": "^8.28.0",
     "@vitest/coverage-v8": "^3.0.9",
     "@vitest/ui": "^3.0.9",
     "cpy-cli": "^5.0.0",
-    "effect": "^3.14.1",
-    "eslint": "^9.22.0",
+    "effect": "^3.14.2",
+    "eslint": "^9.23.0",
     "eslint-config-prettier": "^10.1.1",
-    "eslint-import-resolver-typescript": "^4.2.2",
-    "eslint-plugin-import-x": "^4.9.1",
-    "eslint-plugin-jsdoc": "^50.6.8",
-    "eslint-plugin-prettier": "^5.2.3",
+    "eslint-import-resolver-typescript": "^4.2.4",
+    "eslint-plugin-import-x": "^4.9.3",
+    "eslint-plugin-jsdoc": "^50.6.9",
+    "eslint-plugin-prettier": "^5.2.5",
     "eslint-plugin-sonarjs": "^3.0.2",
     "eslint-plugin-sort-destructure-keys": "^2.0.0",
     "globals": "^16.0.0",
@@ -69,7 +69,7 @@
     "ts-blank-space": "^0.6.1",
     "tsc-alias": "^1.8.11",
     "typescript": "^5.8.2",
-    "typescript-eslint": "^8.27.0",
+    "typescript-eslint": "^8.28.0",
     "typroof": "^0.5.1",
     "vitest": "^3.0.9"
   }

package.json

@@ -1162,6 +1162,77 @@ export class Effected<out E extends Effect, out R> implements Iterable<E, R, unk
   with(handler: (effected: any) => unknown) {
     return handler(this);
   }
+
+  /**
+   * Pipe the effected program through a series of functions.
+   * @returns
+   */
+  pipe<A, B = never>(this: A, ab: (a: A) => B): B;
+  pipe<A, B = never, C = never>(this: A, ab: (a: A) => B, bc: (b: B) => C): C;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): D;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E): E;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F): F;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G): G;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H): H;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I): I;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J): J;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K): K;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L): L;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M): M;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never, N = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N): N;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never, N = never, O = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O): O;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never, N = never, O = never, P = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P): P;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never, N = never, O = never, P = never, Q = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P, pq: (p: P) => Q): Q;
+  // prettier-ignore
+  pipe<A, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never, K = never, L = never, M = never, N = never, O = never, P = never, Q = never, R = never>(this: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P, pq: (p: P) => Q, qr: (q: Q) => R): R;
+  pipe(...args: ((value: any) => any)[]): any {
+    // Optimization inspired by Effect
+    // https://github.com/Effect-TS/effect/blob/f293e97ab2a26f45586de106b85119c5d98ab4c7/packages/effect/src/Pipeable.ts#L491-L524
+    switch (args.length) {
+      case 0:
+        return this;
+      case 1:
+        return args[0]!(this);
+      case 2:
+        return args[1]!(args[0]!(this));
+      case 3:
+        return args[2]!(args[1]!(args[0]!(this)));
+      case 4:
+        return args[3]!(args[2]!(args[1]!(args[0]!(this))));
+      case 5:
+        return args[4]!(args[3]!(args[2]!(args[1]!(args[0]!(this)))));
+      case 6:
+        return args[5]!(args[4]!(args[3]!(args[2]!(args[1]!(args[0]!(this))))));
+      case 7:
+        return args[6]!(args[5]!(args[4]!(args[3]!(args[2]!(args[1]!(args[0]!(this)))))));
+      case 8:
+        return args[7]!(args[6]!(args[5]!(args[4]!(args[3]!(args[2]!(args[1]!(args[0]!(this))))))));
+      case 9:
+        return args[8]!(
+          args[7]!(args[6]!(args[5]!(args[4]!(args[3]!(args[2]!(args[1]!(args[0]!(this)))))))),
+        );
+      default: {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        let result = this;
+        for (let i = 0, len = args.length; i < len; i++) result = args[i]!(result);
+        return result;
+      }
+    }
+  }
 }
 
 interface EffectedDraft<

src/effected.ts

@@ -927,6 +927,34 @@ test("Effects without generators", () => {
       >,
     );
   }
+
+  {
+    const delay =
+      (ms: number) =>
+      <E extends Effect, R>(
+        effected: Effected<E, R>,
+      ): Effected<E | Default<Effect<"delay", [ms: number], void>>, R> =>
+        effect<[ms: number], void>()("delay", {
+          defaultHandler: ({ resume }, ms) => {
+            setTimeout(resume, ms);
+          },
+        })(ms).andThen(() => effected);
+
+    const withLog =
+      (message: string) =>
+      <E extends Effect, R>(effected: Effected<E, R>): Effected<E, R> =>
+        effected.tap((value) => {
+          console.log(`${message}: ${String(value)}`);
+        });
+
+    expect(Effected.of(42).pipe(delay(100))).to(
+      equal<Effected<Default<Effect<"delay", [ms: number], void>>, number>>,
+    );
+
+    expect(Effected.of(42).pipe(delay(100), withLog("Result"))).to(
+      equal<Effected<Default<Effect<"delay", [ms: number], void>>, number>>,
+    );
+  }
 });
 
 test("Pipeline Syntax V.S. Generator Syntax", () => {

test/README.example.proof.ts

@@ -2,7 +2,7 @@
 
 import { expect, test, vi } from "vitest";
 
-import type { Effect, EffectFactory, Unresumable } from "../src";
+import type { Default, Effect, EffectFactory, Unresumable } from "../src";
 import {
   Effected,
   UnhandledEffectError,
@@ -1365,7 +1365,7 @@ test("Parallel execution with `Effected.all`", async () => {
   }
 });
 
-test("Effects without generators (Pipeline syntax)", () => {
+test("Effects without generators (Pipeline syntax)", async () => {
   {
     const fib1 = (n: number): Effected<never, number> =>
       effected(function* () {
@@ -1503,6 +1503,35 @@ test("Effects without generators (Pipeline syntax)", () => {
         .runSync(),
     ).toBe("Welcome Alice! Using dark theme.");
   }
+
+  // Test `.pipe(...fs)`
+  {
+    const delay =
+      (ms: number) =>
+      <E extends Effect, R>(
+        effected: Effected<E, R>,
+      ): Effected<E | Default<Effect<"delay", [ms: number], void>>, R> =>
+        effect<[ms: number], void>()("delay", {
+          defaultHandler: ({ resume }, ms) => {
+            setTimeout(resume, ms);
+          },
+        })(ms).andThen(() => effected);
+
+    const withLog =
+      (message: string) =>
+      <E extends Effect, R>(effected: Effected<E, R>): Effected<E, R> =>
+        effected.tap((value) => {
+          console.log(`${message}: ${String(value)}`);
+        });
+
+    expect(await Effected.of(42).pipe(delay(100)).runAsync()).toBe(42);
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    expect(await Effected.of(42).pipe(delay(100), withLog("Result")).runAsync()).toBe(42);
+    expect(logSpy).toHaveBeenCalledOnce();
+    expect(logSpy.mock.calls[0]![0]).toBe("Result: 42");
+    logSpy.mockRestore();
+  }
 });
 
 test("Pipeline Syntax VS Generator Syntax", async () => {