Simplifying Excessive Nesting

Suppose you want to create a custom function elapsed that prints the elapsed time taken by an effect to execute.

Using plain pipe

Initially, you may come up with code that uses the standard pipe method, but this approach can lead to excessive nesting and result in verbose and hard-to-read code:

Example (Measuring Elapsed Time with pipe)

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

3
// Get the current timestamp
4
const now = Effect.sync(() => new Date().getTime())
5

6
// Prints the elapsed time occurred to `self` to execute
7
const elapsed = <R, E, A>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
8
  now.pipe(
9
    Effect.andThen((startMillis) =>
10
      self.pipe(
11
        Effect.andThen((result) =>
12
          now.pipe(
13
            Effect.andThen((endMillis) => {
14
              // Calculate the elapsed time in milliseconds
15
              const elapsed = endMillis - startMillis
16
              // Log the elapsed time
17
              return Console.log(`Elapsed: ${elapsed}`).pipe(Effect.map(() => result))
18
            }),
19
          ),
20
        ),
21
      ),
22
    ),
23
  )
24

25
// Simulates a successful computation with a delay of 200 milliseconds
26
const task = Effect.succeed("some task").pipe(Effect.delay("200 millis"))
27

28
const program = elapsed(task)
29

30
Effect.runPromise(program).then(console.log)
31
/*
32
Output:
33
Elapsed: 204
34
some task
35
*/

To address this issue and make the code more manageable, there is a solution: the “do simulation.”

Using the “do simulation”

The “do simulation” in Effect allows you to write code in a more declarative style, similar to the “do notation” in other programming languages. It provides a way to define variables and perform operations on them using functions like Effect.bind and Effect.let.

Here’s how the do simulation works:

Start the do simulation using the Effect.Do value:

const program = Effect.Do.pipe(/* ... rest of the code */)

Within the do simulation scope, you can use the Effect.bind function to define variables and bind them to Effect values:
```
Effect.bind("variableName", (scope) => effectValue)
```
- variableName is the name you choose for the variable you want to define. It must be unique within the scope.
- effectValue is the Effect value that you want to bind to the variable. It can be the result of a function call or any other valid Effect value.

You can accumulate multiple Effect.bind statements to define multiple variables within the scope:

Effect.bind("variable1", () => effectValue1),
Effect.bind("variable2", ({ variable1 }) => effectValue2),
// ... additional bind statements

Inside the do simulation scope, you can also use the Effect.let function to define variables and bind them to simple values:
```
Effect.let("variableName", (scope) => simpleValue)
```
- variableName is the name you give to the variable. Like before, it must be unique within the scope.
- simpleValue is the value you want to assign to the variable. It can be a simple value like a number, string, or boolean.
Regular Effect functions like Effect.andThen, Effect.flatMap, Effect.tap, and Effect.map can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope:
```
Effect.andThen(({ variable1, variable2 }) => {
  // Perform operations using variable1 and variable2
  // Return an `Effect` value as the result
})
```

With the do simulation, you can rewrite the elapsed function like this:

Example (Using Do Simulation to Measure Elapsed Time)

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

3
// Get the current timestamp
4
const now = Effect.sync(() => new Date().getTime())
5

6
const elapsed = <R, E, A>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
7
  Effect.Do.pipe(
8
    Effect.bind("startMillis", () => now),
9
    Effect.bind("result", () => self),
10
    Effect.bind("endMillis", () => now),
11
    Effect.let(
12
      "elapsed",
13
      // Calculate the elapsed time in milliseconds
14
      ({ startMillis, endMillis }) => endMillis - startMillis,
15
    ),
16
    // Log the elapsed time
17
    Effect.tap(({ elapsed }) => Console.log(`Elapsed: ${elapsed}`)),
18
    Effect.map(({ result }) => result),
19
  )
20

21
// Simulates a successful computation with a delay of 200 milliseconds
22
const task = Effect.succeed("some task").pipe(Effect.delay("200 millis"))
23

24
const program = elapsed(task)
25

26
Effect.runPromise(program).then(console.log)
27
/*
28
Output:
29
Elapsed: 204
30
some task
31
*/

Using Effect.gen

The most concise and convenient solution is to use Effect.gen, which allows you to work with generators when dealing with effects. This approach leverages the native scope provided by the generator syntax, avoiding excessive nesting and leading to more concise code.

Example (Using Effect.gen to Measure Elapsed Time)

1
import { Effect } from "effect"
2

3
// Get the current timestamp
4
const now = Effect.sync(() => new Date().getTime())
5

6
// Prints the elapsed time occurred to `self` to execute
7
const elapsed = <R, E, A>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
8
  Effect.gen(function* () {
9
    const startMillis = yield* now
10
    const result = yield* self
11
    const endMillis = yield* now
12
    // Calculate the elapsed time in milliseconds
13
    const elapsed = endMillis - startMillis
14
    // Log the elapsed time
15
    console.log(`Elapsed: ${elapsed}`)
16
    return result
17
  })
18

19
// Simulates a successful computation with a delay of 200 milliseconds
20
const task = Effect.succeed("some task").pipe(Effect.delay("200 millis"))
21

22
const program = elapsed(task)
23

24
Effect.runPromise(program).then(console.log)
25
/*
26
Output:
27
Elapsed: 204
28
some task
29
*/

Within the generator, we use yield* to invoke effects and bind their results to variables. This eliminates the nesting and provides a more readable and sequential code structure.

The generator style in Effect uses a more linear and sequential flow of execution, resembling traditional imperative programming languages. This makes the code easier to read and understand, especially for developers who are more familiar with imperative programming paradigms.