Repetition

Repetition is a common requirement when working with effects in software development. It allows us to perform an effect multiple times according to a specific repetition policy.

repeat

The Effect.repeat function returns a new effect that repeats the given effect according to a specified schedule or until the first failure.

Example (Repeating a Successful Effect)

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

3
// Define an effect that logs a message to the console
4
const action = Console.log("success")
5

6
// Define a schedule that repeats the action 2 more times with a delay
7
const policy = Schedule.addDelay(Schedule.recurs(2), () => "100 millis")
8

9
// Repeat the action according to the schedule
10
const program = Effect.repeat(action, policy)
11

12
// Run the program and log the number of repetitions
13
Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
14
/*
15
Output:
16
success
17
success
18
success
19
repetitions: 2
20
*/

Example (Handling Failures in Repetition)

1
import { Effect, Schedule } from "effect"
2

3
let count = 0
4

5
// Define an async effect that simulates an action with potential failure
6
const action = Effect.async<string, string>((resume) => {
7
  if (count > 1) {
8
    console.log("failure")
9
    resume(Effect.fail("Uh oh!"))
10
  } else {
11
    count++
12
    console.log("success")
13
    resume(Effect.succeed("yay!"))
14
  }
15
})
16

17
// Define a schedule that repeats the action 2 more times with a delay
18
const policy = Schedule.addDelay(Schedule.recurs(2), () => "100 millis")
19

20
// Repeat the action according to the schedule
21
const program = Effect.repeat(action, policy)
22

23
// Run the program and observe the result on failure
24
Effect.runPromiseExit(program).then(console.log)
25
/*
26
Output:
27
success
28
success
29
failure
30
{
31
  _id: 'Exit',
32
  _tag: 'Failure',
33
  cause: { _id: 'Cause', _tag: 'Fail', failure: 'Uh oh!' }
34
}
35
*/

Skipping First Execution

If you want to avoid the first execution and only run the action according to a schedule, you can use Effect.schedule. This allows the effect to skip the initial run and follow the defined repeat policy.

Example (Skipping First Execution)

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

3
const action = Console.log("success")
4

5
const policy = Schedule.addDelay(Schedule.recurs(2), () => "100 millis")
6

7
const program = Effect.schedule(action, policy)
8

9
Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
10
/*
11
Output:
12
success
13
success
14
repetitions: 2
15
*/

repeatN

The repeatN function returns a new effect that repeats the specified effect a given number of times or until the first failure. The repeats are in addition to the initial execution, so Effect.repeatN(action, 1) executes action once initially and then repeats it one additional time if it succeeds.

Example (Repeating an Action Multiple Times)

1
import { Effect, Console } from "effect"
2

3
const action = Console.log("success")
4

5
// Repeat the action 2 additional times after the first execution
6
const program = Effect.repeatN(action, 2)
7

8
Effect.runPromise(program)
9
/*
10
Output:
11
success
12
success
13
success
14
*/

repeatOrElse

The repeatOrElse function returns a new effect that repeats the specified effect according to the given schedule or until the first failure. When a failure occurs, the failure value and schedule output are passed to a specified handler. Scheduled recurrences are in addition to the initial execution, so Effect.repeat(action, Schedule.once) executes action once initially and then repeats it an additional time if it succeeds.

Example (Handling Failure During Repeats)

1
import { Effect, Schedule } from "effect"
2

3
let count = 0
4

5
// Define an async effect that simulates an action with possible failures
6
const action = Effect.async<string, string>((resume) => {
7
  if (count > 1) {
8
    console.log("failure")
9
    resume(Effect.fail("Uh oh!"))
10
  } else {
11
    count++
12
    console.log("success")
13
    resume(Effect.succeed("yay!"))
14
  }
15
})
16

17
// Define a schedule that repeats up to 2 times
18
// with a 100ms delay between attempts
19
const policy = Schedule.addDelay(Schedule.recurs(2), () => "100 millis")
20

21
// Provide a handler to run when failure occurs after the retries
22
const program = Effect.repeatOrElse(action, policy, () =>
23
  Effect.sync(() => {
24
    console.log("orElse")
25
    return count - 1
26
  }),
27
)
28

29
Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
30
/*
31
Output:
32
success
33
success
34
failure
35
orElse
36
repetitions: 1
37
*/

Repeating Based on a Condition

You can control the repetition of an effect by a condition using either a while or until option, allowing for dynamic control based on runtime outcomes.

Example (Repeating Until a Condition is Met)

1
import { Effect } from "effect"
2

3
let count = 0
4

5
// Define an effect that simulates varying outcomes on each invocation
6
const action = Effect.sync(() => {
7
  console.log(`Action called ${++count} time(s)`)
8
  return count
9
})
10

11
// Repeat the action until the count reaches 3
12
const program = Effect.repeat(action, { until: (n) => n === 3 })
13

14
Effect.runFork(program)
15
/*
16
Output:
17
Action called 1 time(s)
18
Action called 2 time(s)
19
Action called 3 time(s)
20
*/