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

Infinite and Fixed Repeats

forever

A schedule that repeats indefinitely, producing the number of recurrences each time it runs.

Example (Indefinitely Recurring Schedule)

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

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

28
const schedule = Schedule.forever
29

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

once

A schedule that recurs only once.

Example (Single Recurrence Schedule)

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

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

28
const schedule = Schedule.once
29

30
log(schedule)
31
/*
32
Output:
33
#1: 0ms < once
34
(end)
35
*/

recurs

A schedule that repeats a specified number of times, producing the number of recurrences each time it runs.

Example (Fixed Number of Recurrences)

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

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

28
const schedule = Schedule.recurs(5)
29

30
log(schedule)
31
/*
32
Output:
33
#1: 0ms < recurs
34
#2: 0ms
35
#3: 0ms
36
#4: 0ms
37
#5: 0ms
38
(end)
39
*/

Recurring at specific intervals

You can define schedules that control the time between executions. The difference between spaced and fixed schedules lies in how the interval is measured:

spaced delays each repetition from the end of the previous one.
fixed ensures repetitions occur at regular intervals, regardless of execution time.

spaced

A schedule that repeats indefinitely, each repetition spaced the specified duration from the last run. It returns the number of recurrences each time it runs.

Example (Recurring with Delay Between Executions)

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

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

28
const schedule = Schedule.spaced("200 millis")
29

30
//               ┌─── Simulating an effect that takes
31
//               │    100 milliseconds to complete
32
//               ▼
33
log(schedule, "100 millis")
34
/*
35
Output:
36
#1: 300ms < spaced
37
#2: 300ms
38
#3: 300ms
39
#4: 300ms
40
#5: 300ms
41
#6: 300ms
42
#7: 300ms
43
#8: 300ms
44
#9: 300ms
45
#10: 300ms
46
...
47
*/

The first delay is approximately 100 milliseconds, as the initial execution is not affected by the schedule. Subsequent delays are approximately 200 milliseconds apart, demonstrating the effect of the spaced schedule.

fixed

A schedule that recurs at fixed intervals. It returns the number of recurrences each time it runs. If the action run between updates takes longer than the interval, then the action will be run immediately, but re-runs will not “pile up”.

|-----interval-----|-----interval-----|-----interval-----|
|---------action--------|action-------|action------------|

Example (Fixed Interval Recurrence)

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

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

28
const schedule = Schedule.fixed("200 millis")
29

30
//               ┌─── Simulating an effect that takes
31
//               │    100 milliseconds to complete
32
//               ▼
33
log(schedule, "100 millis")
34
/*
35
Output:
36
#1: 300ms < fixed
37
#2: 200ms
38
#3: 200ms
39
#4: 200ms
40
#5: 200ms
41
#6: 200ms
42
#7: 200ms
43
#8: 200ms
44
#9: 200ms
45
#10: 200ms
46
...
47
*/

Increasing Delays Between Executions

exponential

A schedule that recurs using exponential backoff, with each delay increasing exponentially. Returns the current duration between recurrences.

Example (Exponential Backoff Schedule)

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

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

28
const schedule = Schedule.exponential("10 millis")
29

30
log(schedule)
31
/*
32
Output:
33
#1: 10ms < exponential
34
#2: 20ms
35
#3: 40ms
36
#4: 80ms
37
#5: 160ms
38
#6: 320ms
39
#7: 640ms
40
#8: 1280ms
41
#9: 2560ms
42
#10: 5120ms
43
...
44
*/

fibonacci

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

Example (Fibonacci Delay Schedule)

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

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

28
const schedule = Schedule.fibonacci("10 millis")
29

30
log(schedule)
31
/*
32
Output:
33
#1: 10ms < fibonacci
34
#2: 10ms
35
#3: 20ms
36
#4: 30ms
37
#5: 50ms
38
#6: 80ms
39
#7: 130ms
40
#8: 210ms
41
#9: 340ms
42
#10: 550ms
43
...
44
*/