Examples

Making API Calls and Handling Timeouts

When making API calls to third-party services, we may want to enforce timeouts and retry mechanisms. In this example, the API call is set to retry a maximum of two times in case of failure, and the entire operation will be interrupted if it takes longer than 4 seconds.

1
import { 
import Console
Console, 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from "effect"
2

3
// Function to make the API call
4
const 
const getJson: (url: string) => Effect.Effect<unknown, UnknownException, never>
getJson = (
url: string
url: string) =>
5
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const tryPromise: <unknown>(evaluate: (signal: AbortSignal) => PromiseLike<unknown>) => Effect.Effect<unknown, UnknownException, never> (+1 overload)
Creates an Effect that represents an asynchronous computation that might
fail.
When to Use
In situations where you need to perform asynchronous operations that might
fail, such as fetching data from an API, you can use the tryPromise
constructor. This constructor is designed to handle operations that could
throw exceptions by capturing those exceptions and transforming them into
manageable errors.
Error Handling
There are two ways to handle errors with tryPromise:

If you don't provide a catch function, the error is caught and the
effect fails with an UnknownException.
If you provide a catch function, the error is caught and the catch
function maps it to an error of type E.

Interruptions
An optional AbortSignal can be provided to allow for interruption of the
wrapped Promise API.
@see ― promise if the effectful computation is asynchronous and does not throw errors.
@example 
// Title: Fetching a TODO Item
import { Effect } from "effect"

const getTodo = (id: number) =>
  // Will catch any errors and propagate them as UnknownException
  Effect.tryPromise(() =>
    fetch(`https://jsonplaceholder.typicode.com/todos/${id}`)
  )

//      ┌─── Effect<Response, UnknownException, never>
//      ▼
const program = getTodo(1)
@example 
// Title: Custom Error Handling
import { Effect } from "effect"
const getTodo = (id: number) =>
Effect.tryPromise({
try: () => fetch(https://jsonplaceholder.typicode.com/todos/${id}),
// remap the error
catch: (unknown) => new Error(something went wrong ${unknown})
})
//      ┌─── Effect<Response, Error, never>
//      ▼
const program = getTodo(1)
@since ― 2.0.0
tryPromise(() =>
6
    
function fetch(input: string | URL | globalThis.Request, init?: RequestInit): Promise<Response>
fetch(
url: string
url).
Promise<Response>.then<unknown, never>(onfulfilled?: ((value: Response) => unknown) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<unknown>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then((
res: Response
res) => {
7
      if (!
res: Response
res.
Response.ok: boolean
ok) {
8
        
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
globalThis.Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log("error")
9
        throw new 
var Error: ErrorConstructor
new (message?: string) => Error
Error(
res: Response
res.
Response.statusText: string
statusText)
10
      }
11
      
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
globalThis.Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log("ok")
12
      return 
res: Response
res.
BodyMixin.json: () => Promise<unknown>
json() as unknown
13
    })
14
  )
15

16
// Program that retries the API call twice,
17
// times out after 4 seconds, and logs errors
18
const 
const program: (url: string) => Effect.Effect<unknown, never, never>
program = (
url: string
url: string) =>
19
  
const getJson: (url: string) => Effect.Effect<unknown, UnknownException, never>
getJson(
url: string
url).
Pipeable.pipe<Effect.Effect<unknown, UnknownException, never>, Effect.Effect<unknown, UnknownException, never>, Effect.Effect<unknown, UnknownException | TimeoutException, never>, Effect.Effect<...>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<...>) => Effect.Effect<...>, bc: (_: Effect.Effect<...>) => Effect.Effect<...>, cd: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe(
20
    
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const retry: <UnknownException, {
    times: number;
}>(options: {
    times: number;
}) => <A, R>(self: Effect.Effect<A, UnknownException, R>) => Effect.Effect<...> (+3 overloads)
Retries a failing effect based on a defined retry policy.
Details
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.
When to Use
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.
@see ― retryOrElse for a version that allows you to run a fallback.
@see ― repeat if your retry condition is based on successful outcomes rather than errors.
@example 
// Title: Retrying with a Fixed Delay
import { Effect, Schedule } from "effect"

let count = 0

// Simulates an effect with possible failures
const task = Effect.async<string, Error>((resume) => {
  if (count <= 2) {
    count++
    console.log("failure")
    resume(Effect.fail(new Error()))
  } else {
    console.log("success")
    resume(Effect.succeed("yay!"))
  }
})

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

const repeated = Effect.retry(task, policy)

Effect.runPromise(repeated).then(console.log)
// Output:
// failure
// failure
// failure
// success
// yay!
@example 
// Title: Retrying a Task up to 5 times
import { Effect } from "effect"

let count = 0

// Simulates an effect with possible failures
const task = Effect.async<string, Error>((resume) => {
  if (count <= 2) {
    count++
    console.log("failure")
    resume(Effect.fail(new Error()))
  } else {
    console.log("success")
    resume(Effect.succeed("yay!"))
  }
})

// Retry the task up to 5 times
Effect.runPromise(Effect.retry(task, { times: 5 }))
// Output:
// failure
// failure
// failure
// success
@example 
// Title: Retrying Until a Specific Condition is Met
import { Effect } from "effect"

let count = 0

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

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

Effect.runPromiseExit(program).then(console.log)
// Output:
// Action called 1 time(s)
// Action called 2 time(s)
// Action called 3 time(s)
// {
//   _id: 'Exit',
//   _tag: 'Failure',
//   cause: { _id: 'Cause', _tag: 'Fail', failure: 'Error 3' }
// }
@since ― 2.0.0
retry({ 
times: number
times: 2 }),
21
    
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const timeout: (duration: DurationInput) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E | TimeoutException, R> (+1 overload)
Adds a time limit to an effect, triggering a timeout if the effect exceeds
the duration.
The timeout function allows you to specify a time limit for an
effect's execution. If the effect does not complete within the given time, a
TimeoutException is raised. This can be useful for controlling how long
your program waits for a task to finish, ensuring that it doesn't hang
indefinitely if the task takes too long.
@see ― timeoutFail for a version that raises a custom error.
@see ― timeoutFailCause for a version that raises a custom defect.
@see ― timeoutTo for a version that allows specifying both success and timeout handlers.
@example 
import { Effect } from "effect"

const task = Effect.gen(function* () {
  console.log("Start processing...")
  yield* Effect.sleep("2 seconds") // Simulates a delay in processing
  console.log("Processing complete.")
  return "Result"
})

// Output will show a TimeoutException as the task takes longer
// than the specified timeout duration
const timedEffect = task.pipe(Effect.timeout("1 second"))

Effect.runPromiseExit(timedEffect).then(console.log)
// Output:
// Start processing...
// {
//   _id: 'Exit',
//   _tag: 'Failure',
//   cause: {
//     _id: 'Cause',
//     _tag: 'Fail',
//     failure: { _tag: 'TimeoutException' }
//   }
// }
@since ― 2.0.0
timeout("4 seconds"),
22
    
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const catchAll: <any, void, never, never>(f: (e: any) => Effect.Effect<void, never, never>) => <A, R>(self: Effect.Effect<A, any, R>) => Effect.Effect<void | A, never, R> (+1 overload)
Handles all errors in an effect by providing a fallback effect.
Details
This function catches any errors that may occur during the execution of an
effect and allows you to handle them by specifying a fallback effect. This
ensures that the program continues without failing by recovering from errors
using the provided fallback logic.
Note: This function only handles recoverable errors. It will not recover
from unrecoverable defects.
@see ― catchAllCause for a version that can recover from both
recoverable and unrecoverable errors.
@example 
// Title: Providing Recovery Logic for Recoverable Errors
import { Effect, Random } from "effect"

class HttpError {
  readonly _tag = "HttpError"
}

class ValidationError {
  readonly _tag = "ValidationError"
}

//      ┌─── Effect<string, HttpError | ValidationError, never>
//      ▼
const program = Effect.gen(function* () {
  const n1 = yield* Random.next
  const n2 = yield* Random.next
  if (n1 < 0.5) {
    yield* Effect.fail(new HttpError())
  }
  if (n2 < 0.5) {
    yield* Effect.fail(new ValidationError())
  }
  return "some result"
})

//      ┌─── Effect<string, never, never>
//      ▼
const recovered = program.pipe(
  Effect.catchAll((error) =>
    Effect.succeed(`Recovering from ${error._tag}`)
  )
)
@since ― 2.0.0
catchAll(
import Console
Console.
const error: (...args: ReadonlyArray<any>) => Effect.Effect<void>@since ― 2.0.0
error)
23
  )
24

25
// Test the successful case
26
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runFork: <unknown, never>(effect: Effect.Effect<unknown, never, never>, options?: RunForkOptions) => RuntimeFiber<unknown, never>
The foundational function for running effects, returning a "fiber" that can
be observed or interrupted.
When to Use
runFork is used to run an effect in the background by creating a
fiber. It is the base function for all other run functions. It starts a fiber
that can be observed or interrupted.
Unless you specifically need a Promise or synchronous operation,
runFork is a good default choice.
@example 
// Title: Running an Effect in the Background
import { Effect, Console, Schedule, Fiber } from "effect"

//      ┌─── Effect<number, never, never>
//      ▼
const program = Effect.repeat(
  Console.log("running..."),
  Schedule.spaced("200 millis")
)

//      ┌─── RuntimeFiber<number, never>
//      ▼
const fiber = Effect.runFork(program)

setTimeout(() => {
  Effect.runFork(Fiber.interrupt(fiber))
}, 500)
@since ― 2.0.0
runFork(
const program: (url: string) => Effect.Effect<unknown, never, never>
program("https://dummyjson.com/products/1?delay=1000"))
27
/*
28
Output:
29
ok
30
*/
31

32
// Test case: timeout scenario
33
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runFork: <unknown, never>(effect: Effect.Effect<unknown, never, never>, options?: RunForkOptions) => RuntimeFiber<unknown, never>
The foundational function for running effects, returning a "fiber" that can
be observed or interrupted.
When to Use
runFork is used to run an effect in the background by creating a
fiber. It is the base function for all other run functions. It starts a fiber
that can be observed or interrupted.
Unless you specifically need a Promise or synchronous operation,
runFork is a good default choice.
@example 
// Title: Running an Effect in the Background
import { Effect, Console, Schedule, Fiber } from "effect"

//      ┌─── Effect<number, never, never>
//      ▼
const program = Effect.repeat(
  Console.log("running..."),
  Schedule.spaced("200 millis")
)

//      ┌─── RuntimeFiber<number, never>
//      ▼
const fiber = Effect.runFork(program)

setTimeout(() => {
  Effect.runFork(Fiber.interrupt(fiber))
}, 500)
@since ― 2.0.0
runFork(
const program: (url: string) => Effect.Effect<unknown, never, never>
program("https://dummyjson.com/products/1?delay=5000"))
34
/*
35
Output:
36
TimeoutException: Operation timed out before the specified duration of '4s' elapsed
37
*/
38

39
// Test case: API error handling
40
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runFork: <unknown, never>(effect: Effect.Effect<unknown, never, never>, options?: RunForkOptions) => RuntimeFiber<unknown, never>
The foundational function for running effects, returning a "fiber" that can
be observed or interrupted.
When to Use
runFork is used to run an effect in the background by creating a
fiber. It is the base function for all other run functions. It starts a fiber
that can be observed or interrupted.
Unless you specifically need a Promise or synchronous operation,
runFork is a good default choice.
@example 
// Title: Running an Effect in the Background
import { Effect, Console, Schedule, Fiber } from "effect"

//      ┌─── Effect<number, never, never>
//      ▼
const program = Effect.repeat(
  Console.log("running..."),
  Schedule.spaced("200 millis")
)

//      ┌─── RuntimeFiber<number, never>
//      ▼
const fiber = Effect.runFork(program)

setTimeout(() => {
  Effect.runFork(Fiber.interrupt(fiber))
}, 500)
@since ― 2.0.0
runFork(
const program: (url: string) => Effect.Effect<unknown, never, never>
program("https://dummyjson.com/auth/products/1?delay=500"))
41
/*
42
Output:
43
error
44
error
45
error
46
UnknownException: An unknown error occurred
47
*/

Implementing Conditional Retries

Sometimes, we need to retry a failed API call only for specific error conditions, such as certain HTTP status codes.

1
import { 
import Console
Console, 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from "effect"
2

3
// Custom error class for handling status codes
4
class 
class Err
Err extends 
var Error: ErrorConstructor
Error {
5
  constructor(
message: string
message: string, readonly 
Err.status: number
status: number) {
6
    super(
message: string
message)
7
  }
8
}
9

10
// Function to make the API call
11
const 
const getJson: (url: string) => Effect.Effect<unknown, Err, never>
getJson = (
url: string
url: string) =>
12
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const tryPromise: <unknown, Err>(options: {
    readonly try: (signal: AbortSignal) => PromiseLike<unknown>;
    readonly catch: (error: unknown) => Err;
}) => Effect.Effect<unknown, Err, never> (+1 overload)
Creates an Effect that represents an asynchronous computation that might
fail.
When to Use
In situations where you need to perform asynchronous operations that might
fail, such as fetching data from an API, you can use the tryPromise
constructor. This constructor is designed to handle operations that could
throw exceptions by capturing those exceptions and transforming them into
manageable errors.
Error Handling
There are two ways to handle errors with tryPromise:

If you don't provide a catch function, the error is caught and the
effect fails with an UnknownException.
If you provide a catch function, the error is caught and the catch
function maps it to an error of type E.

Interruptions
An optional AbortSignal can be provided to allow for interruption of the
wrapped Promise API.
@see ― promise if the effectful computation is asynchronous and does not throw errors.
@example 
// Title: Fetching a TODO Item
import { Effect } from "effect"

const getTodo = (id: number) =>
  // Will catch any errors and propagate them as UnknownException
  Effect.tryPromise(() =>
    fetch(`https://jsonplaceholder.typicode.com/todos/${id}`)
  )

//      ┌─── Effect<Response, UnknownException, never>
//      ▼
const program = getTodo(1)
@example 
// Title: Custom Error Handling
import { Effect } from "effect"
const getTodo = (id: number) =>
Effect.tryPromise({
try: () => fetch(https://jsonplaceholder.typicode.com/todos/${id}),
// remap the error
catch: (unknown) => new Error(something went wrong ${unknown})
})
//      ┌─── Effect<Response, Error, never>
//      ▼
const program = getTodo(1)
@since ― 2.0.0
tryPromise({
13
    
try: (signal: AbortSignal) => PromiseLike<unknown>
try: () =>
14
      
function fetch(input: string | URL | globalThis.Request, init?: RequestInit): Promise<Response>
fetch(
url: string
url).
Promise<Response>.then<unknown, never>(onfulfilled?: ((value: Response) => unknown) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<unknown>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param ― onfulfilled The callback to execute when the Promise is resolved.
@param ― onrejected The callback to execute when the Promise is rejected.
@returns ― A Promise for the completion of which ever callback is executed.
then((
res: Response
res) => {
15
        if (!
res: Response
res.
Response.ok: boolean
ok) {
16
          
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
globalThis.Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log(
res: Response
res.
Response.status: number
status)
17
          throw new 
constructor Err(message: string, status: number): Err
Err(
res: Response
res.
Response.statusText: string
statusText, 
res: Response
res.
Response.status: number
status)
18
        }
19
        return 
res: Response
res.
BodyMixin.json: () => Promise<unknown>
json() as unknown
20
      }),
21
    
catch: (error: unknown) => Err
catch: (
e: unknown
e) => 
e: unknown
e as 
class Err
Err
22
  })
23

24
// Program that retries only for 401 status codes
25
const 
const program: (url: string) => Effect.Effect<unknown, never, never>
program = (
url: string
url: string) =>
26
  
const getJson: (url: string) => Effect.Effect<unknown, Err, never>
getJson(
url: string
url).
Pipeable.pipe<Effect.Effect<unknown, Err, never>, Effect.Effect<unknown, Err, never>, Effect.Effect<unknown, never, never>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<unknown, Err, never>) => Effect.Effect<...>, bc: (_: Effect.Effect<...>) => Effect.Effect<...>): Effect.Effect<...> (+21 overloads)
pipe(
27
    
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const retry: <Err, {
    while: (err: Err) => boolean;
}>(options: {
    while: (err: Err) => boolean;
}) => <A, R>(self: Effect.Effect<A, Err, R>) => Effect.Effect<A, Err, R> (+3 overloads)
Retries a failing effect based on a defined retry policy.
Details
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.
When to Use
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.
@see ― retryOrElse for a version that allows you to run a fallback.
@see ― repeat if your retry condition is based on successful outcomes rather than errors.
@example 
// Title: Retrying with a Fixed Delay
import { Effect, Schedule } from "effect"

let count = 0

// Simulates an effect with possible failures
const task = Effect.async<string, Error>((resume) => {
  if (count <= 2) {
    count++
    console.log("failure")
    resume(Effect.fail(new Error()))
  } else {
    console.log("success")
    resume(Effect.succeed("yay!"))
  }
})

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

const repeated = Effect.retry(task, policy)

Effect.runPromise(repeated).then(console.log)
// Output:
// failure
// failure
// failure
// success
// yay!
@example 
// Title: Retrying a Task up to 5 times
import { Effect } from "effect"

let count = 0

// Simulates an effect with possible failures
const task = Effect.async<string, Error>((resume) => {
  if (count <= 2) {
    count++
    console.log("failure")
    resume(Effect.fail(new Error()))
  } else {
    console.log("success")
    resume(Effect.succeed("yay!"))
  }
})

// Retry the task up to 5 times
Effect.runPromise(Effect.retry(task, { times: 5 }))
// Output:
// failure
// failure
// failure
// success
@example 
// Title: Retrying Until a Specific Condition is Met
import { Effect } from "effect"

let count = 0

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

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

Effect.runPromiseExit(program).then(console.log)
// Output:
// Action called 1 time(s)
// Action called 2 time(s)
// Action called 3 time(s)
// {
//   _id: 'Exit',
//   _tag: 'Failure',
//   cause: { _id: 'Cause', _tag: 'Fail', failure: 'Error 3' }
// }
@since ― 2.0.0
retry({ 
while: (err: Err) => boolean
while: (
err: Err
err) => 
err: Err
err.
Err.status: number
status === 401 }),
28
    
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const catchAll: <any, void, never, never>(f: (e: any) => Effect.Effect<void, never, never>) => <A, R>(self: Effect.Effect<A, any, R>) => Effect.Effect<void | A, never, R> (+1 overload)
Handles all errors in an effect by providing a fallback effect.
Details
This function catches any errors that may occur during the execution of an
effect and allows you to handle them by specifying a fallback effect. This
ensures that the program continues without failing by recovering from errors
using the provided fallback logic.
Note: This function only handles recoverable errors. It will not recover
from unrecoverable defects.
@see ― catchAllCause for a version that can recover from both
recoverable and unrecoverable errors.
@example 
// Title: Providing Recovery Logic for Recoverable Errors
import { Effect, Random } from "effect"

class HttpError {
  readonly _tag = "HttpError"
}

class ValidationError {
  readonly _tag = "ValidationError"
}

//      ┌─── Effect<string, HttpError | ValidationError, never>
//      ▼
const program = Effect.gen(function* () {
  const n1 = yield* Random.next
  const n2 = yield* Random.next
  if (n1 < 0.5) {
    yield* Effect.fail(new HttpError())
  }
  if (n2 < 0.5) {
    yield* Effect.fail(new ValidationError())
  }
  return "some result"
})

//      ┌─── Effect<string, never, never>
//      ▼
const recovered = program.pipe(
  Effect.catchAll((error) =>
    Effect.succeed(`Recovering from ${error._tag}`)
  )
)
@since ― 2.0.0
catchAll(
import Console
Console.
const error: (...args: ReadonlyArray<any>) => Effect.Effect<void>@since ― 2.0.0
error)
29
  )
30

31
// Test the 401 scenario
32
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runFork: <unknown, never>(effect: Effect.Effect<unknown, never, never>, options?: RunForkOptions) => RuntimeFiber<unknown, never>
The foundational function for running effects, returning a "fiber" that can
be observed or interrupted.
When to Use
runFork is used to run an effect in the background by creating a
fiber. It is the base function for all other run functions. It starts a fiber
that can be observed or interrupted.
Unless you specifically need a Promise or synchronous operation,
runFork is a good default choice.
@example 
// Title: Running an Effect in the Background
import { Effect, Console, Schedule, Fiber } from "effect"

//      ┌─── Effect<number, never, never>
//      ▼
const program = Effect.repeat(
  Console.log("running..."),
  Schedule.spaced("200 millis")
)

//      ┌─── RuntimeFiber<number, never>
//      ▼
const fiber = Effect.runFork(program)

setTimeout(() => {
  Effect.runFork(Fiber.interrupt(fiber))
}, 500)
@since ― 2.0.0
runFork(
33
  
const program: (url: string) => Effect.Effect<unknown, never, never>
program("https://dummyjson.com/auth/products/1?delay=1000")
34
)
35
/*
36
Output:
37
401
38
401
39
401
40
401
41
...
42
*/
43

44
// Test the 404 scenario
45
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runFork: <unknown, never>(effect: Effect.Effect<unknown, never, never>, options?: RunForkOptions) => RuntimeFiber<unknown, never>
The foundational function for running effects, returning a "fiber" that can
be observed or interrupted.
When to Use
runFork is used to run an effect in the background by creating a
fiber. It is the base function for all other run functions. It starts a fiber
that can be observed or interrupted.
Unless you specifically need a Promise or synchronous operation,
runFork is a good default choice.
@example 
// Title: Running an Effect in the Background
import { Effect, Console, Schedule, Fiber } from "effect"

//      ┌─── Effect<number, never, never>
//      ▼
const program = Effect.repeat(
  Console.log("running..."),
  Schedule.spaced("200 millis")
)

//      ┌─── RuntimeFiber<number, never>
//      ▼
const fiber = Effect.runFork(program)

setTimeout(() => {
  Effect.runFork(Fiber.interrupt(fiber))
}, 500)
@since ― 2.0.0
runFork(
const program: (url: string) => Effect.Effect<unknown, never, never>
program("https://dummyjson.com/-"))
46
/*
47
Output:
48
404
49
Err [Error]: Not Found
50
*/

Running Scheduled Effects Until Completion

Sometimes, we need to run a task periodically until a longer-running task completes. This is common in scenarios like polling or periodic status logging.

1
import { 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect, 
import Console
Console, 
import Schedule
Schedule } from "effect"
2

3
const 
const longRunningEffect: Effect.Effect<void, never, never>
longRunningEffect = 
import Console
Console.
const log: (...args: ReadonlyArray<any>) => Effect.Effect<void>@since ― 2.0.0
log("done").
Pipeable.pipe<Effect.Effect<void, never, never>, Effect.Effect<void, never, never>>(this: Effect.Effect<...>, ab: (_: Effect.Effect<void, never, never>) => Effect.Effect<void, never, never>): Effect.Effect<...> (+21 overloads)
pipe(
4
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const delay: (duration: DurationInput) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R> (+1 overload)
Returns an effect that is delayed from this effect by the specified
Duration.
@since ― 2.0.0
delay("5 seconds")
5
)
6

7
const 
const action: Effect.Effect<void, never, never>
action = 
import Console
Console.
const log: (...args: ReadonlyArray<any>) => Effect.Effect<void>@since ― 2.0.0
log("action...")
8

9
const 
const schedule: Schedule.Schedule<number, unknown, never>
schedule = 
import Schedule
Schedule.
const fixed: (interval: DurationInput) => Schedule.Schedule<number>
A schedule that recurs on a fixed interval. Returns the number of
repetitions of the schedule so far.
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|-----------|
@since ― 2.0.0
fixed("1.5 seconds")
10

11
const 
const program: Effect.Effect<number | void, never, never>
program = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const race: <number, never, never, void, never, never>(self: Effect.Effect<number, never, never>, that: Effect.Effect<void, never, never>) => Effect.Effect<number | void, never, never> (+1 overload)
Races two effects and returns the result of the first successful one.
Details
This function takes two effects and runs them concurrently. The first effect
that successfully completes will determine the result of the race, and the
other effect will be interrupted.
If neither effect succeeds, the function will fail with a Cause
containing all the errors.
When to Use
This is useful when you want to run two effects concurrently, but only care
about the first one to succeed. It is commonly used in cases like timeouts,
retries, or when you want to optimize for the faster response without
worrying about the other effect.
Handling Success or Failure with Either
If you want to handle the result of whichever task completes first, whether
it succeeds or fails, you can use the Effect.either function. This function
wraps the result in an Either type, allowing you to see if the result
was a success (Right) or a failure (Left).
@see ― raceAll for a version that handles multiple effects.
@see ― raceFirst for a version that returns the result of the first effect to complete.
@example 
// Title: Both Tasks Succeed
import { Effect, Console } from "effect"

const task1 = Effect.succeed("task1").pipe(
  Effect.delay("200 millis"),
  Effect.tap(Console.log("task1 done")),
  Effect.onInterrupt(() => Console.log("task1 interrupted"))
)
const task2 = Effect.succeed("task2").pipe(
  Effect.delay("100 millis"),
  Effect.tap(Console.log("task2 done")),
  Effect.onInterrupt(() => Console.log("task2 interrupted"))
)

const program = Effect.race(task1, task2)

Effect.runFork(program)
// Output:
// task1 done
// task2 interrupted
@example 
// Title: One Task Fails, One Succeeds
import { Effect, Console } from "effect"

const task1 = Effect.fail("task1").pipe(
  Effect.delay("100 millis"),
  Effect.tap(Console.log("task1 done")),
  Effect.onInterrupt(() => Console.log("task1 interrupted"))
)
const task2 = Effect.succeed("task2").pipe(
  Effect.delay("200 millis"),
  Effect.tap(Console.log("task2 done")),
  Effect.onInterrupt(() => Console.log("task2 interrupted"))
)

const program = Effect.race(task1, task2)

Effect.runFork(program)
// Output:
// task2 done
@example 
// Title: Both Tasks Fail
import { Effect, Console } from "effect"

const task1 = Effect.fail("task1").pipe(
  Effect.delay("100 millis"),
  Effect.tap(Console.log("task1 done")),
  Effect.onInterrupt(() => Console.log("task1 interrupted"))
)
const task2 = Effect.fail("task2").pipe(
  Effect.delay("200 millis"),
  Effect.tap(Console.log("task2 done")),
  Effect.onInterrupt(() => Console.log("task2 interrupted"))
)

const program = Effect.race(task1, task2)

Effect.runPromiseExit(program).then(console.log)
// Output:
// {
//   _id: 'Exit',
//   _tag: 'Failure',
//   cause: {
//     _id: 'Cause',
//     _tag: 'Parallel',
//     left: { _id: 'Cause', _tag: 'Fail', failure: 'task1' },
//     right: { _id: 'Cause', _tag: 'Fail', failure: 'task2' }
//   }
// }
@example 
// Title: Handling Success or Failure with Either
import { Effect, Console } from "effect"

const task1 = Effect.fail("task1").pipe(
  Effect.delay("100 millis"),
  Effect.tap(Console.log("task1 done")),
  Effect.onInterrupt(() => Console.log("task1 interrupted"))
)
const task2 = Effect.succeed("task2").pipe(
  Effect.delay("200 millis"),
  Effect.tap(Console.log("task2 done")),
  Effect.onInterrupt(() => Console.log("task2 interrupted"))
)

// Run both tasks concurrently, wrapping the result
// in Either to capture success or failure
const program = Effect.race(Effect.either(task1), Effect.either(task2))

Effect.runPromise(program).then(console.log)
// Output:
// task2 interrupted
// { _id: 'Either', _tag: 'Left', left: 'task1' }
@since ― 2.0.0
race(
12
  
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const repeat: <void, never, never, number, never>(self: Effect.Effect<void, never, never>, schedule: Schedule.Schedule<number, void, never>) => Effect.Effect<number, never, never> (+3 overloads)
The repeat function returns a new effect that repeats the given effect
according to a specified schedule or until the first failure. The scheduled
recurrences are in addition to the initial execution, so repeat(action, Schedule.once) executes action once initially, and if it succeeds, repeats it
an additional time.
@example 
// Success Example
import { Effect, Schedule, Console } from "effect"

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

Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
@example 
// Failure Example
import { Effect, Schedule } from "effect"
let count = 0
// Define an async effect that simulates an action with possible failures
const action = Effect.async<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), () => "100 millis")
const program = Effect.repeat(action, policy)
Effect.runPromiseExit(program).then(console.log)
@since ― 2.0.0
repeat(
const action: Effect.Effect<void, never, never>
action, 
const schedule: Schedule.Schedule<number, unknown, never>
schedule),
13
  
const longRunningEffect: Effect.Effect<void, never, never>
longRunningEffect
14
)
15

16
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const runPromise: <number | void, never>(effect: Effect.Effect<number | void, never, never>, options?: {
    readonly signal?: AbortSignal;
} | undefined) => Promise<number | void>
Executes an effect and returns the result as a Promise.
When to Use
Use runPromise when you need to execute an effect and work with the
result using Promise syntax, typically for compatibility with other
promise-based code.
If the effect succeeds, the promise will resolve with the result. If the
effect fails, the promise will reject with an error.
@see ― runPromiseExit for a version that returns an Exit type instead of rejecting.
@example 
// Title: Running a Successful Effect as a Promise
import { Effect } from "effect"

Effect.runPromise(Effect.succeed(1)).then(console.log)
// Output: 1
@example 
//Example: Handling a Failing Effect as a Rejected Promise
import { Effect } from "effect"
Effect.runPromise(Effect.fail("my error")).catch(console.error)
// Output:
// (FiberFailure) Error: my error
@since ― 2.0.0
runPromise(
const program: Effect.Effect<number | void, never, never>
program)
17
/*
18
Output:
19
action...
20
action...
21
action...
22
action...
23
done
24
*/