Retrying

In software development, it’s common to encounter situations where an operation may fail temporarily due to various factors such as network issues, resource unavailability, or external dependencies. In such cases, it’s often desirable to retry the operation automatically, allowing it to succeed eventually.

Retrying is a powerful mechanism to handle transient failures and ensure the successful execution of critical operations. In Effect retrying is made simple and flexible with built-in functions and scheduling strategies.

In this guide, we will explore the concept of retrying in Effect and learn how to use the retry and retryOrElse functions to handle failure scenarios. We’ll see how to define retry policies using schedules, which dictate when and how many times the operation should be retried.

Whether you’re working on network requests, database interactions, or any other potentially error-prone operations, mastering the retrying capabilities of effect can significantly enhance the resilience and reliability of your applications.

retry

The Effect.retry function takes an effect and a Schedule policy, and will automatically retry the effect if it fails, following the rules of the policy.

If the effect ultimately succeeds, the result will be returned.

If the maximum retries are exhausted and the effect still fails, the failure is propagated.

This can be useful when dealing with intermittent failures, such as network issues or temporary resource unavailability. By defining a retry policy, you can control the number of retries, the delay between them, and when to stop retrying.

Example (Retrying with a Fixed Delay)

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

3
let count = 0
4

5
// Simulates an effect with possible failures
6
const task = Effect.async<string, Error>((resume) => {
7
  if (count <= 2) {
8
    count++
9
    console.log("failure")
10
    resume(Effect.fail(new Error()))
11
  } else {
12
    console.log("success")
13
    resume(Effect.succeed("yay!"))
14
  }
15
})
16

17
// Define a repetition policy using a fixed delay between retries
18
const policy = Schedule.fixed("100 millis")
19

20
const repeated = Effect.retry(task, policy)
21

22
Effect.runPromise(repeated).then(console.log)
23
/*
24
Output:
25
failure
26
failure
27
failure
28
success
29
yay!
30
*/

Retrying n Times Immediately

You can also retry a failing effect a set number of times with a simpler policy that retries immediately:

Example (Retrying a Task up to 5 times)

1
import { Effect } from "effect"
2

3
let count = 0
4

5
// Simulates an effect with possible failures
6
const task = Effect.async<string, Error>((resume) => {
7
  if (count <= 2) {
8
    count++
9
    console.log("failure")
10
    resume(Effect.fail(new Error()))
11
  } else {
12
    console.log("success")
13
    resume(Effect.succeed("yay!"))
14
  }
15
})
16

17
// Retry the task up to 5 times
18
Effect.runPromise(Effect.retry(task, { times: 5 }))
19
/*
20
Output:
21
failure
22
failure
23
failure
24
success
25
*/

Retrying Based on a Condition

You can customize how retries are managed by specifying conditions. Use the until or while options to control when retries stop.

Example (Retrying Until a Specific Condition is Met)

1
import { Effect } from "effect"
2

3
let count = 0
4

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

11
// Retry the action until a specific condition is met
12
const program = Effect.retry(action, {
13
  until: (err) => err === "Error 3",
14
})
15

16
Effect.runPromiseExit(program).then(console.log)
17
/*
18
Output:
19
Action called 1 time(s)
20
Action called 2 time(s)
21
Action called 3 time(s)
22
{
23
  _id: 'Exit',
24
  _tag: 'Failure',
25
  cause: { _id: 'Cause', _tag: 'Fail', failure: 'Error 3' }
26
}
27
*/

retryOrElse

The Effect.retryOrElse function attempts to retry a failing effect multiple times according to a defined Schedule policy.

If the retries are exhausted and the effect still fails, it runs a fallback effect instead.

This function is useful when you want to handle failures gracefully by specifying an alternative action after repeated failures.

Example (Retrying with Fallback)

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

3
let count = 0
4

5
// Simulates an effect with possible failures
6
const task = Effect.async<string, Error>((resume) => {
7
  if (count <= 2) {
8
    count++
9
    console.log("failure")
10
    resume(Effect.fail(new Error()))
11
  } else {
12
    console.log("success")
13
    resume(Effect.succeed("yay!"))
14
  }
15
})
16

17
// Retry the task with a delay between retries and a maximum of 2 retries
18
const policy = Schedule.addDelay(Schedule.recurs(2), () => "100 millis")
19

20
// If all retries fail, run the fallback effect
21
const repeated = Effect.retryOrElse(
22
  task,
23
  policy,
24
  // fallback
25
  () => Console.log("orElse").pipe(Effect.as("default value")),
26
)
27

28
Effect.runPromise(repeated).then(console.log)
29
/*
30
Output:
31
failure
32
failure
33
failure
34
orElse
35
default value
36
*/