Fiber

Fiber

Cooperative coroutines implemented via async generators. A fiber runs until it yields, then suspends until resumed externally or after a timer.

Constructor

import { FiberManager } from './src/fiber.js';

const fibers = new FiberManager();

---

Spawning a fiber

generatorFn must be an async generator function. It receives a FiberHandle as its argument.

fibers.spawn(id, generatorFn);

If a fiber with the same id already exists, it is killed before the new one starts.

async function* countdown(fiber) {
  for (let i = 3; i >= 0; i--) {
    console.log(i);
    await fiber.wait(1000); // suspend for 1s, then auto-resume
    if (!fiber.alive) break;
  }
}

fibers.spawn('countdown', countdown);

---

FiberHandle

Passed as the first argument to the generator function.

fiber.yield();      // suspend until fibers.resume(id) is called externally
fiber.wait(ms);     // suspend for ms milliseconds, then auto-resume
fiber.alive;        // boolean — false once the fiber is killed or finishes

yield() returns a Promise. If resume() was already called before yield() is awaited, it resolves immediately.

---

Controlling fibers

fibers.resume(id);   // resume a yielded fiber; → true if found and alive
fibers.kill(id);     // terminate immediately; → true if found
fibers.isAlive(id);  // → boolean
fibers.list();       // → ['countdown', ...]

Killing a fiber that is currently suspended on fiber.yield() resolves the pending Promise so the generator can exit cleanly.

---

Example — external resume

async function* interactive(fiber) {
  console.log('waiting...');
  await fiber.yield();
  console.log('resumed!');
}

fibers.spawn('interactive', interactive);

// Later, from an event handler or command:
fibers.resume('interactive');

---

Error handling

Unhandled errors inside a fiber are caught and logged as [Fiber:<id>] <error>. The fiber is then cleaned up.