API reference › @evolu/common › Task › Fiber

Defined in: packages/common/src/Task.ts:846

Fiber is a handle to a running Task that can be awaited, aborted, or disposed.

Example

await using run = createRun();

// Await to get Result
const result = await run(fetchData);

// Abort manually
const fiber = run(longRunningTask);
fiber.abort();
const aborted = await fiber; // Result contains AbortError (unless unabortable)

// Auto-abort with `using`
{
  using background = run(backgroundSync);
  await someOtherWork();
} // background.abort() called automatically here

// Run child tasks in fiber's scope
fiber.run(childTask);

// Monitor via the Run
fiber.run.onEvent = (event) => {
  // handle event
};

Because Fiber is a PromiseLike object, Fibers can be composed with Promise.all, Promise.race, etc.

Microtask timing: Run wraps the Task's promise with .then and .finally, which adds microtasks between Task completion and Fiber settlement. Do not write code that relies on a specific number of microtask yields between Tasks. Use explicit synchronization primitives instead.

Extends

Methods

[dispose]()

dispose: void;

Defined in: node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.esnext.disposable.d.ts:36

Inherited from

Disposable.[dispose]

abort()

abort(reason?: unknown): void;

Defined in: packages/common/src/Task.ts:894

Requests abort for this Fiber (and any child it started).

Example

const fiber = run(fetchData);
fiber.abort();
const result = await fiber; // err(AbortError)

When abort is requested, the Fiber's result becomes AbortError even if the Task completed successfully. This keeps behavior predictable — calling abort() always yields AbortError.

The optional reason is stored in AbortError.reason. Since any value can be passed, abort reasons are unknown — use typed errors for business logic. To inspect the reason, use type guards like RaceLostError.is(reason).

Abort is idempotent — calling multiple times has no additional effect beyond the first call.

getState()

getState(): RunState<T, E>;

Defined in: packages/common/src/Task.ts:897

Returns the current RunState of this Fiber's Run.

Properties

run

readonly run: Run<D>;

Defined in: packages/common/src/Task.ts:869

A Run of this Fiber.

Tasks run via this Run are aborted when the Fiber ends.

Example

const fiber = run(longRunningTask);

// helperTask is aborted when longRunningTask ends
fiber.run(helperTask);

// Monitor this Fiber's Run
fiber.run.onEvent = (event) => {
  console.log(event);
};

then

readonly then: <TResult1, TResult2>(onfulfilled?:
  | ((value: Result) =>
  | TResult1
  | PromiseLike<TResult1>)
  | null, onrejected?:
  | ((reason: any) =>
  | TResult2
  | PromiseLike<TResult2>)
| null) => PromiseLike<TResult1 | TResult2>;

Defined in: packages/common/src/Task.ts:848

Attaches callbacks for the resolution and/or rejection of the Promise.

Overrides

PromiseLike.then;
Markdown for LLMs