✨ feat: Add Effected.of/from

Author: Snowflyt

README.md

@@ -1132,3 +1132,34 @@ For more complex cases where `defineHandlerFor` isn’t sufficient, you can stil
 const range = (start: number, stop: number) => range(start, stop).with(handleErrorAsResult);
 const range = (start: number, stop: number) => handleErrorAsResult(range(start, stop));
 ```
+
+### Effects without generators
+
+The fundamental logic of tinyeffect is _not_ dependent on generators. An effected program (represented as an `Effected` instance) is essentially an iterable object that implements a `[Symbol.iterator](): Iterator<Effect>` method. Although using the `effected` helper function in conjunction with a generator allows you to write more imperative-style code with `yield*` to manage effects, this is not the only way to handle them.
+
+In fact, `effected` can accept any function that returns an iterator of effects — specifically, any function that returns an object implementing a `.next()` method that outputs objects with `value` and `done` properties.
+
+It is not even necessary to use `effected` to construct an effected program. You can also create them using `Effected.of()` or `Effected.from()`. Here are two equivalent examples:
+
+```typescript
+const fib1 = (n: number): Effected<never, number> =>
+  effected(function* () {
+    if (n <= 1) return n;
+    return (yield* fib1(n - 1)) + (yield* fib1(n - 2));
+  });
+
+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));
+};
+```
+
+> [!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`.”
+
+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.

src/README.example.proof.ts

@@ -3,9 +3,9 @@
 
 import { equal, expect, extend, test, error as triggerError } from "typroof";
 
-import { defineHandlerFor, dependency, effect, effected, effectify, error } from ".";
+import { Effected, defineHandlerFor, dependency, effect, effected, effectify, error } from ".";
 
-import type { Effect, EffectFactory, Effected, InferEffect, UnhandledEffect, Unresumable } from ".";
+import type { Effect, EffectFactory, InferEffect, UnhandledEffect, Unresumable } from ".";
 
 type User = { id: number; name: string; role: "admin" | "user" };
 
@@ -616,3 +616,11 @@ test("Abstracting handlers", () => {
     expect(safeDivide2).to(equal<(a: number, b: number) => Effected<never, Option<number>>>);
   }
 });
+
+test("Effects without generators", () => {
+  expect(Effected.of(42)).not.to(triggerError);
+  expect(Effected.of(42)).to(equal<Effected<never, number>>);
+
+  expect(Effected.from(() => 42)).not.to(triggerError);
+  expect(Effected.from(() => 42)).to(equal<Effected<never, number>>);
+});

src/README.example.spec.ts

@@ -4,6 +4,7 @@
 import { expect, test, vi } from "vitest";
 
 import {
+  Effected,
   UnhandledEffectError,
   defineHandlerFor,
   dependency,
@@ -13,7 +14,7 @@ import {
   error,
 } from ".";
 
-import type { Effect, EffectFactory, Effected, Unresumable } from ".";
+import type { Effect, EffectFactory, Unresumable } from ".";
 
 test("banner", async () => {
   type User = { id: number; name: string; role: "admin" | "user" };
@@ -1108,3 +1109,25 @@ test("Abstracting handlers", () => {
     expect(safeDivide2(1, 2).runSync()).toEqual(some(0.5));
   }
 });
+
+test("Effects without generators", () => {
+  const fib1 = (n: number): Effected<never, number> =>
+    effected(function* () {
+      if (n <= 1) return n;
+      return (yield* fib1(n - 1)) + (yield* fib1(n - 2));
+    });
+
+  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));
+  };
+
+  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));
+  };
+
+  expect(fib1(10).runSync()).toBe(55);
+  expect(fib2(10).runSync()).toBe(55);
+  expect(fib3(10).runSync()).toBe(55);
+});

src/effected.spec.ts

@@ -736,3 +736,29 @@ describe("Effected#catchAllAndThrow", () => {
     expect(thrown).toBe(true);
   });
 });
+
+describe("Effected.of", () => {
+  it("should create an effected program with a single value", () => {
+    const program = Effected.of(42);
+    expect(program.runSync()).toBe(42);
+  });
+});
+
+describe("Effected.from", () => {
+  it("should create an effected program from a generator function", () => {
+    const program = Effected.from(() => 42);
+    expect(program.runSync()).toBe(42);
+  });
+
+  it("should only run the getter once", () => {
+    let count = 0;
+    const program = Effected.from(() => {
+      count++;
+      return 42;
+    });
+    expect(program.runSync()).toBe(42);
+    expect(count).toBe(1);
+    expect(program.runSync()).toBe(42);
+    expect(count).toBe(2);
+  });
+});

src/effected.ts

@@ -201,6 +201,29 @@ export class Effected<out E extends Effect, out R> implements Iterable<E, R, unk
     this.runAsyncUnsafe = () => runAsync(this as never);
   }
 
+  /**
+   * Create an {@link Effected} instance that just returns the value.
+   * @param value The value to return.
+   * @returns
+   *
+   * @since 0.1.2
+   */
+  static of<R>(value: R): Effected<never, R> {
+    return effected(() => ({ next: () => ({ done: true, value }) })) as Effected<never, R>;
+  }
+
+  /**
+   * Create an {@link Effected} instance that just returns the value from a getter.
+   * @param getter The getter to get the value.
+   * @returns
+   */
+  static from<R>(getter: () => R): Effected<never, R> {
+    return effected(() => ({ next: () => ({ done: true, value: getter() }) })) as Effected<
+      never,
+      R
+    >;
+  }
+
   /**
    * Handle an effect with a handler.
    *