Schedule

Describes policies for retrying, repeating, and pacing Effect programs.

A Schedule<Output, Input, Error, Env> is stepped with an input value. Each step either stops or produces an output together with the delay before the next step. Schedules are used by retry, repeat, stream, and channel APIs to decide when work should continue, how long to wait, and when to stop.

39 exports Added in v2.0.0 Source

Combining

max

Added in v4.0.0 Source

Combines schedules by recurring while all schedules want to recur, using the maximum delay between recurrences and outputting that maximum delay.

When to use

Use when a combined policy should continue only while every schedule still recurs, and should wait for the slowest schedule between recurrences.

Signature

declare function max<
  Schedules extends readonly [Schedule<any, any, any, any>, Schedule<any, any, any, any>],
>(
  schedules: Schedules,
): Schedule<
  Duration,
  UnionToIntersection<Input<Schedules[number]>>,
  Error<Schedules[number]>,
  Env<Schedules[number]>
>;

min

Added in v4.0.0 Source

Combines schedules by recurring while at least one schedule wants to recur, using the minimum delay between recurrences and outputting that minimum delay.

When to use

Use when a combined policy should continue while any schedule still recurs, and should wait for the fastest schedule between recurrences.

Signature

declare function min<
  Schedules extends readonly [Schedule<any, any, any, any>, Schedule<any, any, any, any>],
>(
  schedules: Schedules,
): Schedule<
  Duration,
  UnionToIntersection<Input<Schedules[number]>>,
  Error<Schedules[number]>,
  Env<Schedules[number]>
>;

Constructors

cron

Added in v2.0.0 Source

Returns a new Schedule that recurs on the specified Cron schedule and outputs the duration between recurrences.

Signature

declare const cron: {
  (expression: Cron): Schedule<Duration, unknown, CronParseError>;
  (expression: string, tz?: string | TimeZone): Schedule<Duration, unknown, CronParseError>;
};

duration

Added in v2.0.0 Source

Returns a schedule that recurs once after the specified duration.

When to use

Use when you need a schedule that recurs once after a fixed delay.

Details

The schedule outputs the configured duration for its first recurrence and then completes.

See

during for recurring until a duration has elapsed

Signature

declare function duration(durationInput: Input): Schedule<Duration>;

during

Added in v4.0.0 Source

Returns a new Schedule that will always recur, but only during the specified duration of time.

When to use

Use to bound a repeating or retrying schedule by elapsed time.

See

duration for one delayed recurrence

Signature

declare function during(duration: Input): Schedule<Duration>;

exponential

Added in v2.0.0 Source

Schedule that always recurs, but will wait a certain amount between repetitions, given by base * factor.pow(n), where n is the number of repetitions so far. Returns the current duration between recurrences.

Signature

declare function exponential(base: Input, factor: number): Schedule<Duration>;

fibonacci

Added in v2.0.0 Source

Schedule that always recurs, increasing delays by summing the preceding two delays (similar to the Fibonacci sequence). Returns the current duration between recurrences.

Signature

declare function fibonacci(one: Input): Schedule<Duration>;

fixed

Added in v2.0.0 Source

Returns a Schedule that recurs on the specified fixed interval and outputs the number of repetitions of the schedule so far.

When to use

Use when recurrences should stay aligned to a regular cadence.

Gotchas

If the action run between recurrences takes longer than the interval, the next recurrence happens immediately, but missed intervals are not replayed.

``text |-----interval-----|-----interval-----|-----interval-----| |---------action--------||action|-----|action|-----------| ``

See

spaced for delaying after each action completes

Signature

declare function fixed(interval: Input): Schedule<number>;

forever

Added in v2.0.0 Source

Returns a new Schedule that will recur forever.

Details

The output of the schedule is the current count of its repetitions thus far (i.e. 0, 1, 2, ...).

Signature

declare const forever: Schedule<number>;

fromStep

Added in v4.0.0 Source

Creates a Schedule from a step function that returns a Pull.

Signature

declare function fromStep<Input, Output, EnvX, Error, ErrorX, Env>(
  step: Effect<
    (now: number, input: Input) => Pull<[Output, Duration], ErrorX, Output, EnvX>,
    Error,
    Env
  >,
): Schedule<Output, Input, Error | Exclude<ErrorX, Done<any>>, EnvX | Env>;

fromStepWithMetadata

Added in v4.0.0 Source

Creates a Schedule from a step function that receives metadata about the schedule's execution.

Signature

declare function fromStepWithMetadata<Input, Output, EnvX, ErrorX, Error, Env>(
  step: Effect<
    (options: InputMetadata<Input>) => Pull<[Output, Duration], ErrorX, Output, EnvX>,
    Error,
    Env
  >,
): Schedule<Output, Input, Error | Exclude<ErrorX, Done<any>>, EnvX | Env>;

recurs

Added in v2.0.0 Source

Returns a Schedule which can only be stepped the specified number of times before it terminates.

When to use

Use when you need a counter schedule with no additional delay.

Gotchas

recurs(n) counts schedule recurrences, not the first evaluation of the effect being repeated or retried. For retrying, this means one initial attempt plus at most n retries.

See

upTo for limiting an existing schedule

Signature

declare function recurs(times: number): Schedule<number>;

spaced

Added in v2.0.0 Source

Returns a schedule that recurs continuously, each repetition spaced the specified duration from the last run.

When to use

Use when each delay should start after the previous action completes.

See

fixed for recurrence aligned to a regular cadence

Signature

declare function spaced(duration: Input): Schedule<number>;

windowed

Added in v2.0.0 Source

Schedule that divides the timeline to interval-long windows, and sleeps until the nearest window boundary every time it recurs.

Details

For example, Schedule.windowed("10 seconds") would produce a schedule as follows:

``text 10s 10s 10s 10s |----------|----------|----------|----------| |action------|sleep---|act|-sleep|action----| ``

Signature

declare function windowed(interval: Input): Schedule<number>;

Delays & Timeouts

addDelay

Added in v2.0.0 Source

Returns a new Schedule that adds the delay computed by the specified effectful function to the next recurrence of the schedule.

Signature

declare const addDelay: {
  <Output, Input, Error2 = never, Env2 = never>(
    f: (metadata: Metadata<Output, Input>) => Effect<Input, Error2, Env2>,
  ): <Error, Env>(
    self: Schedule<Output, Input, Error, Env>,
  ) => Schedule<Output, Input, Error2 | Error, Env2 | Env>;
  <Output, Input, Error, Env, Error2 = never, Env2 = never>(
    self: Schedule<Output, Input, Error, Env>,
    f: (metadata: Metadata<Output, Input>) => Effect<Input, Error2, Env2>,
  ): Schedule<Output, Input, Error | Error2, Env | Env2>;
};

jittered

Added in v2.0.0 Source

Returns a new Schedule that randomly adjusts each recurrence delay.

When to use

Use to add random variation to an existing schedule's recurrence delays while preserving its output and completion behavior.

Details

Each recurrence delay is scaled by a random factor between 0.8 and 1.2.

See

modifyDelay for replacing recurrence delays with a custom effectful transformation

Signature

declare function jittered<Output, Input, Error, Env>(
  self: Schedule<Output, Input, Error, Env>,
): Schedule<Output, Input, Error, Env>;

modifyDelay

Added in v2.0.0 Source

Returns a new Schedule that modifies the delay of the next recurrence of the schedule using the specified effectful function.

Signature

declare const modifyDelay: {
  <Output, Input, Error2 = never, Env2 = never>(
    f: (metadata: Metadata<Output, Input>) => Effect<Input, Error2, Env2>,
  ): <Error, Env>(
    self: Schedule<Output, Input, Error, Env>,
  ) => Schedule<Output, Input, Error2 | Error, Env2 | Env>;
  <Output, Input, Error, Env, Error2 = never, Env2 = never>(
    self: Schedule<Output, Input, Error, Env>,
    f: (metadata: Metadata<Output, Input>) => Effect<Input, Error2, Env2>,
  ): Schedule<Output, Input, Error | Error2, Env | Env2>;
};

Destructors

toStep

Added in v4.0.0 Source

Extracts the step function from a Schedule.

Signature

declare function toStep<Output, Input, Error, Env>(
  schedule: Schedule<Output, Input, Error, Env>,
): Effect<(now: number, input: Input) => Pull<[Output, Duration], Error, Output, Env>, never, Env>;

toStepWithMetadata

Added in v4.0.0 Source

Extracts a step function from a Schedule that sleeps for each computed delay and returns metadata for the completed step.

When to use

Use to drive a schedule manually while preserving the computed output, delay, input, attempt, and elapsed timing metadata for each step.

Details

The returned step reads the current time from Clock when invoked, calls the schedule step with that timestamp and input, sleeps for the returned duration, and then yields Metadata.

See

toStep for manually supplying the timestamp and handling the returned delay yourself
toStepWithSleep for the same automatic sleeping behavior when only the schedule output is needed

Signature

declare function toStepWithMetadata<Output, Input, Error, Env>(
  schedule: Schedule<Output, Input, Error, Env>,
): Effect<(input: Input) => Pull<Metadata<Output, Input>, Error, Output, Env>, never, Env>;

toStepWithSleep

Added in v4.0.0 Source

Extracts a step function from a Schedule that automatically handles sleep delays.

Signature

declare function toStepWithSleep<Output, Input, Error, Env>(
  schedule: Schedule<Output, Input, Error, Env>,
): Effect<(input: Input) => Pull<Output, Error, Output, Env>, never, Env>;

Filtering

upTo

Added in v4.0.0 Source

Returns a new Schedule that limits an existing schedule by elapsed duration, number of outputs, or both.

When to use

Use to bound an existing schedule while preserving its output and delay behavior. When both duration and times are specified, the schedule stops as soon as either limit is reached.

Gotchas

The times option limits schedule outputs. When used with repeat or retry, the effect is evaluated once before the schedule is stepped, so the total number of evaluations can be one greater than the configured number of outputs.

The duration option is based on the elapsed time observed by the schedule step. Long-running effects can cause the duration limit to be detected on the following schedule step.

Signature

declare const upTo: {
  (options: {
    readonly duration?: Duration.Input;
    readonly times?: number;
  }): <Output, Input, Error, Env>(
    self: Schedule<Output, Input, Error, Env>,
  ) => Schedule<Output, Input, Error, Env>;
  <Output, Input, Error, Env>(
    self: Schedule<Output, Input, Error, Env>,
    options: {
      readonly duration?: Duration.Input;
      readonly times?: number;
    },
  ): Schedule<Output, Input, Error, Env>;
};

Guards

isSchedule

Added in v2.0.0 Source

Type guard that checks if a value is a Schedule.

Signature

declare function isSchedule(u: unknown): u is Schedule<unknown, never, unknown, unknown>;

Mapping

map

Added in v2.0.0 Source

Returns a new Schedule that maps each schedule decision to a new output using the full schedule metadata.

Details

The callback receives the schedule input, output, selected delay duration, current attempt, and elapsed timing information. Return either a plain value or an Effect that produces the new output.

Signature

declare const map: {
  <Input, Output, Output2, Error2 = never, Env2 = never>(
    f: (metadata: Metadata<Output, Input>) => Output2 | Effect<Output2, Error2, Env2>,
  ): <Error, Env>(
    self: Schedule<Output, Input, Error, Env>,
  ) => Schedule<Output2, Input, Error2 | Error, Env2 | Env>;
  <Output, Input, Error, Env, Output2, Error2 = never, Env2 = never>(
    self: Schedule<Output, Input, Error, Env>,
    f: (metadata: Metadata<Output, Input>) => Output2 | Effect<Output2, Error2, Env2>,
  ): Schedule<Output2, Input, Error | Error2, Env | Env2>;
};

passthrough

Added in v2.0.0 Source

Returns a new Schedule that outputs the inputs of the specified schedule.

Signature

declare function passthrough<Output, Input, Error, Env>(
  self: Schedule<Output, Input, Error, Env>,
): Schedule<Input, Input, Error, Env>;

Metadata

InputMetadata interface

Added in v4.0.0 Source

Metadata provided to schedule functions containing timing and input information.

Signature

interface InputMetadata<Input> {
  readonly attempt: number;
  readonly elapsed: number;
  readonly elapsedSincePrevious: number;
  readonly input: Input;
  readonly now: number;
  readonly start: number;
}

Metadata interface

Added in v4.0.0 Source

Extended metadata that includes both input metadata and the output value from the schedule.

Signature

interface Metadata<Output = unknown, Input = unknown> extends InputMetadata<Input> {
  readonly duration: Duration;
  readonly output: Output;
}

Models

Schedule interface

Added in v2.0.0 Source

A Schedule defines a strategy for repeating or retrying effects based on some policy.

Signature

interface Schedule<out Output, in Input = unknown, out Error = never, out Env = never>
  extends Variance<Output, Input, Error, Env>, Pipeable {}

Other

identity

Source

Signature

declare function identity<A>(): Schedule<A, A>;

Schedule

Added in v2.0.0 Source

The Schedule namespace contains types and utilities for working with schedules.

while

Source

Signature

declare const while: {
  <Input, Output, Error2 = never, Env2 = never>(predicate: (metadata: Metadata<Output, Input>) => boolean | Effect<boolean, Error2, Env2>): <Error, Env>(self: Schedule<Output, Input, Error, Env>) => Schedule<Output, Input, Error2 | Error, Env2 | Env>;
  <Output, Input, Error, Env, Error2 = never, Env2 = never>(self: Schedule<Output, Input, Error, Env>, predicate: (metadata: Metadata<Output, Input>) => boolean | Effect<boolean, Error2, Env2>): Schedule<Output, Input, Error | Error2, Env | Env2>;
}

Sequencing

concat

Added in v2.0.0 Source

Returns a schedule that runs self to completion, then runs other, and merges their outputs.

Signature

declare const concat: {
  <Output2, Input2, Error2, Env2>(
    other: Schedule<Output2, Input2, Error2, Env2>,
  ): <Output, Input, Error, Env>(
    self: Schedule<Output, Input, Error, Env>,
  ) => Schedule<Output2 | Output, Input & Input2, Error2 | Error, Env2 | Env>;
  <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(
    self: Schedule<Output, Input, Error, Env>,
    other: Schedule<Output2, Input2, Error2, Env2>,
  ): Schedule<Output | Output2, Input & Input2, Error | Error2, Env | Env2>;
};

concatResult

Added in v4.0.0 Source

Returns a schedule that runs self to completion, then runs other, and preserves which schedule produced each output.

Details

The resulting schedule emits a Result to indicate which phase produced each output: outputs from self are emitted as Failure, and outputs from other are emitted as Success.

Signature

declare const concatResult: {
  <Output2, Input2, Error2, Env2>(
    other: Schedule<Output2, Input2, Error2, Env2>,
  ): <Output, Input, Error, Env>(
    self: Schedule<Output, Input, Error, Env>,
  ) => Schedule<Result<Output2, Output>, Input & Input2, Error2 | Error, Env2 | Env>;
  <Output, Input, Error, Env, Output2, Input2, Error2, Env2>(
    self: Schedule<Output, Input, Error, Env>,
    other: Schedule<Output2, Input2, Error2, Env2>,
  ): Schedule<Result<Output2, Output>, Input & Input2, Error | Error2, Env | Env2>;
};

tap

Added in v4.0.0 Source

Returns a new Schedule that allows execution of an effectful function for every decision of the schedule, but does not alter the inputs and outputs of the schedule.

Details

The callback receives the full schedule metadata, including the input, output, computed delay duration, current attempt, and elapsed timing information.

Signature

declare const tap: {
  <Output, Input, X, Error2, Env2>(
    f: (metadata: Metadata<Output, Input>) => Effect<X, Error2, Env2>,
  ): <Error, Env>(
    self: Schedule<Output, Input, Error, Env>,
  ) => Schedule<Output, Input, Error2 | Error, Env2 | Env>;
  <Output, Input, Error, Env, X, Error2, Env2>(
    self: Schedule<Output, Input, Error, Env>,
    f: (metadata: Metadata<Output, Input>) => Effect<X, Error2, Env2>,
  ): Schedule<Output, Input, Error | Error2, Env | Env2>;
};

Services

CurrentMetadata

Added in v4.0.0 Source

Context reference containing metadata for the currently running schedule step.

Details

Repeat, retry, stream, and channel scheduling operations provide this service to effects run between schedule steps. The default value contains undefined input and output values, zero duration, and zeroed timing fields before any schedule step has produced metadata.

Signature

declare const CurrentMetadata: Reference<Metadata<unknown, unknown>>;

Use to adapt a schedule that does not depend on its input values.

Details

This helper is checked at compile time and does not change the schedule's runtime behavior.

Signature

declare function setInputType<T>(): <Output, Error, Env>(
  self: Schedule<Output, T, Error, Env>,
) => Schedule<Output, T, Error, Env>;