<A, E>(self: FiberHandle<A, E>): <R = never>() => Effect.Effect<
<XE extends E, XA extends A>(
effect: Effect.Effect<XA, XE, R>,
options?:
| {
readonly signal?: AbortSignal | undefined
readonly scheduler?: Scheduler | undefined
readonly onlyIfMissing?: boolean | undefined
readonly propagateInterruption?: boolean | undefined
}
| undefined
) => Promise<XA>,
never,
R
>Captures the current runtime and returns a function for running effects in
an existing FiberHandle as Promises.
Details
Each call stores the forked fiber in the handle and interrupts the previous
fiber unless onlyIfMissing is set. The Promise resolves with the effect's
success value or rejects with the squashed failure cause.
Example (Capturing a runtime for promises)
import { Effect, FiberHandle } from "effect"
Effect.gen(function*() {
const handle = yield* FiberHandle.make()
const runPromise = yield* FiberHandle.runtimePromise(handle)<never>()
// Run an effect and get a promise
const promise = runPromise(Effect.succeed("hello"))
const result = yield* Effect.promise(() => promise)
console.log(result) // "hello"
})combinators
Source effect/FiberHandle.ts:71440 lines
export const const runtimePromise: <A, E>(
self: FiberHandle<A, E>
) => <R = never>() => Effect.Effect<
<XE extends E, XA extends A>(
effect: Effect.Effect<XA, XE, R>,
options?:
| {
readonly signal?:
| AbortSignal
| undefined
readonly scheduler?:
| Scheduler
| undefined
readonly onlyIfMissing?:
| boolean
| undefined
readonly propagateInterruption?:
| boolean
| undefined
}
| undefined
) => Promise<XA>,
never,
R
>
Captures the current runtime and returns a function for running effects in
an existing FiberHandle as Promises.
Details
Each call stores the forked fiber in the handle and interrupts the previous
fiber unless onlyIfMissing is set. The Promise resolves with the effect's
success value or rejects with the squashed failure cause.
Example (Capturing a runtime for promises)
import { Effect, FiberHandle } from "effect"
Effect.gen(function*() {
const handle = yield* FiberHandle.make()
const runPromise = yield* FiberHandle.runtimePromise(handle)<never>()
// Run an effect and get a promise
const promise = runPromise(Effect.succeed("hello"))
const result = yield* Effect.promise(() => promise)
console.log(result) // "hello"
})
runtimePromise = <function (type parameter) A in <A, E>(self: FiberHandle<A, E>): <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
function (type parameter) E in <A, E>(self: FiberHandle<A, E>): <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
self: FiberHandle<A, E>(parameter) self: {
deferred: Deferred.Deferred<void, unknown>;
state: { readonly _tag: "Open"; fiber: Fiber.Fiber<A, E> | undefined } | { readonly _tag: "Closed" };
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
interface FiberHandle<out A = unknown, out E = unknown>Scoped handle that manages at most one fiber, interrupts the current fiber
when the handle's scope closes, and removes managed fibers from the handle
when they complete.
Example (Managing a single fiber)
import { Effect, Fiber, FiberHandle } from "effect"
Effect.gen(function*() {
// Create a FiberHandle that can hold fibers producing strings
const handle = yield* FiberHandle.make<string, never>()
// The handle can store and manage a single fiber
const fiber = yield* FiberHandle.run(handle, Effect.succeed("hello"))
const result = yield* Fiber.await(fiber)
console.log(result) // "hello"
})
FiberHandle<function (type parameter) A in <A, E>(self: FiberHandle<A, E>): <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
function (type parameter) E in <A, E>(self: FiberHandle<A, E>): <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
function (type parameter) R in <R = never>(): Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
import EffectEffect.interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<
<function (type parameter) XE in <XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined): Promise<XA>
function (type parameter) E in <A, E>(self: FiberHandle<A, E>): <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
function (type parameter) XA in <XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined): Promise<XA>
function (type parameter) A in <A, E>(self: FiberHandle<A, E>): <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
effect: Effect.Effect<XA, XE, R>(parameter) effect: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
import EffectEffect.interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) XA in <XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined): Promise<XA>
function (type parameter) XE in <XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined): Promise<XA>
function (type parameter) R in <R = never>(): Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
options: | {
readonly signal?: AbortSignal | undefined
readonly scheduler?: Scheduler | undefined
readonly onlyIfMissing?: boolean | undefined
readonly propagateInterruption?:
| boolean
| undefined
}
| undefined
signal?: AbortSignal | undefinedsignal?: AbortSignal | undefined
readonly scheduler?: Scheduler | undefinedscheduler?: Scheduler | undefined
readonly onlyIfMissing?: boolean | undefinedonlyIfMissing?: boolean | undefined
readonly propagateInterruption?: boolean | undefinedpropagateInterruption?: boolean | undefined
}
| undefined
) => interface Promise<T>Represents the completion of an asynchronous operation
Promise<function (type parameter) XA in <XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined): Promise<XA>
function (type parameter) R in <R = never>(): Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
function (type parameter) R in <R>(): Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
import EffectEffect.const map: {
<A, B>(f: (a: A) => B): <E, R>(
self: Effect<A, E, R>
) => Effect<B, E, R>
<A, E, R, B>(
self: Effect<A, E, R>,
f: (a: A) => B
): Effect<B, E, R>
}
const runtime: <A, E>(
self: FiberHandle<A, E>
) => <R = never>() => Effect.Effect<
<XE extends E, XA extends A>(
effect: Effect.Effect<XA, XE, R>,
options?:
| {
readonly signal?:
| AbortSignal
| undefined
readonly scheduler?:
| Scheduler
| undefined
readonly onlyIfMissing?:
| boolean
| undefined
readonly propagateInterruption?:
| boolean
| undefined
}
| undefined
) => Fiber.Fiber<XA, XE>,
never,
R
>
Captures the current runtime and returns a function for forking effects into
an existing FiberHandle.
Details
Each call returns the forked fiber, stores it in the handle, and interrupts
the previous fiber unless onlyIfMissing is set.
Example (Capturing a runtime for fiber handles)
import { Context, Effect, FiberHandle } from "effect"
interface Users {
readonly _: unique symbol
}
const Users = Context.Service<Users, {
getAll: Effect.Effect<Array<unknown>>
}>("Users")
Effect.gen(function*() {
const handle = yield* FiberHandle.make()
const run = yield* FiberHandle.runtime(handle)<Users>()
// run an effect and set the fiber in the handle
run(Effect.andThen(Users, (_) => _.getAll))
// this will interrupt the previous fiber
run(Effect.andThen(Users, (_) => _.getAll))
}).pipe(
Effect.scoped // The fiber will be interrupted when the scope is closed
)
runtime(self: FiberHandle<A, E>(parameter) self: {
deferred: Deferred.Deferred<void, unknown>;
state: { readonly _tag: "Open"; fiber: Fiber.Fiber<A, E> | undefined } | { readonly _tag: "Closed" };
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
function (type parameter) R in <R>(): Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
runFork: (
effect: Effect.Effect<XA, XE, R>,
options?:
| {
readonly signal?: AbortSignal | undefined
readonly scheduler?: Scheduler | undefined
readonly onlyIfMissing?:
| boolean
| undefined
readonly propagateInterruption?:
| boolean
| undefined
}
| undefined
) => Fiber.Fiber<XA, XE>
function (type parameter) XE in <XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined): Promise<XA>
function (type parameter) E in <A, E>(self: FiberHandle<A, E>): <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
function (type parameter) XA in <XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined): Promise<XA>
function (type parameter) A in <A, E>(self: FiberHandle<A, E>): <R = never>() => Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
effect: Effect.Effect<XA, XE, R>(parameter) effect: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
import EffectEffect.interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) XA in <XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined): Promise<XA>
function (type parameter) XE in <XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined): Promise<XA>
function (type parameter) R in <R>(): Effect.Effect<(<XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined) => Promise<XA>), never, R>
options: | {
readonly signal?: AbortSignal | undefined
readonly scheduler?: Scheduler | undefined
readonly onlyIfMissing?: boolean | undefined
readonly propagateInterruption?:
| boolean
| undefined
}
| undefined
signal?: AbortSignal | undefinedsignal?: AbortSignal | undefined
readonly scheduler?: Scheduler | undefinedscheduler?: Scheduler | undefined
readonly onlyIfMissing?: boolean | undefinedonlyIfMissing?: boolean | undefined
readonly propagateInterruption?: boolean | undefinedpropagateInterruption?: boolean | undefined
}
| undefined
): interface Promise<T>Represents the completion of an asynchronous operation
Promise<function (type parameter) XA in <XE extends E, XA extends A>(effect: Effect.Effect<XA, XE, R>, options?: {
readonly signal?: AbortSignal | undefined;
readonly scheduler?: Scheduler | undefined;
readonly onlyIfMissing?: boolean | undefined;
readonly propagateInterruption?: boolean | undefined;
} | undefined): Promise<XA>
var Promise: PromiseConstructor
new <XA>(executor: (resolve: (value: XA | PromiseLike<XA>) => void, reject: (reason?: any) => void) => void) => Promise<XA>
Creates a new Promise.
Promise((resolve: (value: XA | PromiseLike<XA>) => voidresolve, reject: (reason?: any) => voidreject) =>
runFork: (
effect: Effect.Effect<XA, XE, R>,
options?:
| {
readonly signal?: AbortSignal | undefined
readonly scheduler?: Scheduler | undefined
readonly onlyIfMissing?:
| boolean
| undefined
readonly propagateInterruption?:
| boolean
| undefined
}
| undefined
) => Fiber.Fiber<XA, XE>
effect: Effect.Effect<XA, XE, R>(parameter) effect: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
options: | {
readonly signal?: AbortSignal | undefined
readonly scheduler?: Scheduler | undefined
readonly onlyIfMissing?: boolean | undefined
readonly propagateInterruption?:
| boolean
| undefined
}
| undefined
Fiber<XA, XE>.addObserver: (cb: (exit: Exit<A, E>) => void) => () => voidaddObserver((exit: Exit.Exit<XA, XE>exit) => {
if (import ExitExit.const isSuccess: <A, E>(
self: Exit<A, E>
) => self is Success<A, E>
Checks whether an Exit is a Success.
When to use
Use as a type guard to narrow Exit<A, E> to Success<A, E> and access the
value property.
Example (Narrowing to success)
import { Exit } from "effect"
const exit = Exit.succeed(42)
if (Exit.isSuccess(exit)) {
console.log(exit.value) // 42
}
isSuccess(exit: Exit.Exit<XA, XE>exit)) {
resolve: (value: XA | PromiseLike<XA>) => voidresolve(exit: Exit.Success<XA, XE>(parameter) exit: {
_tag: "Success";
value: A;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
Success<XA, XE>.value: XA extends Avalue)
} else {
reject: (reason?: any) => voidreject(import CauseCause.const squash: <E>(
self: Cause<E>
) => unknown
Collapses a Cause into a single unknown value, picking the "most
important" failure in this order:
When to use
Use to collapse a structured cause to the single value that synchronous and
promise runners would throw.
Details
- First
Fail error (the E value)
- First
Die defect
- A generic
Error("All fibers interrupted without error") for interrupt-only causes
- A generic
Error("Empty cause") for empty
This is the function used by Effect.runPromise and Effect.runSync to
decide what to throw.
Gotchas
This function is lossy. Use
prettyErrors
or iterate cause.reasons
when you need all failures.
Example (Squashing a cause)
import { Cause } from "effect"
console.log(Cause.squash(Cause.fail("error"))) // "error"
console.log(Cause.squash(Cause.die("defect"))) // "defect"
squash(exit: Exit.Failure<XA, XE>(parameter) exit: {
_tag: "Failure";
cause: Cause.Cause<E>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
Failure<XA, XE>.cause: Cause.Cause<E>(property) Failure<XA, XE>.cause: {
reasons: ReadonlyArray<Reason<E>>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
Referenced by 1 symbols