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, Duration, Effect, Pull, Schedule } from "effect"
2

3
const log = (
4
  schedule: Schedule.Schedule<unknown>,
5
  delay: Duration.Input = 0,
6
): void => {
7
  const maxRecurs = 10 // Limit the number of executions
8
  const withDelay = Schedule.addDelay(schedule, () => Effect.succeed(delay))
9
  const delays = Effect.runSync(
10
    Effect.gen(function* () {
11
      const step = yield* Schedule.toStep(withDelay)
12
      const out: Array<Duration.Duration> = []
13
      let now = Date.now()
14
      for (const input of Array.range(0, maxRecurs)) {
15
        const duration = yield* Pull.matchEffect(step(now, input), {
16
          onSuccess: ([, duration]) => Effect.succeed(duration),
17
          onFailure: Effect.failCause,
18
          onDone: () => Effect.succeed(undefined),
19
        })
20
        if (duration === undefined) break
21
        out.push(duration)
22
        now += Duration.toMillis(duration)
23
      }
24
      return out
25
    }),
26
  )
27
  delays.forEach((duration, i) => {
28
    console.log(
29
      i === maxRecurs
30
        ? "..." // Indicate truncation if there are more executions
31
        : i === delays.length - 1
32
          ? "(end)" // Mark the last execution
33
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
34
    )
35
  })
36
}
37

38
typeof log // => "function"

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, Duration, Effect, Pull, Schedule } from "effect"
2

31 collapsed lines
3
const log = (
4
  schedule: Schedule.Schedule<unknown>,
5
  delay: Duration.Input = 0,
6
): Array<Duration.Duration> => {
7
  const maxRecurs = 10
8
  const withDelay = Schedule.addDelay(schedule, () => Effect.succeed(delay))
9
  const delays = Effect.runSync(
10
    Effect.gen(function* () {
11
      const step = yield* Schedule.toStep(withDelay)
12
      const out: Array<Duration.Duration> = []
13
      let now = Date.now()
14
      for (const input of Array.range(0, maxRecurs)) {
15
        const duration = yield* Pull.matchEffect(step(now, input), {
16
          onSuccess: ([, duration]) => Effect.succeed(duration),
17
          onFailure: Effect.failCause,
18
          onDone: () => Effect.succeed(undefined),
19
        })
20
        if (duration === undefined) break
21
        out.push(duration)
22
        now += Duration.toMillis(duration)
23
      }
24
      return out
25
    }),
26
  )
27
  delays.forEach((duration, i) => {
28
    console.log(
29
      i === maxRecurs
30
        ? "..."
31
        : i === delays.length - 1
32
          ? "(end)"
33
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
34
    )
35
  })
36
  return delays
37
}
38

39
const schedule = Schedule.forever
40

41
log(schedule)
42
/*
43
Output:
44
#1: 0ms < forever
45
#2: 0ms
46
#3: 0ms
47
#4: 0ms
48
#5: 0ms
49
#6: 0ms
50
#7: 0ms
51
#8: 0ms
52
#9: 0ms
53
#10: 0ms
54
...
55
*/
56

57
const result = log(schedule)
58
result.map(Duration.toMillis) // => [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

once

A schedule that recurs only once.

Example (Single Recurrence Schedule)

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

31 collapsed lines
3
const log = (
4
  schedule: Schedule.Schedule<unknown>,
5
  delay: Duration.Input = 0,
6
): Array<Duration.Duration> => {
7
  const maxRecurs = 10
8
  const withDelay = Schedule.addDelay(schedule, () => Effect.succeed(delay))
9
  const delays = Effect.runSync(
10
    Effect.gen(function* () {
11
      const step = yield* Schedule.toStep(withDelay)
12
      const out: Array<Duration.Duration> = []
13
      let now = Date.now()
14
      for (const input of Array.range(0, maxRecurs)) {
15
        const duration = yield* Pull.matchEffect(step(now, input), {
16
          onSuccess: ([, duration]) => Effect.succeed(duration),
17
          onFailure: Effect.failCause,
18
          onDone: () => Effect.succeed(undefined),
19
        })
20
        if (duration === undefined) break
21
        out.push(duration)
22
        now += Duration.toMillis(duration)
23
      }
24
      return out
25
    }),
26
  )
27
  delays.forEach((duration, i) => {
28
    console.log(
29
      i === maxRecurs
30
        ? "..."
31
        : i === delays.length - 1
32
          ? "(end)"
33
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
34
    )
35
  })
36
  return delays
37
}
38

39
const schedule = Schedule.duration(Duration.zero)
40

41
log(schedule)
42
/*
43
Output:
44
#1: 0ms < once
45
(end)
46
*/
47

48
const result = log(schedule)
49
result.map(Duration.toMillis) // => [0]

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, Duration, Effect, Pull, Schedule } from "effect"
2

31 collapsed lines
3
const log = (
4
  schedule: Schedule.Schedule<unknown>,
5
  delay: Duration.Input = 0,
6
): Array<Duration.Duration> => {
7
  const maxRecurs = 10
8
  const withDelay = Schedule.addDelay(schedule, () => Effect.succeed(delay))
9
  const delays = Effect.runSync(
10
    Effect.gen(function* () {
11
      const step = yield* Schedule.toStep(withDelay)
12
      const out: Array<Duration.Duration> = []
13
      let now = Date.now()
14
      for (const input of Array.range(0, maxRecurs)) {
15
        const duration = yield* Pull.matchEffect(step(now, input), {
16
          onSuccess: ([, duration]) => Effect.succeed(duration),
17
          onFailure: Effect.failCause,
18
          onDone: () => Effect.succeed(undefined),
19
        })
20
        if (duration === undefined) break
21
        out.push(duration)
22
        now += Duration.toMillis(duration)
23
      }
24
      return out
25
    }),
26
  )
27
  delays.forEach((duration, i) => {
28
    console.log(
29
      i === maxRecurs
30
        ? "..."
31
        : i === delays.length - 1
32
          ? "(end)"
33
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
34
    )
35
  })
36
  return delays
37
}
38

39
const schedule = Schedule.recurs(5)
40

41
log(schedule)
42
/*
43
Output:
44
#1: 0ms < recurs
45
#2: 0ms
46
#3: 0ms
47
#4: 0ms
48
#5: 0ms
49
(end)
50
*/
51

52
const result = log(schedule)
53
result.map(Duration.toMillis) // => [0, 0, 0, 0, 0]

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, Duration, Effect, Pull, Schedule } from "effect"
2

31 collapsed lines
3
const log = (
4
  schedule: Schedule.Schedule<unknown>,
5
  delay: Duration.Input = 0,
6
): Array<Duration.Duration> => {
7
  const maxRecurs = 10
8
  const withDelay = Schedule.addDelay(schedule, () => Effect.succeed(delay))
9
  const delays = Effect.runSync(
10
    Effect.gen(function* () {
11
      const step = yield* Schedule.toStep(withDelay)
12
      const out: Array<Duration.Duration> = []
13
      let now = Date.now()
14
      for (const input of Array.range(0, maxRecurs)) {
15
        const duration = yield* Pull.matchEffect(step(now, input), {
16
          onSuccess: ([, duration]) => Effect.succeed(duration),
17
          onFailure: Effect.failCause,
18
          onDone: () => Effect.succeed(undefined),
19
        })
20
        if (duration === undefined) break
21
        out.push(duration)
22
        now += Duration.toMillis(duration)
23
      }
24
      return out
25
    }),
26
  )
27
  delays.forEach((duration, i) => {
28
    console.log(
29
      i === maxRecurs
30
        ? "..."
31
        : i === delays.length - 1
32
          ? "(end)"
33
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
34
    )
35
  })
36
  return delays
37
}
38

39
const schedule = Schedule.spaced("200 millis")
40

41
//               ┌─── Simulating an effect that takes
42
//               │    100 milliseconds to complete
43
//               ▼
44
log(schedule, "100 millis")
45
/*
46
Output:
47
#1: 300ms < spaced
48
#2: 300ms
49
#3: 300ms
50
#4: 300ms
51
#5: 300ms
52
#6: 300ms
53
#7: 300ms
54
#8: 300ms
55
#9: 300ms
56
#10: 300ms
57
...
58
*/
59

60
const result = log(schedule, "100 millis")
61
result.map(Duration.toMillis) // => [300, 300, 300, 300, 300, 300, 300, 300, 300, 300, 300]

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, Duration, Effect, Pull, Schedule } from "effect"
2

31 collapsed lines
3
const log = (
4
  schedule: Schedule.Schedule<unknown>,
5
  delay: Duration.Input = 0,
6
): Array<Duration.Duration> => {
7
  const maxRecurs = 10
8
  const withDelay = Schedule.addDelay(schedule, () => Effect.succeed(delay))
9
  const delays = Effect.runSync(
10
    Effect.gen(function* () {
11
      const step = yield* Schedule.toStep(withDelay)
12
      const out: Array<Duration.Duration> = []
13
      let now = Date.now()
14
      for (const input of Array.range(0, maxRecurs)) {
15
        const duration = yield* Pull.matchEffect(step(now, input), {
16
          onSuccess: ([, duration]) => Effect.succeed(duration),
17
          onFailure: Effect.failCause,
18
          onDone: () => Effect.succeed(undefined),
19
        })
20
        if (duration === undefined) break
21
        out.push(duration)
22
        now += Duration.toMillis(duration)
23
      }
24
      return out
25
    }),
26
  )
27
  delays.forEach((duration, i) => {
28
    console.log(
29
      i === maxRecurs
30
        ? "..."
31
        : i === delays.length - 1
32
          ? "(end)"
33
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
34
    )
35
  })
36
  return delays
37
}
38

39
const schedule = Schedule.fixed("200 millis")
40

41
//               ┌─── Simulating an effect that takes
42
//               │    100 milliseconds to complete
43
//               ▼
44
log(schedule, "100 millis")
45
/*
46
Output:
47
#1: 300ms < fixed
48
#2: 200ms
49
#3: 200ms
50
#4: 200ms
51
#5: 200ms
52
#6: 200ms
53
#7: 200ms
54
#8: 200ms
55
#9: 200ms
56
#10: 200ms
57
...
58
*/
59

60
const result = log(schedule, "100 millis")
61
result.map(Duration.toMillis) // => [300, 200, 200, 200, 200, 200, 200, 200, 200, 200, 200]

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, Duration, Effect, Pull, Schedule } from "effect"
2

31 collapsed lines
3
const log = (
4
  schedule: Schedule.Schedule<unknown>,
5
  delay: Duration.Input = 0,
6
): Array<Duration.Duration> => {
7
  const maxRecurs = 10
8
  const withDelay = Schedule.addDelay(schedule, () => Effect.succeed(delay))
9
  const delays = Effect.runSync(
10
    Effect.gen(function* () {
11
      const step = yield* Schedule.toStep(withDelay)
12
      const out: Array<Duration.Duration> = []
13
      let now = Date.now()
14
      for (const input of Array.range(0, maxRecurs)) {
15
        const duration = yield* Pull.matchEffect(step(now, input), {
16
          onSuccess: ([, duration]) => Effect.succeed(duration),
17
          onFailure: Effect.failCause,
18
          onDone: () => Effect.succeed(undefined),
19
        })
20
        if (duration === undefined) break
21
        out.push(duration)
22
        now += Duration.toMillis(duration)
23
      }
24
      return out
25
    }),
26
  )
27
  delays.forEach((duration, i) => {
28
    console.log(
29
      i === maxRecurs
30
        ? "..."
31
        : i === delays.length - 1
32
          ? "(end)"
33
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
34
    )
35
  })
36
  return delays
37
}
38

39
const schedule = Schedule.exponential("10 millis")
40

41
log(schedule)
42
/*
43
Output:
44
#1: 10ms < exponential
45
#2: 20ms
46
#3: 40ms
47
#4: 80ms
48
#5: 160ms
49
#6: 320ms
50
#7: 640ms
51
#8: 1280ms
52
#9: 2560ms
53
#10: 5120ms
54
...
55
*/
56

57
const result = log(schedule)
58
result.map(Duration.toMillis) // => [10, 20, 40, 80, 160, 320, 640, 1280, 2560, 5120, 10240]

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, Duration, Effect, Pull, Schedule } from "effect"
2

31 collapsed lines
3
const log = (
4
  schedule: Schedule.Schedule<unknown>,
5
  delay: Duration.Input = 0,
6
): Array<Duration.Duration> => {
7
  const maxRecurs = 10
8
  const withDelay = Schedule.addDelay(schedule, () => Effect.succeed(delay))
9
  const delays = Effect.runSync(
10
    Effect.gen(function* () {
11
      const step = yield* Schedule.toStep(withDelay)
12
      const out: Array<Duration.Duration> = []
13
      let now = Date.now()
14
      for (const input of Array.range(0, maxRecurs)) {
15
        const duration = yield* Pull.matchEffect(step(now, input), {
16
          onSuccess: ([, duration]) => Effect.succeed(duration),
17
          onFailure: Effect.failCause,
18
          onDone: () => Effect.succeed(undefined),
19
        })
20
        if (duration === undefined) break
21
        out.push(duration)
22
        now += Duration.toMillis(duration)
23
      }
24
      return out
25
    }),
26
  )
27
  delays.forEach((duration, i) => {
28
    console.log(
29
      i === maxRecurs
30
        ? "..."
31
        : i === delays.length - 1
32
          ? "(end)"
33
          : `#${i + 1}: ${Duration.toMillis(duration)}ms`,
34
    )
35
  })
36
  return delays
37
}
38

39
const schedule = Schedule.fibonacci("10 millis")
40

41
log(schedule)
42
/*
43
Output:
44
#1: 10ms
45
#2: 20ms
46
#3: 30ms
47
#4: 50ms
48
#5: 80ms
49
#6: 130ms
50
#7: 210ms
51
#8: 340ms
52
#9: 550ms
53
#10: 890ms
54
...
55
*/
56

57
const result = log(schedule)
58
result.map(Duration.toMillis) // => [10, 20, 30, 50, 80, 130, 210, 340, 550, 890, 1440]