ExecutionPlan
Describes ordered fallback steps for running effects or streams.
An ExecutionPlan contains one or more steps. Each step provides a Context or Layer, and may also define attempt limits, retry schedules, or predicates that decide whether to keep trying. The runtime tries steps in order until the workflow succeeds or the plan is exhausted. This module also supports merging plans and reading metadata for the active step and attempt.
Combining
Signature
declare function merge<Plans extends readonly [ExecutionPlan<any>, ExecutionPlan<any>]>(
...plans: Plans
): ExecutionPlan<{
error: Plans[number] extends ExecutionPlan<T> ? T["error"] : never;
input: PlanInput<Plans>;
provides: PlanProvides<Plans>;
requirements: Plans[number] extends ExecutionPlan<T> ? T["requirements"] : never;
}>;Constructors
Create an ExecutionPlan, which 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.
Signature
declare function make<Steps extends readonly [Step, Step]>(
...steps: Steps & { [K in string | number | symbol]: Step }
): ExecutionPlan<{
error: Steps[number]["provide"] extends Context<_P> | Layer<_P, E, _R>
? E
: never | Steps[number]["while"] extends (input: _I) => Effect<_A, _E, _R>
? _E
: never;
input: StepInput<Steps>;
provides: StepProvides<Steps>;
requirements: Steps[number]["provide"] extends Layer<_A, _E, R>
? R
: never | Steps[number]["while"] extends (input: _I) => Effect<_A, _E, R>
? R
: never | Steps[number]["schedule"] extends Schedule<_O, _I, R, never>
? R
: never;
}>;Guards
isExecutionPlan
Returns true if a value is an ExecutionPlan by checking for the ExecutionPlan.TypeId marker.
When to use
Use when accepting an unknown value and you need to narrow it to an ExecutionPlan before reading plan fields or passing it to plan-consuming APIs.
Gotchas
This is a structural marker check; it does not validate the marker value or the shape of the plan steps.
See
Signature
declare function isExecutionPlan(u: unknown): u is ExecutionPlan<any>;Metadata
Metadata describing the currently running execution-plan attempt.
Details
attempt is the current 1-based attempt number, and stepIndex is the 0-based index of the plan step currently being evaluated.
Signature
interface Metadata {
readonly attempt: number;
readonly stepIndex: number;
}Models
AttemptFailure interface
Lifecycle event emitted when an execution-plan attempt fails.
Details
cause holds the full failure cause, so defects and interruption are reported as well as expected errors. Whether the plan retries or fails over afterwards is decided by the step's attempts, while, and schedule; a following AttemptStart indicates another attempt was made.
Signature
interface AttemptFailure<E> {
readonly _tag: "AttemptFailure";
readonly attempt: number;
readonly cause: Cause<E>;
readonly duration: Duration;
readonly stepAttempt: number;
readonly stepIndex: number;
}AttemptStart interface
Lifecycle event emitted before an execution-plan attempt runs.
Details
attempt is the cumulative 1-based attempt number across all steps and matches CurrentMetadata.attempt for the same attempt. stepAttempt is the 1-based attempt number within the current step, and stepIndex is the 0-based index of the step being attempted.
Signature
interface AttemptStart {
readonly _tag: "AttemptStart";
readonly attempt: number;
readonly stepAttempt: number;
readonly stepIndex: number;
}AttemptSuccess interface
Lifecycle event emitted when an execution-plan attempt succeeds.
Details
A successful attempt completes the plan, so this is always the final event. duration is the elapsed time of the attempt.
Signature
interface AttemptSuccess {
readonly _tag: "AttemptSuccess";
readonly attempt: number;
readonly duration: Duration;
readonly stepAttempt: number;
readonly stepIndex: number;
}ConfigBase type
Base type-level configuration carried by an ExecutionPlan.
Details
provides tracks services supplied by plan steps, input tracks the error input consumed by schedules and while predicates, error tracks failures from plan layers or predicates, and requirements tracks services needed to build or run the plan.
Signature
type ConfigBase = {
error: any;
input: any;
provides: any;
requirements: any;
};Union of the lifecycle events emitted while an execution plan runs.
Details
Every AttemptStart is followed by exactly one terminal event, either AttemptSuccess or AttemptFailure. An interrupted attempt emits AttemptFailure with the interruption cause.
Signature
type Event<E> = AttemptStart | AttemptSuccess | AttemptFailure<E>;ExecutionPlan interface
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.
Signature
interface ExecutionPlan<
Config extends {
error: any;
input: any;
provides: any;
requirements: any;
},
> extends Pipeable {
readonly "~effect/ExecutionPlan": "~effect/ExecutionPlan";
readonly captureRequirements: Effect<
ExecutionPlan<{
error: Config["error"];
input: Config["input"];
provides: Config["provides"];
requirements: never;
}>,
never,
Config["requirements"]
>;
readonly steps: readonly [
{
readonly attempts?: number;
readonly provide:
| Context<Config["provides"]>
| Layer<Config["provides"], Config["error"], Config["requirements"]>;
readonly schedule?: Schedule<any, Config["input"], Config["requirements"], never>;
readonly while?: (
input: Config["input"],
) => Effect<boolean, Config["error"], Config["requirements"]>;
},
{
readonly attempts?: number;
readonly provide:
| Context<Config["provides"]>
| Layer<Config["provides"], Config["error"], Config["requirements"]>;
readonly schedule?: Schedule<any, Config["input"], Config["requirements"], never>;
readonly while?: (
input: Config["input"],
) => Effect<boolean, Config["error"], Config["requirements"]>;
},
];
}Other
Services
CurrentMetadata
Context reference containing metadata for the currently running execution-plan attempt.
When to use
Use to read the active plan step and attempt while code is running under an execution plan.
Signature
declare const CurrentMetadata: Reference<Metadata>;Type IDs
Runtime type identifier attached to ExecutionPlan values and used by isExecutionPlan.
Signature
declare const TypeId: "~effect/ExecutionPlan";String literal type used as the runtime type identifier for ExecutionPlan values.
Signature
type TypeId = "~effect/ExecutionPlan";
Combines multiple execution plans by concatenating their steps in order.
When to use
Use to combine separately defined fallback plans into one ordered plan before applying it to an effect or stream.
Details
The resulting plan tries every step from the first plan, then every step from the next plan, and so on.
See
makefor building a plan from individual steps instead of combining existing plans