✨ feat: effect and effectify returns Effected instead of generator

1. `effect` and its variants now returns an effected function instead of a generator function for consistency.
2. `effectify` now returns an `Effected` instance instead of a generator for consistency.

Author: Snowflyt

README.md

@@ -397,44 +397,12 @@ export interface Effect<
 
 At runtime, only `name` and `payloads` are present, while `__returnType` serves purely at the type level to infer the effect’s return type.
 
-Using `yield*` with a factory function created by `effect` (or its variants) yields an `Effect` object. The `effect` function itself can be simplified as follows:
-
-```typescript
-function effect<Name extends string | symbol>(
-  name: Name,
-): <Payloads extends unknown[], R>(
-  ...payloads: Payloads
-) => Generator<Effect<Name, Payloads, R>, R, unknown> {
-  return function* (...payloads) {
-    return yield { name: name, payloads };
-  };
-}
-
-function error<Name extends string>(
-  name: Name,
-): <Payloads extends unknown[]>(
-  message?: string,
-) => Generator<Unresumable<Effect<`error:${Name}`, Payloads, never>>, never, unknown> {
-  return function* (...payloads) {
-    return yield { name: `error:${name}`, payloads, resumable: false };
-  };
-}
-
-function dependency<Name extends string>(
-  name: Name,
-): <R>() => Generator<Effect<`dependency:${Name}`, [], R>, R, unknown> {
-  return function* () {
-    return yield { name: `dependency:${name}`, payloads: [] };
-  };
-}
-```
-
-To keep things simple, let’s remove the type signatures and focus on the structure:
+Using `yield*` with a factory function created by `effect` (or its variants) yields an `Effect` object. To understand how it works, let’s take a look at a simplified version of the `effect` function (and its variants) in JavaScript:
 
 ```typescript
 function effect(name) {
   return function* (...payloads) {
-    return yield { name: name, payloads };
+    return yield { name, payloads };
   };
 }
 
@@ -451,6 +419,8 @@ function dependency(name) {
 }
 ```
 
+While the actual implementation of `effect` is more complex and returns a factory function that produces an `Effected` instance (instead of a generator function), the fundamental concept remains the same.
+
 The mechanism of `.runSync()` and `.runAsync()` is also straightforward. These methods iterate through the generator function, and when encountering an `Effect` object, invoke the corresponding handler registered by `.handle()`. They then either resume or terminate the generator with the value passed to `resume` or `terminate`. The actual implementation is more complex, but the concept remains consistent.
 
 > [!NOTE]
@@ -539,7 +509,7 @@ When you hover over the `raise` variable, you’ll see its `Effect` type is wrap
 ```typescript
 const raise: (
   error: unknown,
-) => Generator<Unresumable<Effect<"raise", [error: unknown], never>>, never, unknown>;
+) => Effected<Unresumable<Effect<"raise", [error: unknown], never>>, never>;
 ```
 
 Attempting to handle an unresumable effect with `.resume()` will result in a TypeScript error:
@@ -681,7 +651,7 @@ type Iterate<T> = Effect<"iterate", [value: T], void>;
 const iterate = <T>(value: T) => effect("iterate")<[value: T], void>(value);
 ```
 
-This might look complex at first, but it simply wraps the `effect` function to make it generic. `effect("iterate")` returns a generic generator function, and we pass type arguments to specialize it, then call the function with a value to yield an Effect object.
+This might look complex at first, but it simply wraps the `effect` function to make it generic. `effect("iterate")` returns a generic factory function that produces an `Effected` instance, and we pass type arguments to specialize it, then call the function with a value to yield an `Effect` object.
 
 ### Handling effects with another effected program
 
@@ -691,7 +661,7 @@ For example, consider the following program:
 
 ```typescript
 type Ask<T> = Effect<"ask", [], T>;
-const ask = <T>(): Generator<Ask<T>, T, unknown> => effect("ask")();
+const ask = <T>(): Effected<Ask<T>, T> => effect("ask")();
 
 const double = (): Effected<Ask<number>, number> =>
   effected(function* () {
@@ -1015,9 +985,8 @@ To group these together, we could define them as:
 ```typescript
 type State<T> = Effect<"state.get", [], T> | Effect<"state.set", [value: T], void>;
 const state = {
-  get: <T>(): Generator<State<T>, T, unknown> => effect("state.get")<[], T>(),
-  set: <T>(value: T): Generator<State<T>, void, unknown> =>
-    effect("state.set")<[value: T], void>(value),
+  get: <T>(): Effected<State<T>, T> => effect("state.get")<[], T>(),
+  set: <T>(value: T): Effected<State<T>, void> => effect("state.set")<[value: T], void>(value),
 };
 ```
 

src/README.example.proof.ts

@@ -206,9 +206,7 @@ test("The `Effect` type > Unresumable effects", () => {
 
   expect(raise).to(
     equal<
-      (
-        error: unknown,
-      ) => Generator<Unresumable<Effect<"raise", [error: unknown], never>>, never, unknown>
+      (error: unknown) => Effected<Unresumable<Effect<"raise", [error: unknown], never>>, never>
     >,
   );
 
@@ -296,7 +294,7 @@ test("A deep dive into `resume` and `terminate`", () => {
 test("Handling effects with another effected program", () => {
   {
     type Ask<T> = Effect<"ask", [], T>;
-    const ask = <T>(): Generator<Ask<T>, T, unknown> => effect("ask")();
+    const ask = <T>(): Effected<Ask<T>, T> => effect("ask")();
 
     const double = (): Effected<Ask<number>, number> =>
       effected(function* () {
@@ -567,9 +565,8 @@ test("Abstracting handlers", () => {
   {
     type State<T> = Effect<"state.get", [], T> | Effect<"state.set", [value: T], void>;
     const state = {
-      get: <T>(): Generator<State<T>, T, unknown> => effect("state.get")<[], T>(),
-      set: <T>(value: T): Generator<State<T>, void, unknown> =>
-        effect("state.set")<[value: T], void>(value),
+      get: <T>(): Effected<State<T>, T> => effect("state.get")<[], T>(),
+      set: <T>(value: T): Effected<State<T>, void> => effect("state.set")<[value: T], void>(value),
     };
 
     const sumDown = (sum: number = 0): Effected<State<number>, number> =>

src/README.example.spec.ts

@@ -567,7 +567,7 @@ test("A deep dive into `resume` and `terminate`", () => {
 test("Handling effects with another effected program", () => {
   {
     type Ask<T> = Effect<"ask", [], T>;
-    const ask = <T>(): Generator<Ask<T>, T, unknown> => effect("ask")();
+    const ask = <T>(): Effected<Ask<T>, T> => effect("ask")();
 
     const double = () =>
       effected(function* () {
@@ -1051,9 +1051,8 @@ test("Abstracting handlers", () => {
   {
     type State<T> = Effect<"state.get", [], T> | Effect<"state.set", [value: T], void>;
     const state = {
-      get: <T>(): Generator<State<T>, T, unknown> => effect("state.get")<[], T>(),
-      set: <T>(value: T): Generator<State<T>, void, unknown> =>
-        effect("state.set")<[value: T], void>(value),
+      get: <T>(): Effected<State<T>, T> => effect("state.get")<[], T>(),
+      set: <T>(value: T): Effected<State<T>, void> => effect("state.set")<[value: T], void>(value),
     };
 
     const sumDown = (sum: number = 0): Effected<State<number>, number> =>

src/effected.proof.ts

@@ -13,22 +13,16 @@ const log = effect("log")<unknown[], void>;
 const raise = effect("raise", { resumable: false })<[error: unknown], never>;
 
 describe("effect", () => {
-  it("should create a generator function yielding a single `Effect`", () => {
-    expect(add42).to(
-      equal<(n: number) => Generator<Effect<"add42", [n: number], number>, number, unknown>>,
-    );
-    expect(now).to(equal<() => Generator<Effect<"now", [], Date>, Date, unknown>>);
-    expect(log).to(
-      equal<(...args: unknown[]) => Generator<Effect<"log", unknown[], void>, void, unknown>>,
-    );
+  it("should create a function that returns an `Effected` instance which yields a single `Effect`", () => {
+    expect(add42).to(equal<(n: number) => Effected<Effect<"add42", [n: number], number>, number>>);
+    expect(now).to(equal<() => Effected<Effect<"now", [], Date>, Date>>);
+    expect(log).to(equal<(...args: unknown[]) => Effected<Effect<"log", unknown[], void>, void>>);
   });
 
   it("should create unresumable effects", () => {
     expect(raise).to(
       equal<
-        (
-          error: unknown,
-        ) => Generator<Unresumable<Effect<"raise", [error: unknown], never>>, never, unknown>
+        (error: unknown) => Effected<Unresumable<Effect<"raise", [error: unknown], never>>, never>
       >,
     );
   });
@@ -46,15 +40,14 @@ describe("effect", () => {
 const typeError = error("type");
 
 describe("error", () => {
-  it("should create a generator function yielding an unresumable error effect", () => {
+  it("should create a function that returns an `Effected` instance which yields a single `Effect.Error`", () => {
     expect(typeError).to(
       equal<
         (
           message?: string,
-        ) => Generator<
+        ) => Effected<
           Unresumable<Effect<"error:type", [message?: string | undefined], never>>,
-          never,
-          unknown
+          never
         >
       >,
     );
@@ -71,10 +64,8 @@ describe("error", () => {
 const askNumber = dependency("number")<number>;
 
 describe("dependency", () => {
-  it("should create a generator function yielding a single `Effect.Dependency`", () => {
-    expect(askNumber).to(
-      equal<() => Generator<Effect.Dependency<"number", number>, number, unknown>>,
-    );
+  it("should create a function that returns an `Effected` instance which yields a single `Effect.Dependency`", () => {
+    expect(askNumber).to(equal<() => Effected<Effect.Dependency<"number", number>, number>>);
   });
 
   it("should be inferred as an `Effect` type by the `InferEffect` utility type", () => {

src/effected.spec.ts

@@ -23,38 +23,41 @@ const log = effect("log")<unknown[], void>;
 const raise = effect("raise", { resumable: false })<[error: unknown], never>;
 
 describe("effect", () => {
-  it("should create a generator function yielding a single `Effect`", () => {
+  it("should create a function that returns an `Effected` instance which yields a single `Effect`", () => {
     {
-      const it = add42(42);
+      const it = add42(42)[Symbol.iterator]();
       const result = it.next();
       expect(result).toEqual({ value: { name: "add42", payloads: [42] }, done: false });
       expect(result.value).toBeInstanceOf(Effect);
       expect(it.next(84)).toEqual({ value: 84, done: true });
+      expect(it.next()).toEqual({ done: true });
     }
 
     {
-      const it = now();
+      const it = now()[Symbol.iterator]();
       const result = it.next();
       expect(result).toEqual({ value: { name: "dependency:now", payloads: [] }, done: false });
       expect(result.value).toBeInstanceOf(Effect);
       const time = new Date();
       expect(it.next(time)).toEqual({ value: time, done: true });
+      expect(it.next()).toEqual({ done: true });
     }
 
     {
-      const it = log("hello", "world", 42);
+      const it = log("hello", "world", 42)[Symbol.iterator]();
       const result = it.next();
       expect(result).toEqual({
         value: { name: "log", payloads: ["hello", "world", 42] },
         done: false,
       });
       expect(result.value).toBeInstanceOf(Effect);
       expect(it.next()).toEqual({ value: undefined, done: true });
+      expect(it.next()).toEqual({ done: true });
     }
   });
 
   it("should create unresumable effects", () => {
-    const it = raise("error");
+    const it = raise("error")[Symbol.iterator]();
     const result = it.next();
     expect(result).toEqual({
       value: { name: "raise", payloads: ["error"], resumable: false },
@@ -67,8 +70,8 @@ describe("effect", () => {
 const typeError = error("type");
 
 describe("error", () => {
-  it("should create a generator function yielding an unresumable error effect", () => {
-    const it = typeError("type error");
+  it("should create a function that returns an `Effected` instance which yields a single `Effect.Error`", () => {
+    const it = typeError("type error")[Symbol.iterator]();
     const result = it.next();
     expect(result).toEqual({
       value: { name: "error:type", payloads: ["type error"], resumable: false },
@@ -81,15 +84,31 @@ describe("error", () => {
 const askNumber = dependency("number")<number>;
 
 describe("dependency", () => {
-  it("should create a generator function yielding a single `Effect.Dependency`", () => {
-    const it = askNumber();
+  it("should create a function that returns an `Effected` instance which yields a single `Effect.Dependency`", () => {
+    const it = askNumber()[Symbol.iterator]();
     const result = it.next();
     expect(result).toEqual({
       value: { name: "dependency:number", payloads: [] },
       done: false,
     });
     expect(result.value).toBeInstanceOf(Effect);
     expect(it.next(42)).toEqual({ value: 42, done: true });
+    expect(it.next()).toEqual({ done: true });
+  });
+});
+
+describe("effectify", () => {
+  it("should transform a promise into an `Effected` instance", () => {
+    const effected = effectify(Promise.resolve(42));
+    expect(effected).toBeInstanceOf(Effected);
+    const it = effected[Symbol.iterator]();
+    const result = it.next();
+    expect(result).toEqual({
+      value: { _effectAsync: true, onComplete: expect.any(Function) },
+      done: false,
+    });
+    expect(it.next(42)).toEqual({ value: 42, done: true });
+    expect(it.next()).toEqual({ done: true });
   });
 });