<Input, Provides, PlanE, PlanR>(
plan: ExecutionPlan<{
provides: Provides
input: Input
error: PlanE
requirements: PlanR
}>
): <A, E extends Input, R>(
effect: Effect<A, E, R>
) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
<A, E extends Input, R, Provides, Input, PlanE, PlanR>(
effect: Effect<A, E, R>,
plan: ExecutionPlan<{
provides: Provides
input: Input
error: PlanE
requirements: PlanR
}>
): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>Applies an ExecutionPlan to an effect, retrying with step-provided resources
until it succeeds or the plan is exhausted.
Details
Each attempt updates ExecutionPlan.CurrentMetadata (attempt and step index),
and retry timing is derived per step (the first attempt uses the remaining
attempts schedule; later retries apply the step schedule at least once).
Example (Retrying with an execution plan)
import { Context, Effect, ExecutionPlan, Layer } from "effect"
const Endpoint = Context.Service<{ url: string }>("Endpoint")
const fetchUrl = Effect.gen(function*() {
const endpoint = yield* Effect.service(Endpoint)
if (endpoint.url === "bad") {
return yield* Effect.fail("Unavailable")
}
return endpoint.url
})
const plan = ExecutionPlan.make(
{ provide: Layer.succeed(Endpoint, { url: "bad" }), attempts: 2 },
{ provide: Layer.succeed(Endpoint, { url: "good" }) }
)
const program = Effect.withExecutionPlan(fetchUrl, plan)fallback
Source effect/Effect.ts:430211 lines
export const const withExecutionPlan: {
<Input, Provides, PlanE, PlanR>(
plan: ExecutionPlan<{
provides: Provides
input: Input
error: PlanE
requirements: PlanR
}>
): <A, E extends Input, R>(
effect: Effect<A, E, R>
) => Effect<
A,
E | PlanE,
Exclude<R, Provides> | PlanR
>
<
A,
E extends Input,
R,
Provides,
Input,
PlanE,
PlanR
>(
effect: Effect<A, E, R>,
plan: ExecutionPlan<{
provides: Provides
input: Input
error: PlanE
requirements: PlanR
}>
): Effect<
A,
E | PlanE,
Exclude<R, Provides> | PlanR
>
}
Applies an ExecutionPlan to an effect, retrying with step-provided resources
until it succeeds or the plan is exhausted.
Details
Each attempt updates ExecutionPlan.CurrentMetadata (attempt and step index),
and retry timing is derived per step (the first attempt uses the remaining
attempts schedule; later retries apply the step schedule at least once).
Example (Retrying with an execution plan)
import { Context, Effect, ExecutionPlan, Layer } from "effect"
const Endpoint = Context.Service<{ url: string }>("Endpoint")
const fetchUrl = Effect.gen(function*() {
const endpoint = yield* Effect.service(Endpoint)
if (endpoint.url === "bad") {
return yield* Effect.fail("Unavailable")
}
return endpoint.url
})
const plan = ExecutionPlan.make(
{ provide: Layer.succeed(Endpoint, { url: "bad" }), attempts: 2 },
{ provide: Layer.succeed(Endpoint, { url: "good" }) }
)
const program = Effect.withExecutionPlan(fetchUrl, plan)
withExecutionPlan: {
<function (type parameter) Input in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) Provides in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) PlanE in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) PlanR in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
plan: ExecutionPlan<{
provides: Provides
input: Input
error: PlanE
requirements: PlanR
}>
(parameter) plan: {
steps: NonEmptyReadonlyArray<{ readonly provide: Context.Context<Config["provides"]> | Layer.Layer<Config["provides"], Config["error"], Config["requirements"]>; readonly attempts?: number | undefined; readonly while?: ((input: Config["input"]) =>…;
captureRequirements: Effect.Effect<ExecutionPlan<{ provides: Config["provides"]; input: Config["input"]; error: Config["error"]; requirements: never }>, never, Config["requirements"]>;
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; <…;
}
interface ExecutionPlan<Config extends { provides: any; input: any; error: any; requirements: any; }>A ExecutionPlan can be used with Effect.withExecutionPlan or Stream.withExecutionPlan, allowing you to provide different resources for each step of execution until the effect succeeds or the plan is exhausted.
Example (Defining fallback execution steps)
import { Effect, ExecutionPlan, Schedule } from "effect"
import type { Layer } from "effect"
import type { LanguageModel } from "effect/unstable/ai"
declare const layerBad: Layer.Layer<LanguageModel.LanguageModel>
declare const layerGood: Layer.Layer<LanguageModel.LanguageModel>
const ThePlan = ExecutionPlan.make(
{
// First try with the bad layer 2 times with a 3 second delay between attempts
provide: layerBad,
attempts: 2,
schedule: Schedule.spaced(3000)
},
// Then try with the bad layer 3 times with a 1 second delay between attempts
{
provide: layerBad,
attempts: 3,
schedule: Schedule.spaced(1000)
},
// Finally try with the good layer.
//
// If `attempts` is omitted, the plan will only attempt once, unless a schedule is provided.
{
provide: layerGood
}
)
declare const effect: Effect.Effect<
void,
never,
LanguageModel.LanguageModel
>
const withPlan: Effect.Effect<void> = Effect.withExecutionPlan(effect, ThePlan)
ExecutionPlan<{ provides: Providesprovides: function (type parameter) Provides in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
input: Inputinput: function (type parameter) Input in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
error: PlanEerror: function (type parameter) PlanE in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
requirements: PlanRrequirements: function (type parameter) PlanR in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) A in <A, E extends Input, R>(effect: Effect<A, E, R>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>A, function (type parameter) E in <A, E extends Input, R>(effect: Effect<A, E, R>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>E extends function (type parameter) Input in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) R in <A, E extends Input, R>(effect: Effect<A, E, R>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>R>(
effect: Effect<A, E, 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;
}
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) A in <A, E extends Input, R>(effect: Effect<A, E, R>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>A, function (type parameter) E in <A, E extends Input, R>(effect: Effect<A, E, R>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>E, function (type parameter) R in <A, E extends Input, R>(effect: Effect<A, E, R>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>R>
) => 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) A in <A, E extends Input, R>(effect: Effect<A, E, R>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>A, function (type parameter) E in <A, E extends Input, R>(effect: Effect<A, E, R>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>E | function (type parameter) PlanE in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
type Exclude<T, U> = T extends U
? never
: T
Exclude from T those types that are assignable to U
Exclude<function (type parameter) R in <A, E extends Input, R>(effect: Effect<A, E, R>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>R, function (type parameter) Provides in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) PlanR in <Input, Provides, PlanE, PlanR>(plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): <A, E extends Input, R>(effect: Effect<A, E, R>) => Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) A in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) E in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) Input in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) R in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) Provides in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) Input in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) PlanE in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) PlanR in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
effect: Effect<A, E, 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;
}
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) A in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) E in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) R in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
plan: ExecutionPlan<{
provides: Provides
input: Input
error: PlanE
requirements: PlanR
}>
(parameter) plan: {
steps: NonEmptyReadonlyArray<{ readonly provide: Context.Context<Config["provides"]> | Layer.Layer<Config["provides"], Config["error"], Config["requirements"]>; readonly attempts?: number | undefined; readonly while?: ((input: Config["input"]) =>…;
captureRequirements: Effect.Effect<ExecutionPlan<{ provides: Config["provides"]; input: Config["input"]; error: Config["error"]; requirements: never }>, never, Config["requirements"]>;
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; <…;
}
interface ExecutionPlan<Config extends { provides: any; input: any; error: any; requirements: any; }>A ExecutionPlan can be used with Effect.withExecutionPlan or Stream.withExecutionPlan, allowing you to provide different resources for each step of execution until the effect succeeds or the plan is exhausted.
Example (Defining fallback execution steps)
import { Effect, ExecutionPlan, Schedule } from "effect"
import type { Layer } from "effect"
import type { LanguageModel } from "effect/unstable/ai"
declare const layerBad: Layer.Layer<LanguageModel.LanguageModel>
declare const layerGood: Layer.Layer<LanguageModel.LanguageModel>
const ThePlan = ExecutionPlan.make(
{
// First try with the bad layer 2 times with a 3 second delay between attempts
provide: layerBad,
attempts: 2,
schedule: Schedule.spaced(3000)
},
// Then try with the bad layer 3 times with a 1 second delay between attempts
{
provide: layerBad,
attempts: 3,
schedule: Schedule.spaced(1000)
},
// Finally try with the good layer.
//
// If `attempts` is omitted, the plan will only attempt once, unless a schedule is provided.
{
provide: layerGood
}
)
declare const effect: Effect.Effect<
void,
never,
LanguageModel.LanguageModel
>
const withPlan: Effect.Effect<void> = Effect.withExecutionPlan(effect, ThePlan)
ExecutionPlan<{ provides: Providesprovides: function (type parameter) Provides in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
input: Inputinput: function (type parameter) Input in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
error: PlanEerror: function (type parameter) PlanE in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
requirements: PlanRrequirements: function (type parameter) PlanR in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
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) A in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) E in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) PlanE in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
type Exclude<T, U> = T extends U
? never
: T
Exclude from T those types that are assignable to U
Exclude<function (type parameter) R in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) Provides in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
function (type parameter) PlanR in <A, E extends Input, R, Provides, Input, PlanE, PlanR>(effect: Effect<A, E, R>, plan: ExecutionPlan<{
provides: Provides;
input: Input;
error: PlanE;
requirements: PlanR;
}>): Effect<A, E | PlanE, Exclude<R, Provides> | PlanR>
import internalExecutionPlaninternalExecutionPlan.const withExecutionPlan: {
<Input, Provides, PlanE, PlanR>(
plan: Api.ExecutionPlan<{
provides: Provides
input: Input
error: PlanE
requirements: PlanR
}>
): <A, E extends Input, R>(
effect: Effect<A, E, R>
) => Effect<
A,
E | PlanE,
Exclude<R, Provides> | PlanR
>
<
A,
E extends Input,
R,
Provides,
Input,
PlanE,
PlanR
>(
effect: Effect<A, E, R>,
plan: Api.ExecutionPlan<{
provides: Provides
input: Input
error: PlanE
requirements: PlanR
}>
): Effect<
A,
E | PlanE,
Exclude<R, Provides> | PlanR
>
}