Resource Management with Effect Scope

In the previous chapter, we saw all the problems we run into when dealing with opening and closing resources using JavaScript’s try/finally. Now let’s rewrite the same file handle demo using Effect’s Scope and see what changes.

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
// Read the data inside data.txt and throw an error if the data contains the term "important"
27
function readData() {
28
  return Effect.gen(function* () {
29
    // Step 1: Create a scope
30
    const scope = yield* Scope.make();
31

32
    // Step 2: Acquire the resource
33
    const handle = yield* Effect.promise(async () => {
34
      const fileHandle = await open(filePath, "r");
35
      handlesOpened++;
36
      return fileHandle;
37
    });
38

39
    // Step 3: Register a finalizer on the scope
40
    yield* Scope.addFinalizer(
41
      scope,
42
      Effect.promise(async () => {
43
        await handle.close();
44
        handlesClosed++;
45
      }),
46
    );
47

48
    // Step 4: Use the resource
49
    const content = yield* Effect.promise(() => handle.readFile("utf-8"));
50

51
    if (content.includes("important")) {
52
      // Step 5a: Close the scope before failing
53
      yield* Scope.close(scope, Exit.fail("error"));
54
      return yield* Effect.fail(
55
        new UnsupportedFormatError("Failed to process: unsupported format"),
56
      );
57
    }
58

59
    // Step 5b: Close the scope on success
60
    yield* Scope.close(scope, Exit.void);
61
    return content;
62
  });
63
}
64

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

78
  // Delete the temporary directory
79
  await rm(tmpDir, { recursive: true, force: true });
80
}
81

82
await main();

Let’s walk through the readData function step by step.

Step 1: Create a Scope

1
const scope = yield * Scope.make();

Scope.make() returns an Effect<Scope.Closeable>. A Closeable scope is one that you can explicitly close later by calling Scope.close on it.

Note that at this point, the scope’s internal state is empty. No finalizers are registered.

Step 2: Acquire the Resource

1
const handle =
2
  yield *
3
  Effect.promise(async () => {
4
    const fileHandle = await open(filePath, "r");
5
    handlesOpened++;
6
    return fileHandle;
7
  });

Here, we open the file and increment our tracker.

Notice that the scope and the acquisition are completely separate at this point. The scope does not know about the file handle yet. They get connected in the next step.

Step 3: Register a Finalizer on the Scope

1
yield *
2
  Scope.addFinalizer(
3
    scope,
4
    Effect.promise(async () => {
5
      await handle.close();
6
      handlesClosed++;
7
    }),
8
  );

Scope.addFinalizer takes two arguments:

• The scope to register with: the one we created in Step 1.
• The finalizer itself: an Effect that describes the cleanup work. In our case, it closes the file handle and increments our tracker.

After this call, the scope now contains one entry: our file-closing effect.

The finalizer does not run now. It just sits inside the scope, waiting. It will only run when someone calls Scope.close on this scope.

Step 4: Use the Resource

1
const content = yield * Effect.promise(() => handle.readFile("utf-8"));

Standard usage. Read the file content through the handle. Nothing scope-related here.

Now comes the final step, and this is where it gets interesting. We have two exit paths, and we must close the scope on both of them.

On the error path, we close the scope with a failure exit before returning the error:

1
yield * Scope.close(scope, Exit.fail("error"));
2
return (
3
  yield *
4
  Effect.fail(
5
    new UnsupportedFormatError("Failed to process: unsupported format"),
6
  )
7
);

On the success path, we close the scope with a success exit before returning the content:

1
yield * Scope.close(scope, Exit.void);
2
return content;

Scope.close takes two arguments:

• The scope to close: the one we created in Step 1.
• An Exit value describing how things ended. We pass Exit.fail("error") on the error path and Exit.void on the success path.

When called, the scope runs every registered finalizer in reverse order of registration (last registered, first run). In our case there is only one finalizer, so order does not matter yet. Each finalizer receives the Exit value you passed, so it could branch on success vs failure if needed.

After closing, the scope is done.

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. Every file that was opened was also closed, even though every call hit the error path. The scope’s finalizer took care of it.

But look at how many places we had to remember to call Scope.close:

• Before the Effect.fail on the error path
• At the end on the success path

And this is a simple example with just one branching point. In real code you might have three, four, five different exit paths. Miss even one and you leak the resource. We have essentially recreated the same problem as the original try/finally version, just in Effect syntax.

Effect provides another approach, Effect.acquireRelease and Effect.scoped, to solve this issue. They take the three manual steps we performed:

• Create a scope
• Register a finalizer
• Close the scope on every exit path

…and bundle them into a single declaration where the acquire and release are defined together, and the scope is created and closed automatically. You never manually call Scope.close. The framework does it for you on every possible exit path: success, failure and even interruption.

In the next chapter, we will rewrite this demo using Effect.acquireRelease and Effect.scoped, and you will see how much simpler it gets.