Automatic Resource Management with acquireRelease

In the previous chapter, we used Effect’s low-level Scope APIs to open and close a file handle. The resource was properly cleaned up, but we had to remember to call Scope.close on every exit path. Miss one path and the resource leaks. We traded one form of manual bookkeeping for another.

Effect provides two APIs that eliminate this problem entirely: Effect.acquireRelease and Effect.scoped. Together, they let you declare how a resource is opened and closed in one place, and Effect takes care of the rest.

Here is the same demo rewritten using these APIs. Replace the code inside resource-leak-demo.ts with the following:

1
import { mkdtemp, open, rm, writeFile } from "node:fs/promises";
2
import { tmpdir } from "node:os";
3
import { join } from "node:path";
4
import { Effect, Exit, Scope } from "effect";
5

6
let handlesOpened = 0;
7
let handlesClosed = 0;
8

9
function printStatus() {
10
  const handlesLeaked = handlesOpened - handlesClosed;
11
  console.log(
12
    `  Handles opened: ${handlesOpened}  |  Handles closed: ${handlesClosed}  |  Handles leaked: ${handlesLeaked}`,
13
  );
14
}
15

16
class UnsupportedFormatError {
17
  readonly _tag = "UnsupportedFormatError";
18
  constructor(readonly message: string) {}
19
}
20

21
// Create a temporary directory and then create data.txt inside it with some content
22
const tmpDir = await mkdtemp(join(tmpdir(), "leak-demo-"));
23
const filePath = join(tmpDir, "data.txt");
24
await writeFile(filePath, "some important data", "utf-8");
25

26
// The file as a managed resource
27
const managedFile = Effect.acquireRelease(
28
  // acquire: open the file
29
  Effect.promise(async () => {
30
    const fileHandle = await open(filePath, "r");
31
    handlesOpened++;
32
    return fileHandle;
33
  }),
34

35
  // release: close the file
36
  (fileHandle) =>
37
    Effect.promise(async () => {
38
      await fileHandle.close();
39
      handlesClosed++;
40
    }),
41
);
42

43
// Read the data inside data.txt and throw an error if the data contains the term "important"
44
function readData() {
45
  return Effect.scoped(
46
    Effect.gen(function* () {
47
      const fileHandle = yield* managedFile;
48

49
      const content = yield* Effect.promise(() => fileHandle.readFile("utf-8"));
50

51
      if (content.includes("important")) {
52
        return yield* Effect.fail(
53
          new UnsupportedFormatError("Failed to process: unsupported format"),
54
        );
55
      }
56

57
      return content;
58
    }),
59
  );
60
}
61

62
// Run readData 5 times
63
async function main() {
64
  for (let i = 1; i <= 5; i++) {
65
    const result = await Effect.runPromise(
66
      readData().pipe(
67
        Effect.catch(() => Effect.succeed(`error caught and "handled"`)),
68
      ),
69
    );
70
    console.log(`Call ${i}: ${result}`);
71
    printStatus();
72
    console.log();
73
  }
74

75
  // Delete the temporary directory
76
  await rm(tmpDir, { recursive: true, force: true });
77
}
78

79
await main();

Notice that in readData(), there is no Scope.make(), no Scope.addFinalizer(), no Scope.close() on every exit path. Let’s understand how.

Effect.acquireRelease

1
const managedFile = Effect.acquireRelease(
2
  // acquire: open the file
3
  Effect.promise(async () => {
4
    const fileHandle = await open(filePath, "r");
5
    handlesOpened++;
6
    return fileHandle;
7
  }),
8

9
  // release: close the file
10
  (fileHandle) =>
11
    Effect.promise(async () => {
12
      await fileHandle.close();
13
      handlesClosed++;
14
    }),
15
);

Effect.acquireRelease takes two arguments:

• The acquire effect: an Effect that opens or creates the resource. In our case, it opens the file and returns the file handle.
• The release function: a function that receives the acquired resource and returns an Effect that cleans it up. In our case, it takes the file handle and closes it.

Effect.acquireRelease does not run anything immediately. It returns a new Effect that says: “When you run me inside a scope, I will acquire the resource and register the release as a finalizer in that scope.” The return type is Effect<FileHandle, never, Scope.Scope>. Notice the Scope.Scope in the requirements position. This tells the type system that this effect needs a scope to run.

The most important point to understand is that the acquire and release are declared together in one place. You cannot forget to register the cleanup because it is part of the same declaration as the acquisition. There is no gap between “open the file” and “register the close” where you could accidentally forget the second step.

Effect.scoped

1
function readData() {
2
  return Effect.scoped(
3
    Effect.gen(function* () {
4
      const fileHandle = yield* managedFile;
5
      // ... use the file handle ...
6
    }),
7
  );
8
}

Effect.scoped is the function that provides the scope. It does four things:

• Creates a new scope.
• Runs the effect inside that scope. When yield* managedFile executes, the file is opened and its cleanup is registered as a finalizer in the scope.
• Closes the scope when the effect finishes. This happens regardless of whether the effect succeeded, failed, or was interrupted. Closing the scope runs all registered finalizers.
• Removes the Scope.Scope requirement from the return type. Without Effect.scoped, the Effect.gen block produces an Effect<string, UnsupportedFormatError, Scope.Scope> because yield* managedFile requires a scope. After wrapping it with Effect.scoped, the return type becomes Effect<string, UnsupportedFormatError, never>. The Scope.Scope is gone because Effect.scoped already provided it.

This is why there is no Scope.close call anywhere in the function. Effect.scoped handles it for you on every possible exit path.

Walking Through the readData Function

Let’s trace through what happens when readData is called:

1. Effect.scoped creates a new scope.
2. yield* managedFile runs the acquire effect. The file is opened. The release function is registered as a finalizer in the scope. The file handle is returned.
3. We read the file content.
4. The content contains "important", so we hit Effect.fail.
5. The generator short-circuits. Effect does not continue to the return content line.
6. Effect.scoped sees that the effect has completed (with a failure). It closes the scope.
7. The scope runs all registered finalizers in reverse order. Our release function runs: the file handle is closed and handlesClosed is incremented.
8. The failure propagates out of Effect.scoped.

If the content did not contain "important", step 4 would not fail. The function would return the content. Effect.scoped would still close the scope (step 6), still run the finalizer (step 7), and the file handle would still be closed. The cleanup happens no matter what.

Run the file. You will see the following output in the terminal:

1
Call 1: error caught and "handled"
2
  Handles opened: 1  |  Handles closed: 1  |  Handles leaked: 0
3

4
Call 2: error caught and "handled"
5
  Handles opened: 2  |  Handles closed: 2  |  Handles leaked: 0
6

7
Call 3: error caught and "handled"
8
  Handles opened: 3  |  Handles closed: 3  |  Handles leaked: 0
9

10
Call 4: error caught and "handled"
11
  Handles opened: 4  |  Handles closed: 4  |  Handles leaked: 0
12

13
Call 5: error caught and "handled"
14
  Handles opened: 5  |  Handles closed: 5  |  Handles leaked: 0

Zero leaked handles. Same result, but with far less code and no manual scope management.

What About Multiple Resources?

Remember the nesting problem from Chapter 2? With acquireRelease, multiple resources compose flatly. If we had an input file and an output file, the code would look like this:

1
const managedInputFile = Effect.acquireRelease(
2
  Effect.promise(async () => await open(inputPath, "r")),
3
  (handle) => Effect.promise(async () => await handle.close()),
4
);
5

6
const managedOutputFile = Effect.acquireRelease(
7
  Effect.promise(async () => await open(outputPath, "w")),
8
  (handle) => Effect.promise(async () => await handle.close()),
9
);
10

11
const program = Effect.scoped(
12
  Effect.gen(function* () {
13
    const input = yield* managedInputFile;
14
    const output = yield* managedOutputFile;
15

16
    const content = yield* Effect.promise(() => input.readFile("utf-8"));
17
    const processed = content.toUpperCase();
18
    yield* Effect.promise(() => output.writeFile(processed, "utf-8"));
19
  }),
20
);

No nesting. Both resources are acquired sequentially with yield*, and both are cleaned up when the scope closes. The cleanup happens in reverse order automatically: the output file is closed first (opened last), then the input file is closed (opened first). This is the correct release order, and you did not have to think about it. Effect handles it for you.

The manual Scope APIs (Scope.make, Scope.addFinalizer, Scope.close) are still available when you need fine-grained control over resource lifetimes. But for the vast majority of use cases, Effect.acquireRelease and Effect.scoped are all you need.