The Runtime module provides the execution environment for Effect workflows. A Runtime<R> contains all the services and configuration needed to run effects.
Type
A runtime encapsulates everything needed to execute effects.
The environment type that this runtime provides
The context used as initial for forks
runtimeFlags
RuntimeFlags.RuntimeFlags
The runtime flags used as initial for forks
The fiber references used as initial for forks
Constructors
make
Creates a new Runtime.
const make: <R>(options: {
readonly context: Context.Context<R>
readonly runtimeFlags: RuntimeFlags.RuntimeFlags
readonly fiberRefs: FiberRefs.FiberRefs
}) => Runtime<R>
options.context
Context.Context<R>
required
The service context
options.runtimeFlags
RuntimeFlags.RuntimeFlags
required
The runtime flags configuration
options.fiberRefs
FiberRefs.FiberRefs
required
The fiber references
import { Runtime, Context, FiberRefs } from "effect"
const runtime = Runtime.make({
context: Context.empty(),
runtimeFlags: Runtime.defaultRuntimeFlags,
fiberRefs: FiberRefs.empty()
})
defaultRuntime
The default runtime with no services.
const defaultRuntime: Runtime<never>
A runtime with empty context
import { Runtime, Effect } from "effect"
Runtime.runSync(Runtime.defaultRuntime)(Effect.succeed(42))
// 42
Execution
runSync
Executes an effect synchronously, throwing on errors or async boundaries.
const runSync: {
<A, E, R>(runtime: Runtime<R>, effect: Effect.Effect<A, E, R>): A
<R>(runtime: Runtime<R>): <A, E>(effect: Effect.Effect<A, E, R>) => A
}
effect
Effect.Effect<A, E, R>
required
The effect to execute
The success value (throws on error)
import { Runtime, Effect } from "effect"
const result = Runtime.runSync(Runtime.defaultRuntime)(
Effect.succeed(42)
)
// 42
This method should only be used at the edges of your program. It throws exceptions for errors and async operations.
runSyncExit
Executes an effect synchronously, returning an Exit.
const runSyncExit: {
<A, E, R>(runtime: Runtime<R>, effect: Effect.Effect<A, E, R>): Exit.Exit<A, E>
<R>(runtime: Runtime<R>): <A, E>(effect: Effect.Effect<A, E, R>) => Exit.Exit<A, E>
}
effect
Effect.Effect<A, E, R>
required
The effect to execute
import { Runtime, Effect, Exit } from "effect"
const exit = Runtime.runSyncExit(Runtime.defaultRuntime)(
Effect.fail("error")
)
// Exit.fail("error")
runPromise
Runs an Effect and returns a Promise that resolves with the value or rejects with the error.
const runPromise: {
<R>(runtime: Runtime<R>): <A, E>(
effect: Effect.Effect<A, E, R>,
options?: { readonly signal?: AbortSignal }
) => Promise<A>
<R, A, E>(runtime: Runtime<R>, effect: Effect.Effect<A, E, R>, options?: {
readonly signal?: AbortSignal
}): Promise<A>
}
effect
Effect.Effect<A, E, R>
required
The effect to execute
Optional abort signal for cancellation
A promise that resolves to the success value
import { Runtime, Effect } from "effect"
const program = Effect.gen(function* () {
const a = yield* Effect.succeed(1)
const b = yield* Effect.succeed(2)
return a + b
})
Runtime.runPromise(Runtime.defaultRuntime)(program).then(console.log)
// 3
This method should only be used at the edges of your program. The promise will reject if the effect fails.
runPromiseExit
Runs an Effect and returns a Promise that resolves with the Exit state.
const runPromiseExit: {
<R>(runtime: Runtime<R>): <A, E>(
effect: Effect.Effect<A, E, R>,
options?: { readonly signal?: AbortSignal }
) => Promise<Exit.Exit<A, E>>
<R, A, E>(runtime: Runtime<R>, effect: Effect.Effect<A, E, R>, options?: {
readonly signal?: AbortSignal
}): Promise<Exit.Exit<A, E>>
}
effect
Effect.Effect<A, E, R>
required
The effect to execute
A promise that always resolves with an Exit
import { Runtime, Effect, Exit } from "effect"
Runtime.runPromiseExit(Runtime.defaultRuntime)(
Effect.fail("error")
).then(console.log)
// Exit.fail("error")
runFork
Executes an effect and returns a RuntimeFiber.
const runFork: {
<R>(runtime: Runtime<R>): <A, E>(
effect: Effect.Effect<A, E, R>,
options?: RunForkOptions
) => Fiber.RuntimeFiber<A, E>
<R, A, E>(runtime: Runtime<R>, effect: Effect.Effect<A, E, R>, options?: RunForkOptions): Fiber.RuntimeFiber<A, E>
}
effect
Effect.Effect<A, E, R>
required
The effect to execute
A handle to the running fiber
import { Runtime, Effect } from "effect"
const fiber = Runtime.runFork(Runtime.defaultRuntime)(
Effect.sleep("1 second").pipe(Effect.andThen(Effect.succeed(42)))
)
// Later: await fiber for result
runCallback
Executes an effect asynchronously, calling a callback with the exit value.
const runCallback: {
<R>(runtime: Runtime<R>): <A, E>(
effect: Effect.Effect<A, E, R>,
options?: RunCallbackOptions<A, E>
) => Cancel<A, E>
<R, A, E>(runtime: Runtime<R>, effect: Effect.Effect<A, E, R>, options?: RunCallbackOptions<A, E>): Cancel<A, E>
}
effect
Effect.Effect<A, E, R>
required
The effect to execute
options.onExit
(exit: Exit.Exit<A, E>) => void
Callback invoked with the result
A function to cancel the execution
Context Operations
provideService
Adds a service to the runtime’s context.
const provideService: {
<I, S>(tag: Context.Tag<I, S>, service: S): <R>(self: Runtime<R>) => Runtime<I | R>
<R, I, S>(self: Runtime<R>, tag: Context.Tag<I, S>, service: S): Runtime<R | I>
}
tag
Context.Tag<I, S>
required
The service tag
The service implementation
A new runtime with the added service
import { Runtime, Context } from "effect"
class Logger extends Context.Tag("Logger")<Logger, {
log: (message: string) => void
}>() {}
const runtime = Runtime.defaultRuntime.pipe(
Runtime.provideService(Logger, {
log: (msg) => console.log(msg)
})
)
updateContext
Updates the runtime’s context.
const updateContext: {
<R, R2>(f: (context: Context.Context<R>) => Context.Context<R2>): (self: Runtime<R>) => Runtime<R2>
<R, R2>(self: Runtime<R>, f: (context: Context.Context<R>) => Context.Context<R2>): Runtime<R2>
}
Fiber Refs
setFiberRef
Sets a fiber reference in the runtime.
const setFiberRef: {
<A>(fiberRef: FiberRef.FiberRef<A>, value: A): <R>(self: Runtime<R>) => Runtime<R>
<R, A>(self: Runtime<R>, fiberRef: FiberRef.FiberRef<A>, value: A): Runtime<R>
}
fiberRef
FiberRef.FiberRef<A>
required
The fiber reference to set
A new runtime with the updated fiber ref
import { Runtime, FiberRef, Effect } from "effect"
const ref = FiberRef.unsafeMake(0)
const runtime = Runtime.defaultRuntime.pipe(
Runtime.setFiberRef(ref, 42)
)
const value = Runtime.runSync(runtime)(FiberRef.get(ref))
// 42
Runtime Flags
updateRuntimeFlags
Updates the runtime flags.
const updateRuntimeFlags: {
(f: (flags: RuntimeFlags.RuntimeFlags) => RuntimeFlags.RuntimeFlags): <R>(self: Runtime<R>) => Runtime<R>
<R>(self: Runtime<R>, f: (flags: RuntimeFlags.RuntimeFlags) => RuntimeFlags.RuntimeFlags): Runtime<R>
}
enableRuntimeFlag
Enables a specific runtime flag.
const enableRuntimeFlag: {
(flag: RuntimeFlags.RuntimeFlag): <R>(self: Runtime<R>) => Runtime<R>
<R>(self: Runtime<R>, flag: RuntimeFlags.RuntimeFlag): Runtime<R>
}
disableRuntimeFlag
Disables a specific runtime flag.
const disableRuntimeFlag: {
(flag: RuntimeFlags.RuntimeFlag): <R>(self: Runtime<R>) => Runtime<R>
<R>(self: Runtime<R>, flag: RuntimeFlags.RuntimeFlag): Runtime<R>
}