API reference › @evolu/common › Task › Fiber

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

A Promise-backed handle to a Task started by a Run.

Await a Fiber to use the Task Result in the current control flow. The Fiber resolves with the Task Result when the Task returns normally. A Fiber returned by run(task) rejects with AbortError when the Task observes abort or when a defect panics the Run tree. Panic uses PanicAbortReason; the original defect is available on the reason for diagnostics. Use Run.abortable when abort or panic should be returned as an Err; do not catch AbortError from run(task) to model expected cancellation.

Prefer await fiber over fiber.then(). Zero-cost async stack traces are reconstructed from await suspension points and selected native Promise combinators such as Promise.all, Promise.any, and Promise.race, not from arbitrary then/catch reaction chains. Awaiting a Fiber preserves the async-function boundary that links cross-Run defect stack traces; attaching then reactions can lose those frames. See Asynchronous stack traces: why await beats Promise#then() and V8: Stack trace API. Hermes/React Native currently expose only child throw sites, so this diagnostic stack-linking benefit is unavailable there; use Run monitoring state, snapshots, and events for cross-Run diagnostics.

Child Fiber results are not implicitly aggregated into parent results. If a Task starts a child Fiber and returns before awaiting or returning it, the parent Run still waits for the child during cleanup. A later child defect panics the root Run and is reported, but the already-returned parent Result is preserved.

The run property exposes the child Run used to execute the Task. Use it for monitoring state, snapshots, events, and child lifetime inspection.

Plain Fibers do not provide abort or disposal controls. Use AbortableFiber, returned by Run.abortable or Run.daemon, for explicit abort and async disposal.

Example

import { createRun, ok, type Fiber, type Task } from "@evolu/common";

await using run = createRun();

const loadUser: Task<string> = () => ok("Ada");

const fiber = run<string, never>(loadUser);
const userResult = await fiber;
const snapshot = fiber.run.snapshot();

expectTypeOf(fiber).toEqualTypeOf<Fiber<string, never>>();
expectOk(userResult, "Ada");
expect(snapshot.id).toBe(fiber.run.id);

Extends

Extended by

Methods

catch()

catch<TResult>(onrejected?:
  | ((reason: any) =>
  | TResult
  | PromiseLike<TResult>)
  | null): Promise<
  | Result<T, E>
| TResult>;

Defined in: node_modules/@typescript/old/lib/lib.es5.d.ts:1562

Attaches a callback for only the rejection of the Promise.

Inherited from

Promise.catch;

finally()

finally(onfinally?: (() => void) | null): Promise<Result<T, E>>;

Defined in: node_modules/@typescript/old/lib/lib.es2018.promise.d.ts:27

Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.

Inherited from

Promise.finally;

then()

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

Defined in: node_modules/@typescript/old/lib/lib.es5.d.ts:1555

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

Inherited from

Promise.then;

Properties

[toStringTag]

readonly [toStringTag]: string;

Defined in: node_modules/@typescript/old/lib/lib.es2015.symbol.wellknown.d.ts:174

Inherited from

Promise.[toStringTag]

run

readonly run: Run<D>;

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

Markdown for LLMs