Repeats an effect based on a specified schedule or until the first failure.

When to use

Use to rerun an effect after successful executions.

Details

This function executes an effect repeatedly according to the given schedule. Each repetition occurs after the initial execution of the effect, meaning that the schedule determines the number of additional repetitions. For example, using Schedule.once will result in the effect being executed twice (once initially and once as part of the repetition).

If the effect succeeds, it is repeated according to the schedule. If it fails, the repetition stops immediately, and the failure is returned.

The schedule can also specify delays between repetitions, making it useful for tasks like retrying operations with backoff, periodic execution, or performing a series of dependent actions.

You can combine schedules for more advanced repetition logic, such as adding delays, limiting recursions, or dynamically adjusting based on the outcome of each execution.

Gotchas

The source effect is always evaluated once before the schedule is stepped. The schedule controls additional repetitions, not the initial execution.

Example (Repeating successful effects with a schedule)

// Success Example
import { Console, Effect, Schedule } from "effect"

const action = Console.log("success")
const policy = Schedule.addDelay(Schedule.recurs(2), () => Effect.succeed("100 millis"))
const program = Effect.repeat(action, policy)

// Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))

Example (Stopping repetition on failure)

// Failure Example
import { Effect, Schedule } from "effect"

let count = 0

// Define a callback effect that simulates an action with possible failures
const action = Effect.callback<string, string>((resume) => {
  if (count > 1) {
    console.log("failure")
    resume(Effect.fail("Uh oh!"))
  } else {
    count++
    console.log("success")
    resume(Effect.succeed("yay!"))
  }
})

const policy = Schedule.addDelay(Schedule.recurs(2), () => Effect.succeed("100 millis"))
const program = Effect.repeat(action, policy)

// Effect.runPromiseExit(program).then(console.log)