Control Flow Operators

Even though JavaScript provides built-in control flow structures, Effect offers additional control flow functions that are useful in Effect applications. In this section, we will introduce different ways to control the flow of execution.

if Expression

When working with Effect values, we can use standard JavaScript if-then-else statements:

Example (Returning None for Invalid Weight)

Here we are using the Option data type to represent the absence of a valid value.

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

3
// Function to validate weight and return an Option
4
const validateWeightOption = (
5
  weight: number,
6
): Effect.Effect<Option.Option<number>> => {
7
  if (weight >= 0) {
8
    // Return Some if the weight is valid
9
    return Effect.succeed(Option.some(weight))
10
  } else {
11
    // Return None if the weight is invalid
12
    return Effect.succeed(Option.none())
13
  }
14
}
15

16
await Effect.runPromise(validateWeightOption(5)) // => Option.some(5)
17
await Effect.runPromise(validateWeightOption(-5)) // => Option.none()

Example (Returning Error for Invalid Weight)

You can also handle invalid inputs by using the error channel, which allows you to return an error when the input is invalid:

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

3
// Function to validate weight or fail with an error
4
const validateWeightOrFail = (
5
  weight: number,
6
): Effect.Effect<number, string> => {
7
  if (weight >= 0) {
8
    // Return the weight if valid
9
    return Effect.succeed(weight)
10
  } else {
11
    // Fail with an error if invalid
12
    return Effect.fail(`negative input: ${weight}`)
13
  }
14
}
15

16
await Effect.runPromise(validateWeightOrFail(5)) // => 5
17
await Effect.runPromiseExit(validateWeightOrFail(-5)) // => Exit.fail("negative input: -5")

Conditional Operators

when

Executes an effect conditionally, based on the result of another effect.

Use Effect.when when the condition to determine whether to execute the effect depends on the outcome of another effect that produces a boolean value. If the condition effect evaluates to true, the specified effect is executed. If it evaluates to false, no effect is executed.

The result of the effect is wrapped in an Option<A> to indicate whether the effect was executed. If the condition is true, the result of the effect is wrapped in a Some. If the condition is false, the result is None, representing that the effect was skipped.

Example (Using an Effect as a Condition)

The following function creates a random integer, but only if a randomly generated boolean is true.

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

3
const randomIntOption = Random.nextInt.pipe(Effect.when(Random.nextBoolean))
4

5
console.log(Effect.runSync(randomIntOption))
6
/*
7
Example Output:
8
{ _id: 'Option', _tag: 'Some', value: 8609104974198840 }
9
*/

Zipping

zip

Combines two effects into a single effect, producing a tuple with the results of both effects.

The Effect.zip function executes the first effect (left) and then the second effect (right). Once both effects succeed, their results are combined into a tuple.

Example (Combining Two Effects Sequentially)

1
import { Effect } from "effect"
2

3
const task1 = Effect.succeed(1).pipe(
4
  Effect.delay("200 millis"),
5
  Effect.tap(Effect.log("task1 done")),
6
)
7

8
const task2 = Effect.succeed("hello").pipe(
9
  Effect.delay("100 millis"),
10
  Effect.tap(Effect.log("task2 done")),
11
)
12

13
// Combine the two effects together
14
//
15
//      ┌─── Effect<[number, string], never, never>
16
//      ▼
17
const program = Effect.zip(task1, task2)
18

19
const result = await Effect.runPromise(program) // => [1, "hello"]
20
console.log(result)
21
/*
22
Output:
23
timestamp=... level=INFO fiber=#0 message="task1 done"
24
timestamp=... level=INFO fiber=#0 message="task2 done"
25
*/

By default, the effects are run sequentially. To run them concurrently, use the { concurrent: true } option.

Example (Combining Two Effects Concurrently)

1
import { Effect } from "effect"
2

9 collapsed lines
3
const task1 = Effect.succeed(1).pipe(
4
  Effect.delay("200 millis"),
5
  Effect.tap(Effect.log("task1 done")),
6
)
7

8
const task2 = Effect.succeed("hello").pipe(
9
  Effect.delay("100 millis"),
10
  Effect.tap(Effect.log("task2 done")),
11
)
12

13
// Run both effects concurrently using the concurrent option
14
const program = Effect.zip(task1, task2, { concurrent: true })
15

16
const result = await Effect.runPromise(program) // => [1, "hello"]
17
console.log(result)
18
/*
19
Output:
20
timestamp=... level=INFO fiber=#3 message="task2 done"
21
timestamp=... level=INFO fiber=#2 message="task1 done"
22
*/

In this concurrent version, both effects run in parallel. task2 completes first, but both tasks can be logged and processed as soon as they’re done.

zipWith

Combines two effects sequentially and applies a function to their results to produce a single value.

The Effect.zipWith function is similar to Effect.zip, but instead of returning a tuple of results, it applies a provided function to the results of the two effects, combining them into a single value.

By default, the effects are run sequentially. To run them concurrently, use the { concurrent: true } option.

Example (Combining Effects with a Custom Function)

1
import { Effect } from "effect"
2

3
const task1 = Effect.succeed(1).pipe(
4
  Effect.delay("200 millis"),
5
  Effect.tap(Effect.log("task1 done")),
6
)
7
const task2 = Effect.succeed("hello").pipe(
8
  Effect.delay("100 millis"),
9
  Effect.tap(Effect.log("task2 done")),
10
)
11

12
//      ┌─── Effect<number, never, never>
13
//      ▼
14
const task3 = Effect.zipWith(
15
  task1,
16
  task2,
17
  // Combines results into a single value
18
  (number, string) => number + string.length,
19
)
20

21
const result = await Effect.runPromise(task3) // => 6
22
console.log(result)
23
/*
24
Output:
25
timestamp=... level=INFO fiber=#3 message="task1 done"
26
timestamp=... level=INFO fiber=#2 message="task2 done"
27
*/

Looping

whileLoop

The Effect.whileLoop function allows you to repeatedly update a state using a step function until a condition defined by the while function becomes false. It collects the intermediate states in an array and returns them as the final result.

Syntax

Effect.whileLoop(initial, {
  while: (state) => boolean,
  step: (state) => state,
  body: (state) => Effect,
})

This function is similar to a while loop in JavaScript, with the addition of effectful computations:

let state = initial
const result = []

while (options.while(state)) {
  result.push(options.body(state)) // Perform the effectful operation
  state = options.step(state) // Update the state
}

return result

Example (Looping with Collected Results)

1
import { Effect } from "effect"
2

3
// A loop that runs 5 times, collecting each iteration's result
4
const result = Effect.gen(function* () {
5
  let state = 1
6
  const results: Array<number> = []
7
  while (state <= 5) {
8
    results.push(yield* Effect.succeed(state))
9
    state = state + 1
10
  }
11
  return results
12
})
13

14
const value = await Effect.runPromise(result) // => [1, 2, 3, 4, 5]
15
console.log(value)

In this example, the loop starts with the state 1 and continues until the state exceeds 5. Each state is incremented by 1 and is collected into an array, which becomes the final result.

Discarding Intermediate Results

The discard option, when set to true, will discard the results of each effectful operation, returning void instead of an array.

Example (Loop with Discarded Results)

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

3
// Discard intermediate results
4
const result = Effect.gen(function* () {
5
  let state = 1
6
  while (state <= 5) {
7
    yield* Console.log(`Currently at state ${state}`)
8
    state = state + 1
9
  }
10
})
11

12
const value = await Effect.runPromise(result) // => undefined
13
console.log(value)
14
/*
15
Output:
16
Currently at state 1
17
Currently at state 2
18
Currently at state 3
19
Currently at state 4
20
Currently at state 5
21
*/

In this example, the loop performs a side effect of logging the current index on each iteration, but it discards all intermediate results. The final result is undefined.

forEach

Executes an effectful operation for each element in an Iterable.

The Effect.forEach function applies a provided operation to each element in the iterable, producing a new effect that returns an array of results. If any effect fails, the iteration stops immediately (short-circuiting), and the error is propagated.

The concurrency option controls how many operations are performed concurrently. By default, the operations are performed sequentially.

Example (Applying Effects to Iterable Elements)

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

3
const result = Effect.forEach([1, 2, 3, 4, 5], (n, index) =>
4
  Console.log(`Currently at index ${index}`).pipe(Effect.as(n * 2)),
5
)
6

7
const value = await Effect.runPromise(result) // => [2, 4, 6, 8, 10]
8
console.log(value)
9
/*
10
Output:
11
Currently at index 0
12
Currently at index 1
13
Currently at index 2
14
Currently at index 3
15
Currently at index 4
16
*/

In this example, we iterate over the array [1, 2, 3, 4, 5], applying an effect that logs the current index. The Effect.as(n * 2) operation transforms each value, resulting in an array [2, 4, 6, 8, 10]. The final output is the result of collecting all the transformed values.

Discarding Results

The discard option, when set to true, will discard the results of each effectful operation, returning void instead of an array.

Example (Using discard to Ignore Results)

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

3
// Apply effects but discard the results
4
const result = Effect.forEach(
5
  [1, 2, 3, 4, 5],
6
  (n, index) =>
7
    Console.log(`Currently at index ${index}`).pipe(Effect.as(n * 2)),
8
  { discard: true },
9
)
10

11
const value = await Effect.runPromise(result) // => undefined
12
console.log(value)
13
/*
14
Output:
15
Currently at index 0
16
Currently at index 1
17
Currently at index 2
18
Currently at index 3
19
Currently at index 4
20
*/

In this case, the effects still run for each element, but the results are discarded, so the final output is undefined.

Collecting

all

Combines multiple effects into one, returning results based on the input structure.

Use Effect.all when you need to run multiple effects and combine their results into a single output. It supports tuples, iterables, structs, and records, making it flexible for different input types.

If any effect fails, it stops execution (short-circuiting) and propagates the error. To change this behavior, you can use the mode option, which allows all effects to run and collect results as Result.

You can control the execution order (e.g., sequential vs. concurrent) using the Concurrency Options.

For instance, if the input is a tuple:

//         ┌─── a tuple of effects
//         ▼
Effect.all([effect1, effect2, ...])

the effects are executed sequentially, and the result is a new effect containing the results as a tuple. The results in the tuple match the order of the effects passed to Effect.all.

Let’s explore examples for different types of structures: tuples, iterables, objects, and records.

Example (Combining Effects in Tuples)

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

3
const tupleOfEffects = [
4
  Effect.succeed(42).pipe(Effect.tap(Console.log)),
5
  Effect.succeed("Hello").pipe(Effect.tap(Console.log)),
6
] as const
7

8
//      ┌─── Effect<[number, string], never, never>
9
//      ▼
10
const resultsAsTuple = Effect.all(tupleOfEffects)
11

12
const result = await Effect.runPromise(resultsAsTuple) // => [42, "Hello"]
13
console.log(result)
14
/*
15
Output:
16
42
17
Hello
18
*/

Example (Combining Effects in Iterables)

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

3
const iterableOfEffects: Iterable<Effect.Effect<number>> = [1, 2, 3].map((n) =>
4
  Effect.succeed(n).pipe(Effect.tap(Console.log)),
5
)
6

7
//      ┌─── Effect<number[], never, never>
8
//      ▼
9
const resultsAsArray = Effect.all(iterableOfEffects)
10

11
const result = await Effect.runPromise(resultsAsArray) // => [1, 2, 3]
12
console.log(result)
13
/*
14
Output:
15
1
16
2
17
3
18
*/

Example (Combining Effects in Structs)

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

3
const structOfEffects = {
4
  a: Effect.succeed(42).pipe(Effect.tap(Console.log)),
5
  b: Effect.succeed("Hello").pipe(Effect.tap(Console.log)),
6
}
7

8
//      ┌─── Effect<{ a: number; b: string; }, never, never>
9
//      ▼
10
const resultsAsStruct = Effect.all(structOfEffects)
11

12
const result = await Effect.runPromise(resultsAsStruct) // => { a: 42, b: "Hello" }
13
console.log(result)
14
/*
15
Output:
16
42
17
Hello
18
*/

Example (Combining Effects in Records)

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

3
const recordOfEffects: Record<string, Effect.Effect<number>> = {
4
  key1: Effect.succeed(1).pipe(Effect.tap(Console.log)),
5
  key2: Effect.succeed(2).pipe(Effect.tap(Console.log)),
6
}
7

8
//      ┌─── Effect<{ [x: string]: number; }, never, never>
9
//      ▼
10
const resultsAsRecord = Effect.all(recordOfEffects)
11

12
const result = await Effect.runPromise(resultsAsRecord) // => { key1: 1, key2: 2 }
13
console.log(result)
14
/*
15
Output:
16
1
17
2
18
*/

Short-Circuiting Behavior

The Effect.all function stops execution on the first error it encounters, this is called “short-circuiting”. If any effect in the collection fails, the remaining effects will not run, and the error will be propagated.

Example (Bail Out on First Failure)

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

3
const program = Effect.all([
4
  Effect.succeed("Task1").pipe(Effect.tap(Console.log)),
5
  Effect.fail("Task2: Oh no!").pipe(Effect.tap(Console.log)),
6
  // Won't execute due to earlier failure
7
  Effect.succeed("Task3").pipe(Effect.tap(Console.log)),
8
])
9

10
const result = await Effect.runPromiseExit(program) // => Exit.fail("Task2: Oh no!")
11
console.log(result)
12
/*
13
Output:
14
Task1
15
*/

You can override this behavior by using the mode option.

The `mode` option

The { mode: "result" } option changes the behavior of Effect.all to ensure all effects run, even if some fail. Instead of stopping on the first failure, this mode collects both successes and failures, returning an array of Result instances.

Example (Collecting Results with mode: "result")

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

3
const effects = [
4
  Effect.succeed("Task1").pipe(Effect.tap(Console.log)),
5
  Effect.fail("Task2: Oh no!").pipe(Effect.tap(Console.log)),
6
  Effect.succeed("Task3").pipe(Effect.tap(Console.log)),
7
]
8

9
const program = Effect.all(effects, { mode: "result" })
10

11
const result = await Effect.runPromiseExit(program) // => Exit.succeed([Result.succeed("Task1"), Result.fail("Task2: Oh no!"), Result.succeed("Task3")])
12
console.log(result)
13
/*
14
Output:
15
Task1
16
Task3
17
*/