Running Effects

To execute an effect, we can utilize a variety of “run” functions provided by the Effect module.

Tip

The recommended approach is to design your program with the majority of its logic as Effects. It’s advisable to use the run* functions closer to the “edge” of your program. This approach allows for greater flexibility in executing your program and building sophisticated Effects.

runSync

The Effect.runSync function is used to execute an effect synchronously, which means it runs immediately and returns the result.

Example

import { Effect } from "effect"

const program = Effect.sync(() => {
  console.log("Hello, World!")
  return 1
})

const result = Effect.runSync(program)
// Output: Hello, World!

console.log(result)
// Output: 1

The Effect.runSync function will throw an error if your effect fails or performs any asynchronous tasks. In the latter case, the execution will not proceed beyond that asynchronous task:

import { Effect } from "effect"

Effect.runSync(Effect.fail("my error")) // throws

Effect.runSync(Effect.promise(() => Promise.resolve(1))) // throws

runSyncExit

The Effect.runSyncExit function is used to execute an effect synchronously, which means it runs immediately and returns the result as an Exit (a data type used to describe the result of executing an effect workflow).

Example

import { Effect } from "effect"

const result1 = Effect.runSyncExit(Effect.succeed(1))
console.log(result1)
/*
Output:
{
  _id: "Exit",
  _tag: "Success",
  value: 1
}
*/

const result2 = Effect.runSyncExit(Effect.fail("my error"))
console.log(result2)
/*
Output:
{
  _id: "Exit",
  _tag: "Failure",
  cause: {
    _id: "Cause",
    _tag: "Fail",
    failure: "my error"
  }
}
*/

The Effect.runSyncExit function will throw an error if your effect performs any asynchronous tasks and the execution will not proceed beyond that asynchronous task:

import { Effect } from "effect"

Effect.runSyncExit(Effect.promise(() => Promise.resolve(1))) // throws

runPromise

The Effect.runPromise function is used to execute an effect and obtain the result as a Promise.

import { Effect } from "effect"

Effect.runPromise(Effect.succeed(1)).then(console.log) // Output: 1

The Effect.runPromise function will reject with an error if your Effect fails:

import { Effect } from "effect"

Effect.runPromise(Effect.fail("my error")) // rejects

runPromiseExit

The Effect.runPromiseExit function is used to execute an Effect and obtain the result as a Promise that resolves to an Exit (a data type used to describe the result of executing an Effect workflow).

import { Effect } from "effect"

Effect.runPromiseExit(Effect.succeed(1)).then(console.log)
/*
Output:
{
  _id: "Exit",
  _tag: "Success",
  value: 1
}
*/

Effect.runPromiseExit(Effect.fail("my error")).then(console.log)
/*
Output:
{
  _id: "Exit",
  _tag: "Failure",
  cause: {
    _id: "Cause",
    _tag: "Fail",
    failure: "my error"
  }
}
*/

runFork

The Effect.runFork function serves as a foundational building block for running effects. In fact, all other run functions are built upon it. Unless you have a specific need for a Promise or a synchronous operation, Effect.runFork is the recommended choice. It returns a fiber that you can observe or interrupt as needed.

import { Effect, Console, Schedule, Fiber } from "effect"

const program = Effect.repeat(
  Console.log("running..."),
  Schedule.spaced("200 millis")
)

const fiber = Effect.runFork(program)

setTimeout(() => {
  Effect.runFork(Fiber.interrupt(fiber))
}, 500)

In this example, the program continuously logs “running…” with each repetition spaced 200 milliseconds apart. You can learn more about repetitions and scheduling in our Introduction to Scheduling guide.

To stop the execution of the program, we use Fiber.interrupt on the fiber returned by Effect.runFork. This allows you to control the execution flow and terminate it when necessary.

For a deeper understanding of how fibers work and how to handle interruptions, check out our guides on Fibers and Interruptions.

Synchronous vs. Asynchronous Effects

In the Effect library, there is no built-in way to determine in advance whether an effect will execute synchronously or asynchronously. While this idea was considered in earlier versions of Effect, it was ultimately not implemented for a few important reasons:

1. Complexity: Introducing this feature to track sync/async behavior in the type system would make Effect more complex to use and limit its composability.

2. Safety Concerns: We experimented with different approaches to track asynchronous Effects, but they all resulted in a worse developer experience without significantly improving safety. Even with fully synchronous types, we needed to support a fromCallback combinator to work with APIs using Continuation-Passing Style (CPS). However, at the type level, it’s impossible to guarantee that such a function is always called immediately and not deferred.

Best Practices for Running Effects

In most cases, effects are run at the outermost parts of your application. Typically, an application built around Effect will involve a single call to the main effect. Here’s how you should approach effect execution:

• Use runPromise or runFork: For most cases, asynchronous execution should be the default. These methods provide the best way to handle Effect-based workflows.

• Use runSync only when necessary: Synchronous execution should be considered an edge case, used only in scenarios where asynchronous execution is not feasible. For example, when you are sure the effect is purely synchronous and need immediate results.

Cheatsheet

The table provides a summary of the available run* functions, along with their input and output types, allowing you to choose the appropriate function based on your needs.

API	Given	To
runSync	Effect<A, E>	A
runSyncExit	Effect<A, E>	Exit<A, E>
runPromise	Effect<A, E>	Promise<A>
runPromiseExit	Effect<A, E>	Promise<Exit<A, E>>
runFork	Effect<A, E>	RuntimeFiber<A, E>

You can find the complete list of run* functions here.