Scope

The Scope data type is a core construct in Effect for managing resources in a safe and composable way.

A scope represents the lifetime of one or more resources. When the scope is closed, all the resources within it are released, ensuring that no resources are leaked. Scopes also allow the addition of finalizers, which define how to release resources.

With the Scope data type, you can:

Add finalizers: A finalizer specifies the cleanup logic for a resource.
Close the scope: When the scope is closed, all resources are released, and the finalizers are executed.

Example (Managing a Scope)

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

3
const program =
4
  // create a new scope
5
  Scope.make().pipe(
6
    // add finalizer 1
7
    Effect.tap((scope) => Scope.addFinalizer(scope, Console.log("finalizer 1"))),
8
    // add finalizer 2
9
    Effect.tap((scope) => Scope.addFinalizer(scope, Console.log("finalizer 2"))),
10
    // close the scope
11
    Effect.andThen((scope) => Scope.close(scope, Exit.succeed("scope closed successfully"))),
12
  )
13

14
Effect.runPromise(program)
15
/*
16
Output:
17
finalizer 2 <-- finalizers are closed in reverse order
18
finalizer 1
19
*/

In the above example, finalizers are added to the scope, and when the scope is closed, the finalizers are executed in the reverse order.

This reverse order is important because it ensures that resources are released in the correct sequence.

For instance, if you acquire a network connection and then access a file on a remote server, the file must be closed before the network connection to avoid errors.

addFinalizer

The Effect.addFinalizer function is a high-level API that allows you to add finalizers to the scope of an effect. A finalizer is a piece of code that is guaranteed to run when the associated scope is closed. The behavior of the finalizer can vary based on the Exit value, which represents how the scope was closed—whether successfully or with an error.

Example (Adding a Finalizer on Success)

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

3
//      ┌─── Effect<string, never, Scope>
4
//      ▼
5
const program = Effect.gen(function* () {
6
  yield* Effect.addFinalizer((exit) => Console.log(`Finalizer executed. Exit status: ${exit._tag}`))
7
  return "some result"
8
})
9

10
// Wrapping the effect in a scope
11
//
12
//      ┌─── Effect<string, never, never>
13
//      ▼
14
const runnable = Effect.scoped(program)
15

16
Effect.runPromiseExit(runnable).then(console.log)
17
/*
18
Output:
19
Finalizer executed. Exit status: Success
20
{ _id: 'Exit', _tag: 'Success', value: 'some result' }
21
*/

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

3
//      ┌─── Effect<string, never, Scope>
4
//      ▼
5
const program = Effect.addFinalizer((exit) =>
6
  Console.log(`Finalizer executed. Exit status: ${exit._tag}`),
7
).pipe(Effect.andThen(Effect.succeed("some result")))
8

9
// Wrapping the effect in a scope
10
//
11
//      ┌─── Effect<string, never, never>
12
//      ▼
13
const runnable = Effect.scoped(program)
14

15
Effect.runPromiseExit(runnable).then(console.log)
16
/*
17
Output:
18
Finalizer executed. Exit status: Success
19
{ _id: 'Exit', _tag: 'Success', value: 'some result' }
20
*/

In this example, we use Effect.addFinalizer to add a finalizer that logs the exit state after the scope is closed. The finalizer will execute when the effect finishes, and it will log whether the effect completed successfully or failed.

The type signature:

const program: Effect<string, never, Scope>

shows that the workflow requires a Scope to run. You can provide this Scope using the Effect.scoped function, which creates a new scope, runs the effect within it, and ensures the finalizers are executed when the scope is closed.

Example (Adding a Finalizer on Failure)

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

3
//      ┌─── Effect<never, string, Scope>
4
//      ▼
5
const program = Effect.gen(function* () {
6
  yield* Effect.addFinalizer((exit) => Console.log(`Finalizer executed. Exit status: ${exit._tag}`))
7
  return yield* Effect.fail("Uh oh!")
8
})
9

10
// Wrapping the effect in a scope
11
//
12
//      ┌─── Effect<never, string, never>
13
//      ▼
14
const runnable = Effect.scoped(program)
15

16
Effect.runPromiseExit(runnable).then(console.log)
17
/*
18
Output:
19
Finalizer executed. Exit status: Failure
20
{
21
  _id: 'Exit',
22
  _tag: 'Failure',
23
  cause: { _id: 'Cause', _tag: 'Fail', failure: 'Uh oh!' }
24
}
25
*/

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

3
//      ┌─── Effect<never, string, Scope>
4
//      ▼
5
const program = Effect.addFinalizer((exit) =>
6
  Console.log(`Finalizer executed. Exit status: ${exit._tag}`),
7
).pipe(Effect.andThen(Effect.fail("Uh oh!")))
8

9
// Wrapping the effect in a scope
10
//
11
//      ┌─── Effect<never, string, never>
12
//      ▼
13
const runnable = Effect.scoped(program)
14

15
Effect.runPromiseExit(runnable).then(console.log)
16
/*
17
Output:
18
Finalizer executed. Exit status: Failure
19
{
20
  _id: 'Exit',
21
  _tag: 'Failure',
22
  cause: { _id: 'Cause', _tag: 'Fail', failure: 'Uh oh!' }
23
}
24
*/

In this case, the finalizer is executed even when the effect fails. The log output reflects that the finalizer runs after the failure, and it logs the failure details.

Example (Adding a Finalizer on Interruption)

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

3
//      ┌─── Effect<never, never, Scope>
4
//      ▼
5
const program = Effect.gen(function* () {
6
  yield* Effect.addFinalizer((exit) => Console.log(`Finalizer executed. Exit status: ${exit._tag}`))
7
  return yield* Effect.interrupt
8
})
9

10
// Wrapping the effect in a scope
11
//
12
//      ┌─── Effect<never, never, never>
13
//      ▼
14
const runnable = Effect.scoped(program)
15

16
Effect.runPromiseExit(runnable).then(console.log)
17
/*
18
Output:
19
Finalizer executed. Exit status: Failure
20
{
21
  _id: 'Exit',
22
  _tag: 'Failure',
23
  cause: {
24
    _id: 'Cause',
25
    _tag: 'Interrupt',
26
    fiberId: {
27
      _id: 'FiberId',
28
      _tag: 'Runtime',
29
      id: 0,
30
      startTimeMillis: ...
31
    }
32
  }
33
}
34
*/

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

3
//      ┌─── Effect<never, never, Scope>
4
//      ▼
5
const program = Effect.addFinalizer((exit) =>
6
  Console.log(`Finalizer executed. Exit status: ${exit._tag}`),
7
).pipe(Effect.andThen(Effect.interrupt))
8

9
// Wrapping the effect in a scope
10
//
11
//      ┌─── Effect<never, never, never>
12
//      ▼
13
const runnable = Effect.scoped(program)
14

15
Effect.runPromiseExit(runnable).then(console.log)
16
/*
17
Output:
18
Finalizer executed. Exit status: Failure
19
{
20
  _id: 'Exit',
21
  _tag: 'Failure',
22
  cause: {
23
    _id: 'Cause',
24
    _tag: 'Interrupt',
25
    fiberId: {
26
      _id: 'FiberId',
27
      _tag: 'Runtime',
28
      id: 0,
29
      startTimeMillis: ...
30
    }
31
  }
32
}
33
*/

This example shows how a finalizer behaves when the effect is interrupted. The finalizer runs after the interruption, and the exit status reflects that the effect was stopped mid-execution.

Manually Create and Close Scopes

When you’re working with multiple scoped resources within a single operation, it’s important to understand how their scopes interact. By default, these scopes are merged into one, but you can have more fine-grained control over when each scope is closed by manually creating and closing them.

Let’s start by looking at how scopes are merged by default:

Example (Merging Scopes)

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

3
const task1 = Effect.gen(function* () {
4
  console.log("task 1")
5
  yield* Effect.addFinalizer(() => Console.log("finalizer after task 1"))
6
})
7

8
const task2 = Effect.gen(function* () {
9
  console.log("task 2")
10
  yield* Effect.addFinalizer(() => Console.log("finalizer after task 2"))
11
})
12

13
const program = Effect.gen(function* () {
14
  // The scopes of both tasks are merged into one
15
  yield* task1
16
  yield* task2
17
})
18

19
Effect.runPromise(Effect.scoped(program))
20
/*
21
Output:
22
task 1
23
task 2
24
finalizer after task 2
25
finalizer after task 1
26
*/

In this case, the scopes of task1 and task2 are merged into a single scope, and when the program is run, it outputs the tasks and their finalizers in a specific order.

If you want more control over when each scope is closed, you can manually create and close them:

Example (Manually Creating and Closing Scopes)

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

3
const task1 = Effect.gen(function* () {
4
  console.log("task 1")
5
  yield* Effect.addFinalizer(() => Console.log("finalizer after task 1"))
6
})
7

8
const task2 = Effect.gen(function* () {
9
  console.log("task 2")
10
  yield* Effect.addFinalizer(() => Console.log("finalizer after task 2"))
11
})
12

13
const program = Effect.gen(function* () {
14
  const scope1 = yield* Scope.make()
15
  const scope2 = yield* Scope.make()
16

17
  // Extend the scope of task1 into scope1
18
  yield* task1.pipe(Scope.extend(scope1))
19

20
  // Extend the scope of task2 into scope2
21
  yield* task2.pipe(Scope.extend(scope2))
22

23
  // Manually close scope1 and scope2
24
  yield* Scope.close(scope1, Exit.void)
25
  yield* Console.log("doing something else")
26
  yield* Scope.close(scope2, Exit.void)
27
})
28

29
Effect.runPromise(program)
30
/*
31
Output:
32
task 1
33
task 2
34
finalizer after task 1
35
doing something else
36
finalizer after task 2
37
*/

In this example, we create two separate scopes, scope1 and scope2, and extend the scope of each task into its respective scope. When you run the program, it outputs the tasks and their finalizers in a different order.

You might wonder what happens when a scope is closed, but a task within that scope hasn’t completed yet. The key point to note is that the scope closing doesn’t force the task to be interrupted.

Example (Closing a Scope with Pending Tasks)

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

3
const task = Effect.gen(function* () {
4
  yield* Effect.sleep("1 second")
5
  console.log("Executed")
6
  yield* Effect.addFinalizer(() => Console.log("Task Finalizer"))
7
})
8

9
const program = Effect.gen(function* () {
10
  const scope = yield* Scope.make()
11

12
  // Close the scope immediately
13
  yield* Scope.close(scope, Exit.void)
14
  console.log("Scope closed")
15

16
  // This task will be executed even if the scope is closed
17
  yield* task.pipe(Scope.extend(scope))
18
})
19

20
Effect.runPromise(program)
21
/*
22
Output:
23
Scope closed
24
Executed <-- after 1 second
25
Task Finalizer
26
*/

Defining Resources

acquireRelease

The Effect.acquireRelease(acquire, release) function allows you to define resources that are acquired and safely released when they are no longer needed. This is useful for managing resources such as file handles, database connections, or network sockets.

To use Effect.acquireRelease, you need to define two actions:

Acquiring the Resource: An effect describing the acquisition of the resource, e.g., opening a file or establishing a database connection.
Releasing the Resource: The clean-up effect that ensures the resource is properly released, e.g., closing the file or the connection.

The acquisition process is uninterruptible to ensure that partial resource acquisition doesn’t leave your system in an inconsistent state.

The Effect.acquireRelease function guarantees that once a resource is successfully acquired, its release step is always executed when the Scope is closed.

Example (Defining a Simple Resource)

1
import { Effect } 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
// Create the resource management workflow
34
//
35
//      ┌─── Effect<MyResource, Error, Scope>
36
//      ▼
37
const resource = Effect.acquireRelease(acquire, release)

In the code above, the Effect.acquireRelease function creates a resource workflow that requires a Scope:

const resource: Effect<MyResource, Error, Scope>

This means that the workflow needs a Scope to run, and the resource will automatically be released when the scope is closed.

You can now use the resource by chaining operations using Effect.andThen or similar functions.

We can continue working with the resource for as long as we want by using Effect.andThen or other Effect operators. For example, here’s how we can read the contents:

Example (Using the Resource)

1
import { Effect } from "effect"
2

32 collapsed lines
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
// Create the resource management workflow
34
const resource = Effect.acquireRelease(acquire, release)
35

36
//      ┌─── Effect<void, Error, Scope>
37
//      ▼
38
const program = Effect.gen(function* () {
39
  const res = yield* resource
40
  console.log(`content is ${res.contents}`)
41
})

To ensure proper resource management, the Scope should be closed when you’re done with the resource. The Effect.scoped function handles this for you by creating a Scope, running the effect, and then closing the Scope when the effect finishes.

Example (Providing the Scope with Effect.scoped)

1
import { Effect } from "effect"
2

32 collapsed lines
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
// Create the resource management workflow
34
const resource = Effect.acquireRelease(acquire, release)
35

36
//      ┌─── Effect<void, Error, never>
37
//      ▼
38
const program = Effect.scoped(
39
  Effect.gen(function* () {
40
    const res = yield* resource
41
    console.log(`content is ${res.contents}`)
42
  }),
43
)
44

45
// We now have a workflow that is ready to run
46
Effect.runPromise(program)
47
/*
48
Resource acquired
49
content is lorem ipsum
50
Resource released
51
*/

Example Pattern: Sequencing Operations

In certain scenarios, you might need to perform a sequence of chained operations where the success of each operation depends on the previous one. However, if any of the operations fail, you would want to reverse the effects of all previous successful operations. This pattern is valuable when you need to ensure that either all operations succeed, or none of them have any effect at all.

Let’s go through an example of implementing this pattern. Suppose we want to create a “Workspace” in our application, which involves creating an S3 bucket, an ElasticSearch index, and a Database entry that relies on the previous two.

To begin, we define the domain model for the required services:

S3
ElasticSearch
Database

1
import { Effect, Context, Data } from "effect"
2

3
class S3Error extends Data.TaggedError("S3Error")<{}> {}
4

5
interface Bucket {
6
  readonly name: string
7
}
8

9
class S3 extends Context.Tag("S3")<
10
  S3,
11
  {
12
    readonly createBucket: Effect.Effect<Bucket, S3Error>
13
    readonly deleteBucket: (bucket: Bucket) => Effect.Effect<void>
14
  }
15
>() {}
16

17
class ElasticSearchError extends Data.TaggedError("ElasticSearchError")<{}> {}
18

19
interface Index {
20
  readonly id: string
21
}
22

23
class ElasticSearch extends Context.Tag("ElasticSearch")<
24
  ElasticSearch,
25
  {
26
    readonly createIndex: Effect.Effect<Index, ElasticSearchError>
27
    readonly deleteIndex: (index: Index) => Effect.Effect<void>
28
  }
29
>() {}
30

31
class DatabaseError extends Data.TaggedError("DatabaseError")<{}> {}
32

33
interface Entry {
34
  readonly id: string
35
}
36

37
class Database extends Context.Tag("Database")<
38
  Database,
39
  {
40
    readonly createEntry: (bucket: Bucket, index: Index) => Effect.Effect<Entry, DatabaseError>
41
    readonly deleteEntry: (entry: Entry) => Effect.Effect<void>
42
  }
43
>() {}

Next, we define the three create actions and the overall transaction (make) for the workspace.

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

46 collapsed lines
3
class S3Error extends Data.TaggedError("S3Error")<{}> {}
4

5
interface Bucket {
6
  readonly name: string
7
}
8

9
class S3 extends Context.Tag("S3")<
10
  S3,
11
  {
12
    readonly createBucket: Effect.Effect<Bucket, S3Error>
13
    readonly deleteBucket: (bucket: Bucket) => Effect.Effect<void>
14
  }
15
>() {}
16

17
class ElasticSearchError extends Data.TaggedError("ElasticSearchError")<{}> {}
18

19
interface Index {
20
  readonly id: string
21
}
22

23
class ElasticSearch extends Context.Tag("ElasticSearch")<
24
  ElasticSearch,
25
  {
26
    readonly createIndex: Effect.Effect<Index, ElasticSearchError>
27
    readonly deleteIndex: (index: Index) => Effect.Effect<void>
28
  }
29
>() {}
30

31
class DatabaseError extends Data.TaggedError("DatabaseError")<{}> {}
32

33
interface Entry {
34
  readonly id: string
35
}
36

37
class Database extends Context.Tag("Database")<
38
  Database,
39
  {
40
    readonly createEntry: (bucket: Bucket, index: Index) => Effect.Effect<Entry, DatabaseError>
41
    readonly deleteEntry: (entry: Entry) => Effect.Effect<void>
42
  }
43
>() {}
44

45
// Create a bucket, and define the release function that deletes the
46
// bucket if the operation fails.
47
const createBucket = Effect.gen(function* () {
48
  const { createBucket, deleteBucket } = yield* S3
49
  return yield* Effect.acquireRelease(createBucket, (bucket, exit) =>
50
    // The release function for the Effect.acquireRelease operation is
51
    // responsible for handling the acquired resource (bucket) after the
52
    // main effect has completed. It is called regardless of whether the
53
    // main effect succeeded or failed. If the main effect failed,
54
    // Exit.isFailure(exit) will be true, and the function will perform
55
    // a rollback by calling deleteBucket(bucket). If the main effect
56
    // succeeded, Exit.isFailure(exit) will be false, and the function
57
    // will return Effect.void, representing a successful, but
58
    // do-nothing effect.
59
    Exit.isFailure(exit) ? deleteBucket(bucket) : Effect.void,
60
  )
61
})
62

63
// Create an index, and define the release function that deletes the
64
// index if the operation fails.
65
const createIndex = Effect.gen(function* () {
66
  const { createIndex, deleteIndex } = yield* ElasticSearch
67
  return yield* Effect.acquireRelease(createIndex, (index, exit) =>
68
    Exit.isFailure(exit) ? deleteIndex(index) : Effect.void,
69
  )
70
})
71

72
// Create an entry in the database, and define the release function that
73
// deletes the entry if the operation fails.
74
const createEntry = (bucket: Bucket, index: Index) =>
75
  Effect.gen(function* () {
76
    const { createEntry, deleteEntry } = yield* Database
77
    return yield* Effect.acquireRelease(createEntry(bucket, index), (entry, exit) =>
78
      Exit.isFailure(exit) ? deleteEntry(entry) : Effect.void,
79
    )
80
  })
81

82
const make = Effect.scoped(
83
  Effect.gen(function* () {
84
    const bucket = yield* createBucket
85
    const index = yield* createIndex
86
    return yield* createEntry(bucket, index)
87
  }),
88
)

We then create simple service implementations to test the behavior of our Workspace code. To achieve this, we will utilize layers to construct test These layers will be able to handle various scenarios, including errors, which we can control using the FailureCase type.

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

93 collapsed lines
3
class S3Error extends Data.TaggedError("S3Error")<{}> {}
4

5
interface Bucket {
6
  readonly name: string
7
}
8

9
class S3 extends Context.Tag("S3")<
10
  S3,
11
  {
12
    readonly createBucket: Effect.Effect<Bucket, S3Error>
13
    readonly deleteBucket: (bucket: Bucket) => Effect.Effect<void>
14
  }
15
>() {}
16

17
class ElasticSearchError extends Data.TaggedError("ElasticSearchError")<{}> {}
18

19
interface Index {
20
  readonly id: string
21
}
22

23
class ElasticSearch extends Context.Tag("ElasticSearch")<
24
  ElasticSearch,
25
  {
26
    readonly createIndex: Effect.Effect<Index, ElasticSearchError>
27
    readonly deleteIndex: (index: Index) => Effect.Effect<void>
28
  }
29
>() {}
30

31
class DatabaseError extends Data.TaggedError("DatabaseError")<{}> {}
32

33
interface Entry {
34
  readonly id: string
35
}
36

37
class Database extends Context.Tag("Database")<
38
  Database,
39
  {
40
    readonly createEntry: (bucket: Bucket, index: Index) => Effect.Effect<Entry, DatabaseError>
41
    readonly deleteEntry: (entry: Entry) => Effect.Effect<void>
42
  }
43
>() {}
44

45
// Create a bucket, and define the release function that deletes the
46
// bucket if the operation fails.
47
const createBucket = Effect.gen(function* () {
48
  const { createBucket, deleteBucket } = yield* S3
49
  return yield* Effect.acquireRelease(createBucket, (bucket, exit) =>
50
    // The release function for the Effect.acquireRelease operation is
51
    // responsible for handling the acquired resource (bucket) after the
52
    // main effect has completed. It is called regardless of whether the
53
    // main effect succeeded or failed. If the main effect failed,
54
    // Exit.isFailure(exit) will be true, and the function will perform
55
    // a rollback by calling deleteBucket(bucket). If the main effect
56
    // succeeded, Exit.isFailure(exit) will be false, and the function
57
    // will return Effect.void, representing a successful, but
58
    // do-nothing effect.
59
    Exit.isFailure(exit) ? deleteBucket(bucket) : Effect.void,
60
  )
61
})
62

63
// Create an index, and define the release function that deletes the
64
// index if the operation fails.
65
const createIndex = Effect.gen(function* () {
66
  const { createIndex, deleteIndex } = yield* ElasticSearch
67
  return yield* Effect.acquireRelease(createIndex, (index, exit) =>
68
    Exit.isFailure(exit) ? deleteIndex(index) : Effect.void,
69
  )
70
})
71

72
// Create an entry in the database, and define the release function that
73
// deletes the entry if the operation fails.
74
const createEntry = (bucket: Bucket, index: Index) =>
75
  Effect.gen(function* () {
76
    const { createEntry, deleteEntry } = yield* Database
77
    return yield* Effect.acquireRelease(createEntry(bucket, index), (entry, exit) =>
78
      Exit.isFailure(exit) ? deleteEntry(entry) : Effect.void,
79
    )
80
  })
81

82
const make = Effect.scoped(
83
  Effect.gen(function* () {
84
    const bucket = yield* createBucket
85
    const index = yield* createIndex
86
    return yield* createEntry(bucket, index)
87
  }),
88
)
89

90
// The `FailureCaseLiterals` type allows us to provide different error
91
// scenarios while testing our
92
//
93
// For example, by providing the value "S3", we can simulate an error
94
// scenario specific to the S3 service. This helps us ensure that our
95
// program handles errors correctly and behaves as expected in various
96
// situations.
97
//
98
// Similarly, we can provide other values like "ElasticSearch" or
99
// "Database" to simulate error scenarios for those  In cases
100
// where we want to test the absence of errors, we can provide
101
// `undefined`. By using this parameter, we can thoroughly test our
102
// services and verify their behavior under different error conditions.
103
type FailureCaseLiterals = "S3" | "ElasticSearch" | "Database" | undefined
104

105
class FailureCase extends Context.Tag("FailureCase")<FailureCase, FailureCaseLiterals>() {}
106

107
// Create a test layer for the S3 service
108

109
const S3Test = Layer.effect(
110
  S3,
111
  Effect.gen(function* () {
112
    const failureCase = yield* FailureCase
113
    return {
114
      createBucket: Effect.gen(function* () {
115
        console.log("[S3] creating bucket")
116
        if (failureCase === "S3") {
117
          return yield* Effect.fail(new S3Error())
118
        } else {
119
          return { name: "<bucket.name>" }
120
        }
121
      }),
122
      deleteBucket: (bucket) => Console.log(`[S3] delete bucket ${bucket.name}`),
123
    }
124
  }),
125
)
126

127
// Create a test layer for the ElasticSearch service
128

129
const ElasticSearchTest = Layer.effect(
130
  ElasticSearch,
131
  Effect.gen(function* () {
132
    const failureCase = yield* FailureCase
133
    return {
134
      createIndex: Effect.gen(function* () {
135
        console.log("[ElasticSearch] creating index")
136
        if (failureCase === "ElasticSearch") {
137
          return yield* Effect.fail(new ElasticSearchError())
138
        } else {
139
          return { id: "<index.id>" }
140
        }
141
      }),
142
      deleteIndex: (index) => Console.log(`[ElasticSearch] delete index ${index.id}`),
143
    }
144
  }),
145
)
146

147
// Create a test layer for the Database service
148

149
const DatabaseTest = Layer.effect(
150
  Database,
151
  Effect.gen(function* () {
152
    const failureCase = yield* FailureCase
153
    return {
154
      createEntry: (bucket, index) =>
155
        Effect.gen(function* () {
156
          console.log(
157
            "[Database] creating entry for bucket" + `${bucket.name} and index ${index.id}`,
158
          )
159
          if (failureCase === "Database") {
160
            return yield* Effect.fail(new DatabaseError())
161
          } else {
162
            return { id: "<entry.id>" }
163
          }
164
        }),
165
      deleteEntry: (entry) => Console.log(`[Database] delete entry ${entry.id}`),
166
    }
167
  }),
168
)
169

170
// Merge all the test layers for S3, ElasticSearch, and Database
171
// services into a single layer
172
const layer = Layer.mergeAll(S3Test, ElasticSearchTest, DatabaseTest)
173

174
// Create a runnable effect to test the Workspace code. The effect is
175
// provided with the test layer and a FailureCase service with undefined
176
// value (no failure case).
177
const runnable = make.pipe(Effect.provide(layer), Effect.provideService(FailureCase, undefined))
178

179
Effect.runPromise(Effect.either(runnable)).then(console.log)

Let’s examine the test results for the scenario where FailureCase is set to undefined (happy path):

[S3] creating bucket
[ElasticSearch] creating index
[Database] creating entry for bucket <bucket.name> and index <index.id>
{ _id: 'Either', _tag: 'Right', right: { id: '<entry.id>' } }

In this case, all operations succeed, and we see a successful result with right({ id: '<entry.id>' }).

Now, let’s simulate a failure in the Database:

const runnable = make.pipe(Effect.provide(layer), Effect.provideService(FailureCase, "Database"))

The console output will be:

[S3] creating bucket
[ElasticSearch] creating index
[Database] creating entry for bucket <bucket.name> and index <index.id>
[ElasticSearch] delete index <index.id>
[S3] delete bucket <bucket.name>
{ _id: 'Either', _tag: 'Left', left: { _tag: 'DatabaseError' } }

You can observe that once the Database error occurs, there is a complete rollback that deletes the ElasticSearch index first and then the associated S3 bucket. The result is a failure with left(new DatabaseError()).

Let’s now make the index creation fail instead:

const runnable = make.pipe(
  Effect.provide(layer),
  Effect.provideService(FailureCase, "ElasticSearch"),
)

In this case, the console output will be:

[S3] creating bucket
[ElasticSearch] creating index
[S3] delete bucket <bucket.name>
{ _id: 'Either', _tag: 'Left', left: { _tag: 'ElasticSearchError' } }

As expected, once the ElasticSearch index creation fails, there is a rollback that deletes the S3 bucket. The result is a failure with left(new ElasticSearchError()).