@effectionx/effect-ts 0.1.0

package/effect.test.ts

@@ -0,0 +1,479 @@
+import { describe, it } from "@effectionx/bdd";
+import { Context, Effect, Exit, Fiber, Layer } from "effect";
+import { call, scoped, sleep, spawn, suspend } from "effection";
+import { expect } from "expect";
+
+import {
+  EffectionRuntime,
+  makeEffectRuntime,
+  makeEffectionRuntime,
+} from "./mod.ts";
+
+describe("@effectionx/effect-ts", () => {
+  describe("EffectRuntime - Effect inside Effection", () => {
+    describe("run()", () => {
+      it("runs a successful Effect and returns the value", function* () {
+        const runtime = yield* makeEffectRuntime();
+        const result = yield* runtime.run(Effect.succeed(42));
+        expect(result).toEqual(42);
+      });
+
+      it("runs Effect with transformations (map, flatMap)", function* () {
+        const runtime = yield* makeEffectRuntime();
+        const program = Effect.succeed(10).pipe(
+          Effect.map((n) => n * 2),
+          Effect.flatMap((n) => Effect.succeed(n + 1)),
+        );
+        const result = yield* runtime.run(program);
+        expect(result).toEqual(21);
+      });
+
+      it("throws Effect failures as JavaScript errors", function* () {
+        const runtime = yield* makeEffectRuntime();
+        let caught: unknown;
+        try {
+          yield* runtime.run(Effect.fail(new Error("boom")));
+          throw new Error("should have thrown");
+        } catch (error) {
+          caught = error;
+        }
+        expect((caught as Error).message).toEqual("boom");
+      });
+
+      it("handles Effect.die (defects)", function* () {
+        const runtime = yield* makeEffectRuntime();
+        let caught: unknown;
+        try {
+          yield* runtime.run(Effect.die("unexpected"));
+          throw new Error("should have thrown");
+        } catch (error) {
+          caught = error;
+        }
+        // Effect.die wraps in FiberFailure, check the message
+        expect(String(caught)).toContain("unexpected");
+      });
+
+      it("runs Effect.sleep correctly", function* () {
+        const runtime = yield* makeEffectRuntime();
+        const start = Date.now();
+        yield* runtime.run(Effect.sleep("50 millis"));
+        const elapsed = Date.now() - start;
+        expect(elapsed).toBeGreaterThanOrEqual(45);
+      });
+
+      it("runs Effect.gen programs", function* () {
+        const runtime = yield* makeEffectRuntime();
+        const program = Effect.gen(function* () {
+          const a = yield* Effect.succeed(1);
+          const b = yield* Effect.succeed(2);
+          return a + b;
+        });
+        const result = yield* runtime.run(program);
+        expect(result).toEqual(3);
+      });
+
+      it("works with Effect.async", function* () {
+        const runtime = yield* makeEffectRuntime();
+        const program = Effect.async<number>((resume) => {
+          const timer = setTimeout(() => resume(Effect.succeed(42)), 10);
+          return Effect.sync(() => clearTimeout(timer));
+        });
+        const result = yield* runtime.run(program);
+        expect(result).toEqual(42);
+      });
+    });
+
+    describe("runExit()", () => {
+      it("returns Exit.Success for successful Effect", function* () {
+        const runtime = yield* makeEffectRuntime();
+        const exit = yield* runtime.runExit(Effect.succeed(42));
+        expect(Exit.isSuccess(exit)).toEqual(true);
+        if (Exit.isSuccess(exit)) {
+          expect(exit.value).toEqual(42);
+        }
+      });
+
+      it("returns Exit.Failure for failed Effect", function* () {
+        const runtime = yield* makeEffectRuntime();
+        const exit = yield* runtime.runExit(Effect.fail(new Error("boom")));
+        expect(Exit.isFailure(exit)).toEqual(true);
+      });
+
+      it("returns Exit.Failure for Effect.die", function* () {
+        const runtime = yield* makeEffectRuntime();
+        const exit = yield* runtime.runExit(Effect.die("defect"));
+        expect(Exit.isFailure(exit)).toEqual(true);
+      });
+
+      it("preserves the full Cause in Exit.Failure", function* () {
+        const runtime = yield* makeEffectRuntime();
+        const error = new Error("typed error");
+        const exit = yield* runtime.runExit(Effect.fail(error));
+        expect(Exit.isFailure(exit)).toEqual(true);
+        // Can inspect Cause for error details
+      });
+    });
+
+    describe("with optional layer", () => {
+      it("provides services from the layer", function* () {
+        class Counter extends Context.Tag("Counter")<
+          Counter,
+          { value: number }
+        >() {}
+        const CounterLive = Layer.succeed(Counter, { value: 100 });
+
+        const runtime = yield* makeEffectRuntime(CounterLive);
+        // Types flow correctly - runtime is EffectRuntime<Counter>
+        const result = yield* runtime.run(
+          Effect.gen(function* () {
+            const counter = yield* Counter;
+            return counter.value;
+          }),
+        );
+        expect(result).toEqual(100);
+      });
+
+      it("supports composed layers", function* () {
+        class A extends Context.Tag("A")<A, { a: number }>() {}
+        class B extends Context.Tag("B")<B, { b: number }>() {}
+
+        const ALive = Layer.succeed(A, { a: 1 });
+        const BLive = Layer.succeed(B, { b: 2 });
+        const AppLayer = Layer.mergeAll(ALive, BLive);
+
+        const runtime = yield* makeEffectRuntime(AppLayer);
+        // Types flow correctly - runtime is EffectRuntime<A | B>
+        const result = yield* runtime.run(
+          Effect.gen(function* () {
+            const a = yield* A;
+            const b = yield* B;
+            return a.a + b.b;
+          }),
+        );
+        expect(result).toEqual(3);
+      });
+    });
+
+    describe("cancellation", () => {
+      it("interrupts Effect when Effection task is halted", function* () {
+        let finalizerRan = false;
+        let effectStarted = false;
+
+        // Run in a nested scope so we can control when it ends
+        yield* scoped(function* () {
+          const runtime = yield* makeEffectRuntime();
+
+          // Spawn so the effect runs concurrently and we can end the scope
+          yield* spawn(function* () {
+            yield* runtime.run(
+              Effect.gen(function* () {
+                effectStarted = true;
+                yield* Effect.addFinalizer(() =>
+                  Effect.sync(() => {
+                    finalizerRan = true;
+                  }),
+                );
+                yield* Effect.sleep("10 seconds");
+              }).pipe(Effect.scoped),
+            );
+          });
+
+          // Give the effect time to start before scope ends
+          yield* sleep(50);
+        });
+
+        // After the scoped block completes, the finalizer should have run
+        expect(effectStarted).toEqual(true);
+        expect(finalizerRan).toEqual(true);
+      });
+    });
+
+    describe("lifecycle", () => {
+      it("disposes ManagedRuntime when Effection scope ends", function* () {
+        let runtimeActive = false;
+
+        yield* scoped(function* () {
+          const runtime = yield* makeEffectRuntime();
+          yield* runtime.run(
+            Effect.sync(() => {
+              runtimeActive = true;
+            }),
+          );
+          // After scoped block completes, runtime should be disposed
+        });
+
+        // Runtime was active during the scope
+        expect(runtimeActive).toEqual(true);
+      });
+    });
+  });
+
+  describe("EffectionRuntime - Effection inside Effect", () => {
+    // Helper to run Effect programs with EffectionRuntime
+    const runWithEffection = <A, E>(
+      effect: Effect.Effect<A, E, EffectionRuntime>,
+    ): Promise<A> =>
+      Effect.runPromise(
+        effect.pipe(Effect.provide(makeEffectionRuntime()), Effect.scoped),
+      );
+
+    const runWithEffectionExit = <A, E>(
+      effect: Effect.Effect<A, E, EffectionRuntime>,
+    ): Promise<Exit.Exit<A, E>> =>
+      Effect.runPromiseExit(
+        effect.pipe(Effect.provide(makeEffectionRuntime()), Effect.scoped),
+      );
+
+    describe("run()", () => {
+      it("runs a successful Operation and returns the value", function* () {
+        const result = yield* call(() =>
+          runWithEffection(
+            Effect.gen(function* () {
+              const runtime = yield* EffectionRuntime;
+              return yield* runtime.run(function* () {
+                return 42;
+              });
+            }),
+          ),
+        );
+        expect(result).toEqual(42);
+      });
+
+      it("runs Operation with sleep", function* () {
+        const start = Date.now();
+        yield* call(() =>
+          runWithEffection(
+            Effect.gen(function* () {
+              const runtime = yield* EffectionRuntime;
+              yield* runtime.run(function* () {
+                yield* sleep(50);
+              });
+            }),
+          ),
+        );
+        const elapsed = Date.now() - start;
+        expect(elapsed).toBeGreaterThanOrEqual(45);
+      });
+
+      it("wraps Operation errors as UnknownException", function* () {
+        const exit = yield* call(() =>
+          runWithEffectionExit(
+            Effect.gen(function* () {
+              const runtime = yield* EffectionRuntime;
+              return yield* runtime.run(function* () {
+                throw new Error("boom");
+              });
+            }),
+          ),
+        );
+
+        expect(Exit.isFailure(exit)).toEqual(true);
+      });
+
+      it("returns an Effect", function* () {
+        const result = yield* call(() =>
+          runWithEffection(
+            Effect.gen(function* () {
+              const runtime = yield* EffectionRuntime;
+              const effect = runtime.run(function* () {
+                return 42;
+              });
+              expect(Effect.isEffect(effect)).toEqual(true);
+              return yield* effect;
+            }),
+          ),
+        );
+        expect(result).toEqual(42);
+      });
+    });
+
+    describe("cancellation", () => {
+      it("runs Effection finally blocks when Effect scope ends", function* () {
+        let finalizerRan = false;
+
+        yield* call(() =>
+          runWithEffection(
+            Effect.gen(function* () {
+              const runtime = yield* EffectionRuntime;
+              yield* runtime
+                .run(function* () {
+                  try {
+                    yield* suspend();
+                  } finally {
+                    finalizerRan = true;
+                  }
+                })
+                .pipe(Effect.fork);
+
+              yield* Effect.sleep("50 millis");
+              // Scope ends here, which should close Effection scope
+            }),
+          ),
+        );
+
+        expect(finalizerRan).toEqual(true);
+      });
+
+      it("runs Effection finally blocks when Effect fiber is interrupted", function* () {
+        let finalizerRan = false;
+
+        yield* call(() =>
+          runWithEffection(
+            Effect.gen(function* () {
+              const runtime = yield* EffectionRuntime;
+
+              const fiber = yield* runtime
+                .run(function* () {
+                  try {
+                    yield* suspend();
+                  } finally {
+                    finalizerRan = true;
+                  }
+                })
+                .pipe(Effect.fork);
+
+              yield* Effect.sleep("50 millis");
+              yield* Fiber.interrupt(fiber);
+            }),
+          ),
+        );
+
+        expect(finalizerRan).toEqual(true);
+      });
+    });
+
+    describe("lifecycle", () => {
+      it("closes Effection scope when Effect scope ends", function* () {
+        let scopeEnded = false;
+
+        yield* call(async () => {
+          await Effect.runPromise(
+            Effect.gen(function* () {
+              const runtime = yield* EffectionRuntime;
+              yield* runtime
+                .run(function* () {
+                  try {
+                    yield* suspend();
+                  } finally {
+                    scopeEnded = true;
+                  }
+                })
+                .pipe(Effect.fork);
+              yield* Effect.sleep("10 millis");
+            }).pipe(Effect.provide(makeEffectionRuntime()), Effect.scoped),
+          );
+        });
+
+        expect(scopeEnded).toEqual(true);
+      });
+    });
+  });
+
+  describe("bidirectional", () => {
+    it("Effect -> Effection: runs Effect pipeline in Effection", function* () {
+      const runtime = yield* makeEffectRuntime();
+
+      const result = yield* runtime.run(
+        Effect.succeed(42).pipe(Effect.map((n) => n * 2)),
+      );
+
+      expect(result).toEqual(84);
+    });
+
+    it("nested: Effect uses EffectionRuntime which runs Operation", function* () {
+      const effectRuntime = yield* makeEffectRuntime();
+
+      const result = yield* effectRuntime.run(
+        Effect.gen(function* () {
+          const effectionRuntime = yield* EffectionRuntime;
+          return yield* effectionRuntime.run(function* () {
+            yield* sleep(10);
+            return "nested";
+          });
+        }).pipe(Effect.provide(makeEffectionRuntime()), Effect.scoped),
+      );
+
+      expect(result).toEqual("nested");
+    });
+
+    it("deeply nested: Effection -> Effect -> Effection -> Effect", function* () {
+      const outerEffectRuntime = yield* makeEffectRuntime();
+
+      const result = yield* outerEffectRuntime.run(
+        Effect.gen(function* () {
+          const effectionRuntime = yield* EffectionRuntime;
+
+          return yield* effectionRuntime.run(function* () {
+            const innerEffectRuntime = yield* makeEffectRuntime();
+            return yield* innerEffectRuntime.run(Effect.succeed("deep"));
+          });
+        }).pipe(Effect.provide(makeEffectionRuntime()), Effect.scoped),
+      );
+
+      expect(result).toEqual("deep");
+    });
+  });
+
+  describe("resource cleanup", () => {
+    it("cleans up Effect resources when Effection scope halts", function* () {
+      const cleanupOrder: string[] = [];
+
+      yield* scoped(function* () {
+        const runtime = yield* makeEffectRuntime();
+
+        yield* spawn(function* () {
+          yield* runtime.run(
+            Effect.gen(function* () {
+              yield* Effect.acquireRelease(
+                Effect.sync(() => {
+                  cleanupOrder.push("acquired");
+                }),
+                () =>
+                  Effect.sync(() => {
+                    cleanupOrder.push("released");
+                  }),
+              );
+              // Keep the effect running so we can test cleanup
+              yield* Effect.never;
+            }).pipe(Effect.scoped),
+          );
+        });
+
+        yield* sleep(50);
+        // Scope ends here, halting the spawned task
+      });
+
+      // After scoped block completes, cleanup should have happened
+      expect(cleanupOrder).toContain("acquired");
+      expect(cleanupOrder).toContain("released");
+    });
+
+    it("cleans up Effection resources when Effect interrupts", function* () {
+      const cleanupOrder: string[] = [];
+
+      yield* call(() =>
+        Effect.runPromise(
+          Effect.gen(function* () {
+            const runtime = yield* EffectionRuntime;
+
+            const fiber = yield* runtime
+              .run(function* () {
+                try {
+                  cleanupOrder.push("started");
+                  yield* suspend();
+                } finally {
+                  cleanupOrder.push("cleaned");
+                }
+              })
+              .pipe(Effect.fork);
+
+            yield* Effect.sleep("50 millis");
+            yield* Fiber.interrupt(fiber);
+          }).pipe(Effect.provide(makeEffectionRuntime()), Effect.scoped),
+        ),
+      );
+
+      expect(cleanupOrder).toEqual(["started", "cleaned"]);
+    });
+  });
+});

package/effection-runtime.ts

@@ -0,0 +1,126 @@
+import { Context, Effect, Layer } from "effect";
+import type { UnknownException } from "effect/Cause";
+import { type Operation, type Scope, createScope } from "effection";
+
+/**
+ * A runtime for executing Effection operations inside Effect programs.
+ */
+export interface EffectionRuntime {
+  /**
+   * Run an Effection operation and return its result as an Effect.
+   *
+   * Errors thrown in the operation become `UnknownException` in Effect.
+   * The Effection scope is automatically cleaned up when the Effect completes
+   * or is interrupted.
+   *
+   * @param operation - The Effection operation (generator function) to run
+   * @returns An Effect that yields the operation's result
+   *
+   * @example
+   * ```ts
+   * const program = Effect.gen(function* () {
+   *   const runtime = yield* EffectionRuntime;
+   *   return yield* runtime.run(function* () {
+   *     yield* sleep(100);
+   *     return "hello";
+   *   });
+   * });
+   * ```
+   */
+  run<T>(operation: () => Operation<T>): Effect.Effect<T, UnknownException>;
+}
+
+/**
+ * Effect Context Tag for accessing the EffectionRuntime.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const runtime = yield* EffectionRuntime;
+ *   // use runtime.run(...)
+ * });
+ * ```
+ */
+export const EffectionRuntime =
+  Context.GenericTag<EffectionRuntime>("EffectionRuntime");
+
+/**
+ * Create an Effect Layer that provides an EffectionRuntime.
+ *
+ * The Effection scope is automatically closed when the Effect scope ends,
+ * ensuring proper cleanup of Effection resources.
+ *
+ * @param parent - Optional parent Effection scope. If provided, the runtime's
+ *                 scope will inherit all contexts from the parent scope.
+ * @returns An Effect Layer providing EffectionRuntime
+ *
+ * @example Basic usage
+ * ```ts
+ * import { Effect } from "effect";
+ * import { sleep } from "effection";
+ * import { makeEffectionRuntime, EffectionRuntime } from "@effectionx/effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const runtime = yield* EffectionRuntime;
+ *   const result = yield* runtime.run(function* () {
+ *     yield* sleep(100);
+ *     return "hello from effection";
+ *   });
+ *   return result;
+ * });
+ *
+ * await Effect.runPromise(
+ *   program.pipe(
+ *     Effect.provide(makeEffectionRuntime()),
+ *     Effect.scoped
+ *   )
+ * );
+ * ```
+ *
+ * @example With parent scope (to inherit Effection contexts)
+ * ```ts
+ * import { Effect } from "effect";
+ * import { useScope } from "effection";
+ * import { makeEffectionRuntime, EffectionRuntime } from "@effectionx/effect";
+ *
+ * function* myOperation() {
+ *   const scope = yield* useScope();
+ *   const result = yield* call(() =>
+ *     Effect.runPromise(
+ *       Effect.gen(function* () {
+ *         const runtime = yield* EffectionRuntime;
+ *         return yield* runtime.run(function* () {
+ *           // Can access Effection contexts from parent scope
+ *           return "hello";
+ *         });
+ *       }).pipe(Effect.provide(makeEffectionRuntime(scope)), Effect.scoped)
+ *     )
+ *   );
+ *   return result;
+ * }
+ * ```
+ */
+export function makeEffectionRuntime(
+  parent?: Scope,
+): Layer.Layer<EffectionRuntime> {
+  return Layer.scoped(
+    EffectionRuntime,
+    Effect.gen(function* () {
+      const [scope, close] = createScope(parent);
+
+      const run: EffectionRuntime["run"] = <T>(
+        operation: () => Operation<T>,
+      ) => {
+        return Effect.tryPromise(() => scope.run(operation));
+      };
+
+      yield* Effect.addFinalizer(() =>
+        Effect.gen(function* () {
+          yield* Effect.tryPromise(() => close()).pipe(Effect.exit);
+        }),
+      );
+
+      return { run };
+    }),
+  );
+}

package/mod.ts

@@ -0,0 +1,7 @@
+// Effect -> Effection
+export { makeEffectRuntime } from "./effect-runtime.ts";
+export type { EffectRuntime } from "./effect-runtime.ts";
+
+// Effection -> Effect
+export { EffectionRuntime, makeEffectionRuntime } from "./effection-runtime.ts";
+export type { EffectionRuntime as EffectionRuntimeType } from "./effection-runtime.ts";

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@effectionx/effect-ts",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "development": "./mod.ts",
+      "default": "./dist/mod.js"
+    }
+  },
+  "peerDependencies": {
+    "effect": "^3",
+    "effection": "^3 || ^4"
+  },
+  "devDependencies": {
+    "effect": "^3",
+    "@effectionx/bdd": "0.4.1"
+  },
+  "license": "MIT",
+  "author": "engineering@frontside.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thefrontside/effectionx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thefrontside/effectionx/issues"
+  },
+  "engines": {
+    "node": ">= 22"
+  },
+  "sideEffects": false
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["**/*.test.ts", "dist"],
+  "references": [{ "path": "../bdd" }]
+}