✨ Add inline() operation to collapse nested yield* delegation

When Effection operations compose via `yield*`, each level of nesting
creates an intermediate JavaScript generator frame. The JS engine must
unwind through every one of these frames on each call to `.next()`,
`.return()`, or `.throw()`. For deeply nested or recursive operations,
this means the cost of resuming a single yield point is O(depth),
which is the primary driver of Effection being ~34x slower than
vanilla addEventListener in benchmarks.

The `inline()` function is a zero-overhead alternative to `yield*`
that replaces nested generator delegation with an explicit iterator
stack. Instead of:

```ts
let value = yield* someOperation();
```

You write:

```ts
let value = yield inline(someOperation());
```

When the first `inline()` effect enters, it replaces the coroutine's
iterator with an `InlineIterator` that manages a stack of iterators
in a `while(true)` loop. Subsequent nested `inline()` calls are
caught within that same loop rather than creating additional generator
frames. This means a chain of 100 nested inline() calls collapses to
a single iterator stepping through a flat loop -- the reducer only
ever sees one frame regardless of depth.

Because this uses plain `yield` rather than `yield*`, there are no
intermediate generator frames at all. The trade-off is that the return
type is `unknown` (requiring a cast), and you lose the natural
generator stack trace. This is acceptable for a manual optimization
that users opt into on hot paths. A future SWC/Babel plugin could
apply this transformation automatically at build time while preserving
`yield*` syntax and type safety at the source level.

The `InlineIterator` handles the full generator protocol:

- `next()`: steps the current iterator, collapsing inline effects and
  popping the stack when sub-operations complete
- `return()`: unwinds the entire stack, giving each iterator a chance
  to run its finally blocks (critical for structured concurrency
  cleanup)
- `throw()`: propagates errors up the stack, giving each level a
  chance to catch (via `raise()` -> `propagate()`)

Author: cowboyd

inline/README.md

@@ -0,0 +1,16 @@
+# ⭐ optimize
+
+
+
+On rare occasions, `yield*`` syntax can cause a performance degradation, for example when there are many, many levels of recursion.
+
+The idea is that we can roll up any number of levels of recursion into a single yield point by transforming:
+```js
+yield* operation;
+```
+into:
+
+```js
+yield star(operation);
+```
+

inline/mod.ts

@@ -0,0 +1,152 @@
+import { Ok } from "effection";
+import type { Effect, Operation, Result } from "effection";
+
+export function inline<T>(operation: Operation<T>): Inline<T> {
+  return {
+    operation,
+    description: "inline()",
+    enter(resolve, routine) {
+      let current = routine.data.iterator;
+      if (isInlineIterator(current)) {
+        current.stack.push(current.current);
+        current.current = operation[Symbol.iterator]();
+      } else {
+        let inlined = new InlineIterator(operation, current);
+        Object.defineProperty(routine.data, "iterator", {
+          get: () => inlined,
+          configurable: true,
+        });
+      }
+      resolve(Ok() as Result<T>);
+      return (didExit) => didExit(Ok());
+    },
+  };
+}
+
+interface Inline<T> extends Effect<T> {
+  operation: Operation<T>;
+}
+
+function isInline<T>(effect: Effect<T>): effect is Inline<T> {
+  return "operation" in effect;
+}
+
+type EffectIterator = Iterator<Effect<unknown>, unknown, unknown>;
+
+function isInlineIterator(
+  iterator: EffectIterator,
+): iterator is InlineIterator {
+  return "@effectionx/inline" in iterator;
+}
+
+class InlineIterator implements EffectIterator {
+  "@effectionx/inline" = true;
+  stack: EffectIterator[];
+  current: EffectIterator;
+
+  constructor(operation: Operation<unknown>, original: EffectIterator) {
+    this.stack = [original];
+    this.current = operation[Symbol.iterator]();
+  }
+
+  next(value: unknown): IteratorResult<Effect<unknown>, unknown> {
+    let next: IteratorResult<Effect<unknown>, unknown>;
+    try {
+      next = this.current.next(value);
+    } catch (error) {
+      return this.raise(error);
+    }
+    return this.step(next);
+  }
+
+  return(value: unknown): IteratorResult<Effect<unknown>, unknown> {
+    if (this.current.return) {
+      let result: IteratorResult<Effect<unknown>, unknown>;
+      try {
+        result = this.current.return(value);
+      } catch (error) {
+        return this.raise(error);
+      }
+      if (!result.done) {
+        return result;
+      }
+    }
+
+    while (this.stack.length > 0) {
+      let top = this.stack.pop()!;
+      this.current = top;
+      if (top.return) {
+        let result: IteratorResult<Effect<unknown>, unknown>;
+        try {
+          result = top.return(value);
+        } catch (error) {
+          return this.raise(error);
+        }
+        if (!result.done) {
+          return result;
+        }
+      }
+    }
+
+    return { done: true, value };
+  }
+
+  throw(error: unknown): IteratorResult<Effect<unknown>, unknown> {
+    return this.raise(error);
+  }
+
+  step(
+    next: IteratorResult<Effect<unknown>, unknown>,
+  ): IteratorResult<Effect<unknown>, unknown> {
+    while (true) {
+      if (next.done) {
+        let top = this.stack.pop();
+        if (!top) {
+          return next;
+        }
+        this.current = top;
+        try {
+          next = this.current.next(next.value);
+        } catch (error) {
+          return this.raise(error);
+        }
+      } else {
+        let effect = next.value;
+        if (isInline(effect)) {
+          this.stack.push(this.current);
+          this.current = effect.operation[Symbol.iterator]();
+          try {
+            next = this.current.next(undefined);
+          } catch (error) {
+            return this.raise(error);
+          }
+        } else {
+          return next;
+        }
+      }
+    }
+  }
+
+  raise(error: unknown): IteratorResult<Effect<unknown>, unknown> {
+    if (this.current.throw) {
+      let next: IteratorResult<Effect<unknown>, unknown>;
+      try {
+        next = this.current.throw(error);
+      } catch (rethrown) {
+        return this.propagate(rethrown);
+      }
+      return this.step(next);
+    }
+
+    return this.propagate(error);
+  }
+
+  propagate(error: unknown): IteratorResult<Effect<unknown>, unknown> {
+    let top = this.stack.pop();
+    if (!top) {
+      throw error;
+    }
+    this.current = top;
+    return this.raise(error);
+  }
+}

inline/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@effectionx/inline",
+  "description": "Optimize deeply nested operations by collapsing yield delegation into a single iterator",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "development": "./mod.ts",
+      "default": "./dist/mod.js"
+    }
+  },
+  "peerDependencies": {
+    "effection": "^3 || ^4"
+  },
+  "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,
+  "devDependencies": {
+    "@effectionx/bdd": "workspace:*"
+  }
+}

inline/star.test.ts

@@ -0,0 +1,102 @@
+import { type Operation, run, suspend, until } from "effection";
+import { describe, it } from "node:test";
+import { inline } from "./mod.ts";
+import { expect } from "expect";
+
+describe("inline", () => {
+  it("can be used for simple operations", async () => {
+    let value = await run(function* () {
+      return yield inline(until(Promise.resolve(10)));
+    });
+    expect(value).toEqual(10);
+  });
+
+  it("can be used for operations with multiple yield points", async () => {
+    let result = await run(function* () {
+      let first = yield inline(
+        (function* () {
+          return yield inline(constant(5));
+        })(),
+      );
+      let second = yield inline(
+        (function* () {
+          return yield inline(constant(5));
+        })(),
+      );
+      return (first as number) + (second as number);
+    });
+    expect(result).toEqual(10);
+  });
+
+  it("can be used for recursive operations", async () => {
+    function* recurse(depth: number, total: number): Operation<number> {
+      if (depth > 0) {
+        return (yield inline(recurse(depth - 1, total + depth))) as number;
+      } else {
+        for (let i = 0; i < 10; i++) {
+          total += yield* until(Promise.resolve(1));
+        }
+        return total;
+      }
+    }
+    await expect(run(() => recurse(10, 0))).resolves.toEqual(65);
+  });
+
+  it("successfully halts inlined iterators", async () => {
+    let backout = 0;
+
+    function* recurse(depth: number, total: number): Operation<number> {
+      if (depth > 0) {
+        try {
+          return (yield inline(recurse(depth - 1, total + depth))) as number;
+        } finally {
+          backout += (yield inline(until(Promise.resolve(1)))) as number;
+        }
+      } else {
+        yield* suspend();
+        return 10;
+      }
+    }
+
+    let task = run(() => recurse(10, 0));
+
+    await task.halt();
+
+    expect(backout).toEqual(10);
+  });
+
+  it("handles unwinding when inlined iterators throw", async () => {
+    interface CountingError extends Error {
+      cause: number;
+    }
+
+    function* recurse(depth: number): Operation<number> {
+      if (depth > 0) {
+        try {
+          return (yield inline(recurse(depth - 1))) as number;
+        } catch (err) {
+          let counter = err as CountingError;
+          let num = (yield inline(until(Promise.resolve(1)))) as number;
+          counter.cause += num;
+          throw counter;
+        }
+      } else {
+        let error = Object.assign(new Error("bottom"), { cause: 0 });
+        throw error;
+      }
+    }
+
+    try {
+      await run(() => recurse(10));
+      throw new Error(`expected to throw, but did not`);
+    } catch (err) {
+      expect((err as CountingError).cause).toEqual(10);
+    }
+  });
+});
+
+function constant<T>(value: T): Operation<T> {
+  return {
+    [Symbol.iterator]: () => ({ next: () => ({ done: true, value }) }),
+  };
+}

inline/tsconfig.json

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

pnpm-lock.yaml

@@ -14,6 +14,7 @@ packages:
   - "raf"
   - "scope-eval"
   - "signals"
+  - "inline"
   - "stream-helpers"
   - "stream-yaml"
   - "task-buffer"

pnpm-workspace.yaml

@@ -26,6 +26,7 @@
     { "path": "raf" },
     { "path": "scope-eval" },
     { "path": "signals" },
+    { "path": "inline" },
     { "path": "stream-helpers" },
     { "path": "stream-yaml" },
     { "path": "task-buffer" },