Skip to main content Link Search Menu Expand Document (external link)
effect

Fiber overview

Added in v2.0.0

Table of contents

alternatives

orElse

Returns a fiber that prefers this fiber, but falls back to the that one when this one fails. Interrupting the returned fiber will interrupt both fibers, sequentially, from left to right.

Signature

export declare const orElse: {
  <A2, E2>(that: Fiber<A2, E2>): <A, E>(self: Fiber<A, E>) => Fiber<A2 | A, E2 | E>
  <A, E, A2, E2>(self: Fiber<A, E>, that: Fiber<A2, E2>): Fiber<A | A2, E | E2>
}

Added in v2.0.0

orElseEither

Returns a fiber that prefers this fiber, but falls back to the that one when this one fails. Interrupting the returned fiber will interrupt both fibers, sequentially, from left to right.

Signature

export declare const orElseEither: {
  <A2, E2>(that: Fiber<A2, E2>): <A, E>(self: Fiber<A, E>) => Fiber<Either.Either<A2, A>, E2 | E>
  <A, E, A2, E2>(self: Fiber<A, E>, that: Fiber<A2, E2>): Fiber<Either.Either<A2, A>, E | E2>
}

Added in v2.0.0

constructors

all

Collects all fibers into a single fiber producing an in-order list of the results.

Signature

export declare const all: <A, E>(fibers: Iterable<Fiber<A, E>>) => Fiber<readonly A[], E>

Added in v2.0.0

done

A fiber that is done with the specified Exit value.

Signature

export declare const done: <A, E>(exit: Exit.Exit<A, E>) => Fiber<A, E>

Added in v2.0.0

fail

A fiber that has already failed with the specified value.

Signature

export declare const fail: <E>(error: E) => Fiber<never, E>

Added in v2.0.0

failCause

Creates a Fiber that has already failed with the specified cause.

Signature

export declare const failCause: <E>(cause: Cause.Cause<E>) => Fiber<never, E>

Added in v2.0.0

interrupted

Constructrs a Fiber that is already interrupted.

Signature

export declare const interrupted: (fiberId: FiberId.FiberId) => Fiber<never>

Added in v2.0.0

never

A fiber that never fails or succeeds.

Signature

export declare const never: Fiber<never, never>

Added in v2.0.0

roots

Returns a chunk containing all root fibers.

Signature

export declare const roots: Effect.Effect<RuntimeFiber<any, any>[], never, never>

Added in v2.0.0

succeed

Returns a fiber that has already succeeded with the specified value.

Signature

export declare const succeed: <A>(value: A) => Fiber<A, never>

Added in v2.0.0

unsafeRoots

Returns a chunk containing all root fibers.

Signature

export declare const unsafeRoots: (_: void) => Array<RuntimeFiber<any, any>>

Added in v2.0.0

void

A fiber that has already succeeded with unit.

Signature

export declare const void: Fiber<void, never>

Added in v2.0.0

conversions

fromEffect

Lifts an Effect into a Fiber.

Signature

export declare const fromEffect: <A, E>(effect: Effect.Effect<A, E, never>) => Effect.Effect<Fiber<A, E>, never, never>

Added in v2.0.0

destructors

awaitAll

Awaits on all fibers to be completed, successfully or not.

Signature

export declare const awaitAll: (fibers: Iterable<Fiber<any, any>>) => Effect.Effect<void>

Added in v2.0.0

dump

Signature

export declare const dump: <A, E>(self: RuntimeFiber<A, E>) => Effect.Effect<Fiber.Dump>

Added in v2.0.0

dumpAll

Signature

export declare const dumpAll: (fibers: Iterable<RuntimeFiber<unknown, unknown>>) => Effect.Effect<Array<Fiber.Dump>>

Added in v2.0.0

inheritAll

Inherits values from all FiberRef instances into current fiber. This will resume immediately.

Signature

export declare const inheritAll: <A, E>(self: Fiber<A, E>) => Effect.Effect<void>

Added in v2.0.0

join

Joins the fiber, which suspends the joining fiber until the result of the fiber has been determined. Attempting to join a fiber that has erred will result in a catchable error. Joining an interrupted fiber will result in an “inner interruption” of this fiber, unlike interruption triggered by another fiber, “inner interruption” can be caught and recovered.

Signature

export declare const join: <A, E>(self: Fiber<A, E>) => Effect.Effect<A, E, never>

Added in v2.0.0

joinAll

Joins all fibers, awaiting their successful completion. Attempting to join a fiber that has erred will result in a catchable error, if that error does not result from interruption.

Signature

export declare const joinAll: <A, E>(fibers: Iterable<Fiber<A, E>>) => Effect.Effect<A[], E, never>

Added in v2.0.0

pretty

Pretty-prints a RuntimeFiber.

Signature

export declare const pretty: <A, E>(self: RuntimeFiber<A, E>) => Effect.Effect<string>

Added in v2.0.0

scoped

Converts this fiber into a scoped effect. The fiber is interrupted when the scope is closed.

Signature

export declare const scoped: <A, E>(self: Fiber<A, E>) => Effect.Effect<Fiber<A, E>, never, Scope.Scope>

Added in v2.0.0

folding

match

Folds over the Fiber or RuntimeFiber.

Signature

export declare const match: {
  <A, E, Z>(options: {
    readonly onFiber: (fiber: Fiber<A, E>) => Z
    readonly onRuntimeFiber: (fiber: RuntimeFiber<A, E>) => Z
  }): (self: Fiber<A, E>) => Z
  <A, E, Z>(
    self: Fiber<A, E>,
    options: { readonly onFiber: (fiber: Fiber<A, E>) => Z; readonly onRuntimeFiber: (fiber: RuntimeFiber<A, E>) => Z }
  ): Z
}

Added in v2.0.0

getters

await

Awaits the fiber, which suspends the awaiting fiber until the result of the fiber has been determined.

Signature

export declare const await: <A, E>(self: Fiber<A, E>) => Effect.Effect<Exit.Exit<A, E>, never, never>

Added in v2.0.0

children

Retrieves the immediate children of the fiber.

Signature

export declare const children: <A, E>(self: Fiber<A, E>) => Effect.Effect<Array<RuntimeFiber<any, any>>>

Added in v2.0.0

id

The identity of the fiber.

Signature

export declare const id: <A, E>(self: Fiber<A, E>) => FiberId.FiberId

Added in v2.0.0

poll

Tentatively observes the fiber, but returns immediately if it is not already done.

Signature

export declare const poll: <A, E>(self: Fiber<A, E>) => Effect.Effect<Option.Option<Exit.Exit<A, E>>, never, never>

Added in v2.0.0

status

Returns the FiberStatus of a RuntimeFiber.

Signature

export declare const status: <A, E>(self: RuntimeFiber<A, E>) => Effect.Effect<FiberStatus.FiberStatus>

Added in v2.0.0

instances

Order

Signature

export declare const Order: order.Order<RuntimeFiber<unknown, unknown>>

Added in v2.0.0

interruption

interrupt

Interrupts the fiber from whichever fiber is calling this method. If the fiber has already exited, the returned effect will resume immediately. Otherwise, the effect will resume when the fiber exits.

Signature

export declare const interrupt: <A, E>(self: Fiber<A, E>) => Effect.Effect<Exit.Exit<A, E>, never, never>

Added in v2.0.0

interruptAll

Interrupts all fibers, awaiting their interruption.

Signature

export declare const interruptAll: (fibers: Iterable<Fiber<any, any>>) => Effect.Effect<void>

Added in v2.0.0

interruptAllAs

Interrupts all fibers as by the specified fiber, awaiting their interruption.

Signature

export declare const interruptAllAs: {
  (fiberId: FiberId.FiberId): (fibers: Iterable<Fiber<any, any>>) => Effect.Effect<void>
  (fibers: Iterable<Fiber<any, any>>, fiberId: FiberId.FiberId): Effect.Effect<void>
}

Added in v2.0.0

interruptAs

Interrupts the fiber as if interrupted from the specified fiber. If the fiber has already exited, the returned effect will resume immediately. Otherwise, the effect will resume when the fiber exits.

Signature

export declare const interruptAs: {
  (fiberId: FiberId.FiberId): <A, E>(self: Fiber<A, E>) => Effect.Effect<Exit.Exit<A, E>, never, never>
  <A, E>(self: Fiber<A, E>, fiberId: FiberId.FiberId): Effect.Effect<Exit.Exit<A, E>, never, never>
}

Added in v2.0.0

interruptAsFork

Interrupts the fiber as if interrupted from the specified fiber. If the fiber has already exited, the returned effect will resume immediately. Otherwise, the effect will resume when the fiber exits.

Signature

export declare const interruptAsFork: {
  (fiberId: FiberId.FiberId): <A, E>(self: Fiber<A, E>) => Effect.Effect<void>
  <A, E>(self: Fiber<A, E>, fiberId: FiberId.FiberId): Effect.Effect<void>
}

Added in v2.0.0

interruptFork

Interrupts the fiber from whichever fiber is calling this method. The interruption will happen in a separate daemon fiber, and the returned effect will always resume immediately without waiting.

Signature

export declare const interruptFork: <A, E>(self: Fiber<A, E>) => Effect.Effect<void>

Added in v2.0.0

mapping

map

Maps over the value the Fiber computes.

Signature

export declare const map: {
  <A, B>(f: (a: A) => B): <E>(self: Fiber<A, E>) => Fiber<B, E>
  <A, E, B>(self: Fiber<A, E>, f: (a: A) => B): Fiber<B, E>
}

Added in v2.0.0

mapEffect

Effectually maps over the value the fiber computes.

Signature

export declare const mapEffect: {
  <A, A2, E2>(f: (a: A) => Effect.Effect<A2, E2, never>): <E>(self: Fiber<A, E>) => Fiber<A2, E2 | E>
  <A, E, A2, E2>(self: Fiber<A, E>, f: (a: A) => Effect.Effect<A2, E2, never>): Fiber<A2, E | E2>
}

Added in v2.0.0

mapFiber

Passes the success of this fiber to the specified callback, and continues with the fiber that it returns.

Signature

export declare const mapFiber: {
  <E, E2, A, B>(f: (a: A) => Fiber<B, E2>): (self: Fiber<A, E>) => Effect.Effect<Fiber<B, E | E2>, never, never>
  <A, E, E2, B>(self: Fiber<A, E>, f: (a: A) => Fiber<B, E2>): Effect.Effect<Fiber<B, E | E2>, never, never>
}

Added in v2.0.0

models

Fiber (interface)

A fiber is a lightweight thread of execution that never consumes more than a whole thread (but may consume much less, depending on contention and asynchronicity). Fibers are spawned by forking effects, which run concurrently with the parent effect.

Fibers can be joined, yielding their result to other fibers, or interrupted, which terminates the fiber, safely releasing all resources.

Signature

export interface Fiber<out A, out E = never> extends Fiber.Variance<A, E>, Pipeable {
  /**
   * The identity of the fiber.
   */
  id(): FiberId.FiberId

  /**
   * Awaits the fiber, which suspends the awaiting fiber until the result of the
   * fiber has been determined.
   */
  readonly await: Effect.Effect<Exit.Exit<A, E>>

  /**
   * Retrieves the immediate children of the fiber.
   */
  readonly children: Effect.Effect<Array<Fiber.Runtime<any, any>>>

  /**
   * Inherits values from all `FiberRef` instances into current fiber. This
   * will resume immediately.
   */
  readonly inheritAll: Effect.Effect<void>

  /**
   * Tentatively observes the fiber, but returns immediately if it is not
   * already done.
   */
  readonly poll: Effect.Effect<Option.Option<Exit.Exit<A, E>>>

  /**
   * In the background, interrupts the fiber as if interrupted from the
   * specified fiber. If the fiber has already exited, the returned effect will
   * resume immediately. Otherwise, the effect will resume when the fiber exits.
   */
  interruptAsFork(fiberId: FiberId.FiberId): Effect.Effect<void>
}

Added in v2.0.0

RuntimeFiber (interface)

A runtime fiber that is executing an effect. Runtime fibers have an identity and a trace.

Signature

export interface RuntimeFiber<out A, out E = never> extends Fiber<A, E>, Fiber.RuntimeVariance<A, E> {
  /**
   * Reads the current number of ops that have occurred since the last yield
   */
  get currentOpCount(): number

  /**
   * Reads the current value of a fiber ref
   */
  getFiberRef<X>(fiberRef: FiberRef<X>): X

  /**
   * The identity of the fiber.
   */
  id(): FiberId.Runtime

  /**
   * The status of the fiber.
   */
  readonly status: Effect.Effect<FiberStatus.FiberStatus>

  /**
   * Returns the current `RuntimeFlags` the fiber is running with.
   */
  readonly runtimeFlags: Effect.Effect<RuntimeFlags.RuntimeFlags>

  /**
   * Adds an observer to the list of observers.
   */
  addObserver(observer: (exit: Exit.Exit<A, E>) => void): void

  /**
   * Removes the specified observer from the list of observers that will be
   * notified when the fiber exits.
   */
  removeObserver(observer: (exit: Exit.Exit<A, E>) => void): void

  /**
   * Retrieves all fiber refs of the fiber.
   */
  getFiberRefs(): FiberRefs.FiberRefs

  /**
   * Unsafely observes the fiber, but returns immediately if it is not
   * already done.
   */
  unsafePoll(): Exit.Exit<A, E> | null

  /**
   * In the background, interrupts the fiber as if interrupted from the
   * specified fiber. If the fiber has already exited, the returned effect will
   * resume immediately. Otherwise, the effect will resume when the fiber exits.
   */
  unsafeInterruptAsFork(fiberId: FiberId.FiberId): void
}

Added in v2.0.0

refinements

isFiber

Returns true if the specified value is a Fiber, false otherwise.

Signature

export declare const isFiber: (u: unknown) => u is Fiber<unknown, unknown>

Added in v2.0.0

isRuntimeFiber

Returns true if the specified Fiber is a RuntimeFiber, false otherwise.

Signature

export declare const isRuntimeFiber: <A, E>(self: Fiber<A, E>) => self is RuntimeFiber<A, E>

Added in v2.0.0

symbols

FiberTypeId

Signature

export declare const FiberTypeId: typeof FiberTypeId

Added in v2.0.0

FiberTypeId (type alias)

Signature

export type FiberTypeId = typeof FiberTypeId

Added in v2.0.0

RuntimeFiberTypeId

Signature

export declare const RuntimeFiberTypeId: typeof RuntimeFiberTypeId

Added in v2.0.0

RuntimeFiberTypeId (type alias)

Signature

export type RuntimeFiberTypeId = typeof RuntimeFiberTypeId

Added in v2.0.0

utilities

getCurrentFiber

Gets the current fiber if one is running.

Signature

export declare const getCurrentFiber: () => Option.Option<RuntimeFiber<any, any>>

Added in v2.0.0

utils

Fiber (namespace)

Added in v2.0.0

Descriptor (interface)

A record containing information about a Fiber.

Signature

export interface Descriptor {
  /**
   * The fiber's unique identifier.
   */
  readonly id: FiberId.FiberId
  /**
   * The status of the fiber.
   */
  readonly status: FiberStatus.FiberStatus
  /**
   * The set of fibers attempting to interrupt the fiber or its ancestors.
   */
  readonly interruptors: HashSet.HashSet<FiberId.FiberId>
}

Added in v2.0.0

Dump (interface)

Signature

export interface Dump {
  /**
   * The fiber's unique identifier.
   */
  readonly id: FiberId.Runtime
  /**
   * The status of the fiber.
   */
  readonly status: FiberStatus.FiberStatus
}

Added in v2.0.0

RuntimeVariance (interface)

Signature

export interface RuntimeVariance<out A, out E> {
  readonly [RuntimeFiberTypeId]: {
    readonly _A: Types.Covariant<A>
    readonly _E: Types.Covariant<E>
  }
}

Added in v2.0.0

Variance (interface)

Signature

export interface Variance<out A, out E> {
  readonly [FiberTypeId]: {
    readonly _A: Types.Covariant<A>
    readonly _E: Types.Covariant<E>
  }
}

Added in v2.0.0

Runtime (type alias)

Signature

export type Runtime<A, E = never> = RuntimeFiber<A, E>

Added in v2.0.0

zipping

zip

Zips this fiber and the specified fiber together, producing a tuple of their output.

Signature

export declare const zip: {
  <A2, E2>(that: Fiber<A2, E2>): <A, E>(self: Fiber<A, E>) => Fiber<[A, A2], E2 | E>
  <A, E, A2, E2>(self: Fiber<A, E>, that: Fiber<A2, E2>): Fiber<[A, A2], E | E2>
}

Added in v2.0.0

zipLeft

Same as zip but discards the output of that Fiber.

Signature

export declare const zipLeft: {
  <A2, E2>(that: Fiber<A2, E2>): <A, E>(self: Fiber<A, E>) => Fiber<A, E2 | E>
  <A, E, A2, E2>(self: Fiber<A, E>, that: Fiber<A2, E2>): Fiber<A, E | E2>
}

Added in v2.0.0

zipRight

Same as zip but discards the output of this Fiber.

Signature

export declare const zipRight: {
  <A2, E2>(that: Fiber<A2, E2>): <A, E>(self: Fiber<A, E>) => Fiber<A2, E2 | E>
  <A, E, A2, E2>(self: Fiber<A, E>, that: Fiber<A2, E2>): Fiber<A2, E | E2>
}

Added in v2.0.0

zipWith

Zips this fiber with the specified fiber, combining their results using the specified combiner function. Both joins and interruptions are performed in sequential order from left to right.

Signature

export declare const zipWith: {
  <B, E2, A, C>(that: Fiber<B, E2>, f: (a: A, b: B) => C): <E>(self: Fiber<A, E>) => Fiber<C, E2 | E>
  <A, E, B, E2, C>(self: Fiber<A, E>, that: Fiber<B, E2>, f: (a: A, b: B) => C): Fiber<C, E | E2>
}

Added in v2.0.0