Introduction

In long-running applications, managing resources efficiently is essential, particularly when building large-scale systems. If resources like socket connections, database connections, or file descriptors are not properly managed, it can lead to resource leaks, which degrade application performance and reliability. Effect provides constructs that help ensure resources are properly managed and released, even in cases where exceptions occur.

By ensuring that every time a resource is acquired, there is a corresponding mechanism to release it, Effect simplifies the process of resource management in your application.

Finalization

In many programming languages, the try / finally construct ensures that cleanup code runs regardless of whether an operation succeeds or fails. Effect provides similar functionality through Effect.ensuring, Effect.onExit, and Effect.onError.

ensuring

The Effect.ensuring function guarantees that a finalizer effect runs whether the main effect succeeds, fails, or is interrupted.

This is useful for performing cleanup actions such as closing file handles, logging messages, or releasing locks.

If you need access to the effect’s result, consider using onExit.

Example (Running a Finalizer in All Outcomes)

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

3
// Define a cleanup effect
4
const handler = Effect.ensuring(Console.log("Cleanup completed"))
5

6
// Define a successful effect
7
const success = Console.log("Task completed").pipe(Effect.as("some result"), handler)
8

9
Effect.runFork(success)
10
/*
11
Output:
12
Task completed
13
Cleanup completed
14
*/
15

16
// Define a failing effect
17
const failure = Console.log("Task failed").pipe(Effect.andThen(Effect.fail("some error")), handler)
18

19
Effect.runFork(failure)
20
/*
21
Output:
22
Task failed
23
Cleanup completed
24
*/
25

26
// Define an interrupted effect
27
const interruption = Console.log("Task interrupted").pipe(Effect.andThen(Effect.interrupt), handler)
28

29
Effect.runFork(interruption)
30
/*
31
Output:
32
Task interrupted
33
Cleanup completed
34
*/

onExit

Effect.onExit allows you to run a cleanup effect after the main effect completes, receiving an Exit value that describes the outcome.

If the effect succeeds, the Exit holds the success value.
If it fails, the Exit includes the error or failure cause.
If it is interrupted, the Exit reflects that interruption.

The cleanup step itself is uninterruptible, which can help manage resources in complex or high-concurrency cases.

Example (Running a Cleanup Function with the Effect’s Result)

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

3
// Define a cleanup effect that logs the result
4
const handler = Effect.onExit((exit) =>
5
  Console.log(`Cleanup completed: ${Exit.getOrElse(exit, String)}`),
6
)
7

8
// Define a successful effect
9
const success = Console.log("Task completed").pipe(Effect.as("some result"), handler)
10

11
Effect.runFork(success)
12
/*
13
Output:
14
Task completed
15
Cleanup completed: some result
16
*/
17

18
// Define a failing effect
19
const failure = Console.log("Task failed").pipe(Effect.andThen(Effect.fail("some error")), handler)
20

21
Effect.runFork(failure)
22
/*
23
Output:
24
Task failed
25
Cleanup completed: Error: some error
26
*/
27

28
// Define an interrupted effect
29
const interruption = Console.log("Task interrupted").pipe(Effect.andThen(Effect.interrupt), handler)
30

31
Effect.runFork(interruption)
32
/*
33
Output:
34
Task interrupted
35
Cleanup completed: All fibers interrupted without errors.
36
*/

onError

This function lets you attach a cleanup effect that runs whenever the calling effect fails, passing the cause of the failure to the cleanup effect.

You can use it to perform actions such as logging, releasing resources, or applying additional recovery steps.

The cleanup effect will also run if the failure is caused by interruption, and it is uninterruptible, so it always finishes once it starts.

Example (Running Cleanup Only on Failure)

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

3
// This handler logs the failure cause when the effect fails
4
const handler = Effect.onError((cause) => Console.log(`Cleanup completed: ${cause}`))
5

6
// Define a successful effect
7
const success = Console.log("Task completed").pipe(Effect.as("some result"), handler)
8

9
Effect.runFork(success)
10
/*
11
Output:
12
Task completed
13
*/
14

15
// Define a failing effect
16
const failure = Console.log("Task failed").pipe(Effect.andThen(Effect.fail("some error")), handler)
17

18
Effect.runFork(failure)
19
/*
20
Output:
21
Task failed
22
Cleanup completed: Error: some error
23
*/
24

25
// Define a failing effect
26
const defect = Console.log("Task failed with defect").pipe(
27
  Effect.andThen(Effect.die("Boom!")),
28
  handler,
29
)
30

31
Effect.runFork(defect)
32
/*
33
Output:
34
Task failed with defect
35
Cleanup completed: Error: Boom!
36
*/
37

38
// Define an interrupted effect
39
const interruption = Console.log("Task interrupted").pipe(Effect.andThen(Effect.interrupt), handler)
40

41
Effect.runFork(interruption)
42
/*
43
Output:
44
Task interrupted
45
Cleanup completed: All fibers interrupted without errors.
46
*/

acquireUseRelease

Many real-world operations involve working with resources that must be released when no longer needed, such as:

Database connections
File handles
Network requests

Effect provides Effect.acquireUseRelease, which ensures that a resource is:

Acquired properly.
Used for its intended purpose.
Released even if an error occurs.

Syntax

Effect.acquireUseRelease(acquire, use, release)

Example (Automatically Managing Resource Lifetime)

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

3
// Define an interface for a resource
4
interface MyResource {
5
  readonly contents: string
6
  readonly close: () => Promise<void>
7
}
8

9
// Simulate resource acquisition
10
const getMyResource = (): Promise<MyResource> =>
11
  Promise.resolve({
12
    contents: "lorem ipsum",
13
    close: () =>
14
      new Promise((resolve) => {
15
        console.log("Resource released")
16
        resolve()
17
      }),
18
  })
19

20
// Define how the resource is acquired
21
const acquire = Effect.tryPromise({
22
  try: () =>
23
    getMyResource().then((res) => {
24
      console.log("Resource acquired")
25
      return res
26
    }),
27
  catch: () => new Error("getMyResourceError"),
28
})
29

30
// Define how the resource is released
31
const release = (res: MyResource) => Effect.promise(() => res.close())
32

33
const use = (res: MyResource) => Console.log(`content is ${res.contents}`)
34

35
//      ┌─── Effect<void, Error, never>
36
//      ▼
37
const program = Effect.acquireUseRelease(acquire, use, release)
38

39
Effect.runPromise(program)
40
/*
41
Output:
42
Resource acquired
43
content is lorem ipsum
44
Resource released
45
*/