Schedule Combinators

Schedules define stateful, possibly effectful, recurring schedules of events, and compose in a variety of ways. Combinators allow us to take schedules and combine them together to get other schedules.

To demonstrate the functionality of different schedules, we will use the following helper function that logs each repetition along with the corresponding delay in milliseconds, formatted as:

#<repetition>: <delay in ms>

Helper (Logging Execution Delays)

1
import { Array, Chunk, Duration, Effect, Schedule } from "effect"
2

3
const log = (schedule: Schedule.Schedule<unknown>, delay: Duration.DurationInput = 0): void => {
4
  const maxRecurs = 10 // Limit the number of executions
5
  const delays = Chunk.toArray(
6
    Effect.runSync(
7
      Schedule.run(
8
        Schedule.delays(Schedule.addDelay(schedule, () => delay)),
9
        Date.now(),
10
        Array.range(0, maxRecurs),
11
      ),
12
    ),
13
  )
14
  delays.forEach((duration, i) => {
15
    console.log(
16
      i === maxRecurs
17
        ? "..." // Indicate truncation if there are more executions
18
        : i === delays.length - 1
19
          ? "(end)" // Mark the last execution
20
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
21
    )
22
  })
23
}

Composition

Schedules can be composed in different ways:

Mode	Description
Union	Combines two schedules and recurs if either schedule wants to continue, using the shorter delay.
Intersection	Combines two schedules and recurs only if both schedules want to continue, using the longer delay.
Sequencing	Combines two schedules by running the first one fully, then switching to the second.

Union

Combines two schedules and recurs if either schedule wants to continue, using the shorter delay.

Example (Combining Exponential and Spaced Intervals)

1
import { Array, Chunk, Duration, Effect, Schedule } from "effect"
2

24 collapsed lines
3
const log = (schedule: Schedule.Schedule<unknown>, delay: Duration.DurationInput = 0): void => {
4
  const maxRecurs = 10
5
  const delays = Chunk.toArray(
6
    Effect.runSync(
7
      Schedule.run(
8
        Schedule.delays(Schedule.addDelay(schedule, () => delay)),
9
        Date.now(),
10
        Array.range(0, maxRecurs),
11
      ),
12
    ),
13
  )
14
  delays.forEach((duration, i) => {
15
    console.log(
16
      i === maxRecurs
17
        ? "..."
18
        : i === delays.length - 1
19
          ? "(end)"
20
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
21
    )
22
  })
23
}
24

25
const schedule = Schedule.union(Schedule.exponential("100 millis"), Schedule.spaced("1 second"))
26

27
log(schedule)
28
/*
29
Output:
30
#1: 100ms  < exponential
31
#2: 200ms
32
#3: 400ms
33
#4: 800ms
34
#5: 1000ms < spaced
35
#6: 1000ms
36
#7: 1000ms
37
#8: 1000ms
38
#9: 1000ms
39
#10: 1000ms
40
...
41
*/

The Schedule.union operator selects the shortest delay at each step, so when combining an exponential schedule with a spaced interval, the initial recurrences will follow the exponential backoff, then settle into the spaced interval once the delays exceed that value.

Intersection

Combines two schedules and recurs only if both schedules want to continue, using the longer delay.

Example (Limiting Exponential Backoff with a Fixed Number of Retries)

1
import { Array, Chunk, Duration, Effect, Schedule } from "effect"
2

24 collapsed lines
3
const log = (schedule: Schedule.Schedule<unknown>, delay: Duration.DurationInput = 0): void => {
4
  const maxRecurs = 10
5
  const delays = Chunk.toArray(
6
    Effect.runSync(
7
      Schedule.run(
8
        Schedule.delays(Schedule.addDelay(schedule, () => delay)),
9
        Date.now(),
10
        Array.range(0, maxRecurs),
11
      ),
12
    ),
13
  )
14
  delays.forEach((duration, i) => {
15
    console.log(
16
      i === maxRecurs
17
        ? "..."
18
        : i === delays.length - 1
19
          ? "(end)"
20
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
21
    )
22
  })
23
}
24

25
const schedule = Schedule.intersect(Schedule.exponential("10 millis"), Schedule.recurs(5))
26

27
log(schedule)
28
/*
29
Output:
30
#1: 10ms  < exponential
31
#2: 20ms
32
#3: 40ms
33
#4: 80ms
34
#5: 160ms
35
(end)     < recurs
36
*/

The Schedule.intersect operator enforces both schedules’ constraints. In this example, the schedule follows an exponential backoff but stops after 5 recurrences due to the Schedule.recurs(5) limit.

Sequencing

Combines two schedules by running the first one fully, then switching to the second.

Example (Switching from Fixed Retries to Periodic Execution)

1
import { Array, Chunk, Duration, Effect, Schedule } from "effect"
2

24 collapsed lines
3
const log = (schedule: Schedule.Schedule<unknown>, delay: Duration.DurationInput = 0): void => {
4
  const maxRecurs = 10
5
  const delays = Chunk.toArray(
6
    Effect.runSync(
7
      Schedule.run(
8
        Schedule.delays(Schedule.addDelay(schedule, () => delay)),
9
        Date.now(),
10
        Array.range(0, maxRecurs),
11
      ),
12
    ),
13
  )
14
  delays.forEach((duration, i) => {
15
    console.log(
16
      i === maxRecurs
17
        ? "..."
18
        : i === delays.length - 1
19
          ? "(end)"
20
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
21
    )
22
  })
23
}
24

25
const schedule = Schedule.andThen(Schedule.recurs(5), Schedule.spaced("1 second"))
26

27
log(schedule)
28
/*
29
Output:
30
#1: 0ms    < recurs
31
#2: 0ms
32
#3: 0ms
33
#4: 0ms
34
#5: 0ms
35
#6: 1000ms < spaced
36
#7: 1000ms
37
#8: 1000ms
38
#9: 1000ms
39
#10: 1000ms
40
...
41
*/

The first schedule runs until completion, after which the second schedule takes over. In this example, the effect initially executes 5 times with no delay, then continues every 1 second.

Adding Randomness to Retry Delays

The Schedule.jittered combinator modifies a schedule by applying a random delay within a specified range.

When a resource is out of service due to overload or contention, retrying and backing off doesn’t help us. If all failed API calls are backed off to the same point of time, they cause another overload or contention. Jitter adds some amount of randomness to the delay of the schedule. This helps us to avoid ending up accidentally synchronizing and taking the service down by accident.

Research suggests that Schedule.jittered(0.0, 1.0) is an effective way to introduce randomness in retries.

Example (Jittered Exponential Backoff)

1
import { Array, Chunk, Duration, Effect, Schedule } from "effect"
2

24 collapsed lines
3
const log = (schedule: Schedule.Schedule<unknown>, delay: Duration.DurationInput = 0): void => {
4
  const maxRecurs = 10
5
  const delays = Chunk.toArray(
6
    Effect.runSync(
7
      Schedule.run(
8
        Schedule.delays(Schedule.addDelay(schedule, () => delay)),
9
        Date.now(),
10
        Array.range(0, maxRecurs),
11
      ),
12
    ),
13
  )
14
  delays.forEach((duration, i) => {
15
    console.log(
16
      i === maxRecurs
17
        ? "..."
18
        : i === delays.length - 1
19
          ? "(end)"
20
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
21
    )
22
  })
23
}
24

25
const schedule = Schedule.jittered(Schedule.exponential("10 millis"))
26

27
log(schedule)
28
/*
29
Output:
30
#1: 10.448486ms
31
#2: 21.134521ms
32
#3: 47.245117ms
33
#4: 88.263184ms
34
#5: 163.651367ms
35
#6: 335.818848ms
36
#7: 719.126709ms
37
#8: 1266.18457ms
38
#9: 2931.252441ms
39
#10: 6121.593018ms
40
...
41
*/

The Schedule.jittered combinator introduces randomness to delays within a range. For example, applying jitter to an exponential backoff ensures that each retry occurs at a slightly different time, reducing the risk of overwhelming the system.

Controlling Repetitions with Filters

You can use Schedule.whileInput or Schedule.whileOutput to limit how long a schedule continues based on conditions applied to its input or output.

Example (Stopping Based on Output)

1
import { Array, Chunk, Duration, Effect, Schedule } from "effect"
2

24 collapsed lines
3
const log = (schedule: Schedule.Schedule<unknown>, delay: Duration.DurationInput = 0): void => {
4
  const maxRecurs = 10
5
  const delays = Chunk.toArray(
6
    Effect.runSync(
7
      Schedule.run(
8
        Schedule.delays(Schedule.addDelay(schedule, () => delay)),
9
        Date.now(),
10
        Array.range(0, maxRecurs),
11
      ),
12
    ),
13
  )
14
  delays.forEach((duration, i) => {
15
    console.log(
16
      i === maxRecurs
17
        ? "..."
18
        : i === delays.length - 1
19
          ? "(end)"
20
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
21
    )
22
  })
23
}
24

25
const schedule = Schedule.whileOutput(Schedule.recurs(5), (n) => n <= 2)
26

27
log(schedule)
28
/*
29
Output:
30
#1: 0ms < recurs
31
#2: 0ms
32
#3: 0ms
33
(end)   < whileOutput
34
*/

Schedule.whileOutput filters repetitions based on the output of the schedule. In this example, the schedule stops once the output exceeds 2, even though Schedule.recurs(5) allows up to 5 repetitions.

Adjusting Delays Based on Output

The Schedule.modifyDelay combinator allows you to dynamically change the delay of a schedule based on the number of repetitions or other output conditions.

Example (Reducing Delay After a Certain Number of Repetitions)

1
import { Array, Chunk, Duration, Effect, Schedule } from "effect"
2

24 collapsed lines
3
const log = (schedule: Schedule.Schedule<unknown>, delay: Duration.DurationInput = 0): void => {
4
  const maxRecurs = 10
5
  const delays = Chunk.toArray(
6
    Effect.runSync(
7
      Schedule.run(
8
        Schedule.delays(Schedule.addDelay(schedule, () => delay)),
9
        Date.now(),
10
        Array.range(0, maxRecurs),
11
      ),
12
    ),
13
  )
14
  delays.forEach((duration, i) => {
15
    console.log(
16
      i === maxRecurs
17
        ? "..."
18
        : i === delays.length - 1
19
          ? "(end)"
20
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
21
    )
22
  })
23
}
24

25
const schedule = Schedule.modifyDelay(Schedule.spaced("1 second"), (out, duration) =>
26
  out > 2 ? "100 millis" : duration,
27
)
28

29
log(schedule)
30
/*
31
Output:
32
#1: 1000ms
33
#2: 1000ms
34
#3: 1000ms
35
#4: 100ms  < modifyDelay
36
#5: 100ms
37
#6: 100ms
38
#7: 100ms
39
#8: 100ms
40
#9: 100ms
41
#10: 100ms
42
...
43
*/

The delay modification applies dynamically during execution. In this example, the first three repetitions follow the original 1-second spacing. After that, the delay drops to 100 milliseconds, making subsequent repetitions occur more frequently.

Tapping

Schedule.tapInput and Schedule.tapOutput allow you to perform additional effectful operations on a schedule’s input or output without modifying its behavior.

Example (Logging Schedule Outputs)

1
import { Array, Chunk, Duration, Effect, Schedule, Console } from "effect"
2

24 collapsed lines
3
const log = (schedule: Schedule.Schedule<unknown>, delay: Duration.DurationInput = 0): void => {
4
  const maxRecurs = 10
5
  const delays = Chunk.toArray(
6
    Effect.runSync(
7
      Schedule.run(
8
        Schedule.delays(Schedule.addDelay(schedule, () => delay)),
9
        Date.now(),
10
        Array.range(0, maxRecurs),
11
      ),
12
    ),
13
  )
14
  delays.forEach((duration, i) => {
15
    console.log(
16
      i === maxRecurs
17
        ? "..."
18
        : i === delays.length - 1
19
          ? "(end)"
20
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
21
    )
22
  })
23
}
24

25
const schedule = Schedule.tapOutput(Schedule.recurs(2), (n) => Console.log(`Schedule Output: ${n}`))
26

27
log(schedule)
28
/*
29
Output:
30
Schedule Output: 0
31
Schedule Output: 1
32
Schedule Output: 2
33
#1: 0ms
34
#2: 0ms
35
(end)
36
*/

Schedule.tapOutput runs an effect before each recurrence, using the schedule’s current output as input. This can be useful for logging, debugging, or triggering side effects.