Managing Layers

In the Managing Services page, you learned how to create effects which depend on some service to be provided in order to execute, as well as how to provide that service to an effect.

However, what if we have a service within our effect program that has dependencies on other services in order to be built? We want to avoid leaking these implementation details into the service interface.

To represent the “dependency graph” of our program and manage these dependencies more effectively, we can utilize a powerful abstraction called “Layer”.

Layers act as constructors for creating services, allowing us to manage dependencies during construction rather than at the service level. This approach helps to keep our service interfaces clean and focused.

Let’s review some key concepts before diving into the details:

Concept	Description
service	A reusable component providing specific functionality, used across different parts of an application.
tag	A unique identifier representing a service, allowing Effect to locate and use it.
context	A collection storing services, functioning like a map with tags as keys and services as values.
layer	An abstraction for constructing services, managing dependencies during construction rather than at the service level.

Designing the Dependency Graph

Let’s imagine that we are building a web application. We could imagine that the dependency graph for an application where we need to manage configuration, logging, and database access might look something like this:

The Config service provides application configuration.
The Logger service depends on the Config service.
The Database service depends on both the Config and Logger services.

Our goal is to build the Database service along with its direct and indirect dependencies. This means we need to ensure that the Config service is available for both Logger and Database, and then provide these dependencies to the Database service.

Avoiding Requirement Leakage

When constructing the Database service, it’s important to avoid exposing the dependencies on Config and Logger within the Database interface.

You might be tempted to define the Database service as follows:

Example (Leaking Dependencies in the Service Interface)

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

3
// Declaring a tag for the Config service
4
class Config extends Context.Tag("Config")<Config, {}>() {}
5

6
// Declaring a tag for the Logger service
7
class Logger extends Context.Tag("Logger")<Logger, {}>() {}
8

9
// Declaring a tag for the Database service
10
class Database extends Context.Tag("Database")<
11
  Database,
12
  {
13
    // ❌ Avoid exposing Config and Logger as a requirement
14
    readonly query: (sql: string) => Effect.Effect<unknown, never, Config | Logger>
15
  }
16
>() {}

Here, the query function of the Database service requires both Config and Logger. This design leaks implementation details, making the Database service aware of its dependencies, which complicates testing and makes it difficult to mock.

Service functions should avoid requiring dependencies directly. In practice, service operations should have the Requirements parameter set to never:

                         ┌─── No dependencies required
                         ▼
Effect<Success, Error, never>

To demonstrate the problem, let’s create a test instance of the Database service:

Example (Creating a Test Instance with Leaked Dependencies)

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

15 collapsed lines
3
// Declaring a tag for the Config service
4
class Config extends Context.Tag("Config")<Config, {}>() {}
5

6
// Declaring a tag for the Logger service
7
class Logger extends Context.Tag("Logger")<Logger, {}>() {}
8

9
// Declaring a tag for the Database service
10
class Database extends Context.Tag("Database")<
11
  Database,
12
  {
13
    readonly query: (sql: string) => Effect.Effect<unknown, never, Config | Logger>
14
  }
15
>() {}
16

17
// Declaring a test instance of the Database service
18
const DatabaseTest = Database.of({
19
  // Simulating a simple response
20
  query: (sql: string) => Effect.succeed([]),
21
})
22

23
import * as assert from "node:assert"
24

25
// A test that uses the Database service
26
const test = Effect.gen(function* () {
27
  const database = yield* Database
28
  const result = yield* database.query("SELECT * FROM users")
29
  assert.deepStrictEqual(result, [])
30
})
31

32
//      ┌─── Effect<unknown, never, Config | Logger>
33
//      ▼
34
const incompleteTestSetup = test.pipe(
35
  // Attempt to provide only the Database service without Config and Logger
36
  Effect.provideService(Database, DatabaseTest),
37
)

Because the Database service interface directly includes dependencies on Config and Logger, it forces any test setup to include these services, even if they’re irrelevant to the test. This adds unnecessary complexity and makes it difficult to write simple, isolated unit tests.

Instead of directly tying dependencies to the Database service interface, dependencies should be managed at the construction phase.

We can use layers to properly construct the Database service and manage its dependencies without leaking details into the interface.

Creating Layers

The Layer type is structured as follows:

        ┌─── The service to be created
        │                ┌─── The possible error
        │                │      ┌─── The required dependencies
        ▼                ▼      ▼
Layer<RequirementsOut, Error, RequirementsIn>

A Layer represents a blueprint for constructing a RequirementsOut (the service). It requires a RequirementsIn (dependencies) as input and may result in an error of type Error during the construction process.

Parameter	Description
`RequirementsOut`	The service or resource to be created.
`Error`	The type of error that might occur during the construction of the service.
`RequirementsIn`	The dependencies required to construct the service.

By using layers, you can better organize your services, ensuring that their dependencies are clearly defined and separated from their implementation details.

For simplicity, let’s assume that we won’t encounter any errors during the value construction (meaning Error = never).

Now, let’s determine how many layers we need to implement our dependency graph:

Layer	Dependencies	Type
`ConfigLive`	The `Config` service does not depend on any other services	`Layer<Config>`
`LoggerLive`	The `Logger` service depends on the `Config` service	`Layer<Logger, never, Config>`
`DatabaseLive`	The `Database` service depends on `Config` and `Logger`	`Layer<Database, never, Config \| Logger>`

When a service has multiple dependencies, they are represented as a union type. In our case, the Database service depends on both the Config and Logger services. Therefore, the type for the DatabaseLive layer will be:

Layer<Database, never, Config | Logger>

Config

The Config service does not depend on any other services, so ConfigLive will be the simplest layer to implement. Just like in the Managing Services page, we must create a tag for the service. And because the service has no dependencies, we can create the layer directly using the Layer.succeed constructor:

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

3
// Declaring a tag for the Config service
4
class Config extends Context.Tag("Config")<
5
  Config,
6
  {
7
    readonly getConfig: Effect.Effect<{
8
      readonly logLevel: string
9
      readonly connection: string
10
    }>
11
  }
12
>() {}
13

14
// Layer<Config, never, never>
15
const ConfigLive = Layer.succeed(
16
  Config,
17
  Config.of({
18
    getConfig: Effect.succeed({
19
      logLevel: "INFO",
20
      connection: "mysql://username:password@hostname:port/database_name",
21
    }),
22
  }),
23
)

Looking at the type of ConfigLive we can observe:

RequirementsOut is Config, indicating that constructing the layer will produce a Config service
Error is never, indicating that layer construction cannot fail
RequirementsIn is never, indicating that the layer has no dependencies

Note that, to construct ConfigLive, we used the Config.of constructor. However, this is merely a helper to ensure correct type inference for the implementation. It’s possible to skip this helper and construct the implementation directly as a simple object:

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

3
// Declaring a tag for the Config service
9 collapsed lines
4
class Config extends Context.Tag("Config")<
5
  Config,
6
  {
7
    readonly getConfig: Effect.Effect<{
8
      readonly logLevel: string
9
      readonly connection: string
10
    }>
11
  }
12
>() {}
13

14
// Layer<Config, never, never>
15
const ConfigLive = Layer.succeed(Config, {
16
  getConfig: Effect.succeed({
17
    logLevel: "INFO",
18
    connection: "mysql://username:password@hostname:port/database_name",
19
  }),
20
})

Logger

Now we can move on to the implementation of the Logger service, which depends on the Config service to retrieve some configuration.

Just like we did in the Managing Services page, we can yield the Config tag to “extract” the service from the context.

Given that using the Config tag is an effectful operation, we use Layer.effect to create a layer from the resulting effect.

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

3
// Declaring a tag for the Config service
17 collapsed lines
4
class Config extends Context.Tag("Config")<
5
  Config,
6
  {
7
    readonly getConfig: Effect.Effect<{
8
      readonly logLevel: string
9
      readonly connection: string
10
    }>
11
  }
12
>() {}
13

14
// Layer<Config, never, never>
15
const ConfigLive = Layer.succeed(Config, {
16
  getConfig: Effect.succeed({
17
    logLevel: "INFO",
18
    connection: "mysql://username:password@hostname:port/database_name",
19
  }),
20
})
21

22
// Declaring a tag for the Logger service
23
class Logger extends Context.Tag("Logger")<
24
  Logger,
25
  { readonly log: (message: string) => Effect.Effect<void> }
26
>() {}
27

28
// Layer<Logger, never, Config>
29
const LoggerLive = Layer.effect(
30
  Logger,
31
  Effect.gen(function* () {
32
    const config = yield* Config
33
    return {
34
      log: (message) =>
35
        Effect.gen(function* () {
36
          const { logLevel } = yield* config.getConfig
37
          console.log(`[${logLevel}] ${message}`)
38
        }),
39
    }
40
  }),
41
)

Looking at the type of LoggerLive:

Layer<Logger, never, Config>

we can observe that:

RequirementsOut is Logger
Error is never, indicating that layer construction cannot fail
RequirementsIn is Config, indicating that the layer has a requirement

Database

Finally, we can use our Config and Logger services to implement the Database service.

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

3
// Declaring a tag for the Config service
17 collapsed lines
4
class Config extends Context.Tag("Config")<
5
  Config,
6
  {
7
    readonly getConfig: Effect.Effect<{
8
      readonly logLevel: string
9
      readonly connection: string
10
    }>
11
  }
12
>() {}
13

14
// Layer<Config, never, never>
15
const ConfigLive = Layer.succeed(Config, {
16
  getConfig: Effect.succeed({
17
    logLevel: "INFO",
18
    connection: "mysql://username:password@hostname:port/database_name",
19
  }),
20
})
21

22
// Declaring a tag for the Logger service
19 collapsed lines
23
class Logger extends Context.Tag("Logger")<
24
  Logger,
25
  { readonly log: (message: string) => Effect.Effect<void> }
26
>() {}
27

28
// Layer<Logger, never, Config>
29
const LoggerLive = Layer.effect(
30
  Logger,
31
  Effect.gen(function* () {
32
    const config = yield* Config
33
    return {
34
      log: (message) =>
35
        Effect.gen(function* () {
36
          const { logLevel } = yield* config.getConfig
37
          console.log(`[${logLevel}] ${message}`)
38
        }),
39
    }
40
  }),
41
)
42

43
// Declaring a tag for the Database service
44
class Database extends Context.Tag("Database")<
45
  Database,
46
  { readonly query: (sql: string) => Effect.Effect<unknown> }
47
>() {}
48

49
// Layer<Database, never, Config | Logger>
50
const DatabaseLive = Layer.effect(
51
  Database,
52
  Effect.gen(function* () {
53
    const config = yield* Config
54
    const logger = yield* Logger
55
    return {
56
      query: (sql: string) =>
57
        Effect.gen(function* () {
58
          yield* logger.log(`Executing query: ${sql}`)
59
          const { connection } = yield* config.getConfig
60
          return { result: `Results from ${connection}` }
61
        }),
62
    }
63
  }),
64
)

Looking at the type of DatabaseLive:

Layer<Database, never, Config | Logger>

we can observe that the RequirementsIn type is Config | Logger, i.e., the Database service requires both Config and Logger services.

Combining Layers

Layers can be combined in two primary ways: merging and composing.

Merging Layers

Layers can be combined through merging using the Layer.merge function:

1
import { Layer } from "effect"
2

3
declare const layer1: Layer.Layer<"Out1", never, "In1">
4
declare const layer2: Layer.Layer<"Out2", never, "In2">
5

6
// Layer<"Out1" | "Out2", never, "In1" | "In2">
7
const merging = Layer.merge(layer1, layer2)

When we merge two layers, the resulting layer:

requires all the services that both of them require ("In1" | "In2").
produces all services that both of them produce ("Out1" | "Out2").

For example, in our web application above, we can merge our ConfigLive and LoggerLive layers into a single AppConfigLive layer, which retains the requirements of both layers (never | Config = Config) and the outputs of both layers (Config | Logger):

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

3
// Declaring a tag for the Config service
17 collapsed lines
4
class Config extends Context.Tag("Config")<
5
  Config,
6
  {
7
    readonly getConfig: Effect.Effect<{
8
      readonly logLevel: string
9
      readonly connection: string
10
    }>
11
  }
12
>() {}
13

14
// Layer<Config, never, never>
15
const ConfigLive = Layer.succeed(Config, {
16
  getConfig: Effect.succeed({
17
    logLevel: "INFO",
18
    connection: "mysql://username:password@hostname:port/database_name",
19
  }),
20
})
21

22
// Declaring a tag for the Logger service
19 collapsed lines
23
class Logger extends Context.Tag("Logger")<
24
  Logger,
25
  { readonly log: (message: string) => Effect.Effect<void> }
26
>() {}
27

28
// Layer<Logger, never, Config>
29
const LoggerLive = Layer.effect(
30
  Logger,
31
  Effect.gen(function* () {
32
    const config = yield* Config
33
    return {
34
      log: (message) =>
35
        Effect.gen(function* () {
36
          const { logLevel } = yield* config.getConfig
37
          console.log(`[${logLevel}] ${message}`)
38
        }),
39
    }
40
  }),
41
)
42

43
// Layer<Config | Logger, never, Config>
44
const AppConfigLive = Layer.merge(ConfigLive, LoggerLive)

Composing Layers

Layers can be composed using the Layer.provide function:

1
import { Layer } from "effect"
2

3
declare const inner: Layer.Layer<"OutInner", never, "InInner">
4
declare const outer: Layer.Layer<"InInner", never, "InOuter">
5

6
// Layer<"OutInner", never, "InOuter">
7
const composition = Layer.provide(inner, outer)

Sequential composition of layers implies that the output of one layer is supplied as the input for the inner layer, resulting in a single layer with the requirements of the outer layer and the output of the inner.

Now we can compose the AppConfigLive layer with the DatabaseLive layer:

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

3
// Declaring a tag for the Config service
17 collapsed lines
4
class Config extends Context.Tag("Config")<
5
  Config,
6
  {
7
    readonly getConfig: Effect.Effect<{
8
      readonly logLevel: string
9
      readonly connection: string
10
    }>
11
  }
12
>() {}
13

14
// Layer<Config, never, never>
15
const ConfigLive = Layer.succeed(Config, {
16
  getConfig: Effect.succeed({
17
    logLevel: "INFO",
18
    connection: "mysql://username:password@hostname:port/database_name",
19
  }),
20
})
21

22
// Declaring a tag for the Logger service
19 collapsed lines
23
class Logger extends Context.Tag("Logger")<
24
  Logger,
25
  { readonly log: (message: string) => Effect.Effect<void> }
26
>() {}
27

28
// Layer<Logger, never, Config>
29
const LoggerLive = Layer.effect(
30
  Logger,
31
  Effect.gen(function* () {
32
    const config = yield* Config
33
    return {
34
      log: (message) =>
35
        Effect.gen(function* () {
36
          const { logLevel } = yield* config.getConfig
37
          console.log(`[${logLevel}] ${message}`)
38
        }),
39
    }
40
  }),
41
)
42

43
// Declaring a tag for the Database service
21 collapsed lines
44
class Database extends Context.Tag("Database")<
45
  Database,
46
  { readonly query: (sql: string) => Effect.Effect<unknown> }
47
>() {}
48

49
// Layer<Database, never, Config | Logger>
50
const DatabaseLive = Layer.effect(
51
  Database,
52
  Effect.gen(function* () {
53
    const config = yield* Config
54
    const logger = yield* Logger
55
    return {
56
      query: (sql: string) =>
57
        Effect.gen(function* () {
58
          yield* logger.log(`Executing query: ${sql}`)
59
          const { connection } = yield* config.getConfig
60
          return { result: `Results from ${connection}` }
61
        }),
62
    }
63
  }),
64
)
65

66
// Layer<Config | Logger, never, Config>
67
const AppConfigLive = Layer.merge(ConfigLive, LoggerLive)
68

69
// Layer<Database, never, never>
70
const MainLive = DatabaseLive.pipe(
71
  // provides the config and logger to the database
72
  Layer.provide(AppConfigLive),
73
  // provides the config to AppConfigLive
74
  Layer.provide(ConfigLive),
75
)

We obtained a MainLive layer that produces the Database service:

Layer<Database, never, never>

This layer is the fully resolved layer for our application.

Merging and Composing Layers

Let’s say we want our MainLive layer to return both the Config and Database services. We can achieve this with Layer.provideMerge:

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

3
// Declaring a tag for the Config service
16 collapsed lines
4
class Config extends Context.Tag("Config")<
5
  Config,
6
  {
7
    readonly getConfig: Effect.Effect<{
8
      readonly logLevel: string
9
      readonly connection: string
10
    }>
11
  }
12
>() {}
13

14
const ConfigLive = Layer.succeed(Config, {
15
  getConfig: Effect.succeed({
16
    logLevel: "INFO",
17
    connection: "mysql://username:password@hostname:port/database_name",
18
  }),
19
})
20

21
// Declaring a tag for the Logger service
18 collapsed lines
22
class Logger extends Context.Tag("Logger")<
23
  Logger,
24
  { readonly log: (message: string) => Effect.Effect<void> }
25
>() {}
26

27
const LoggerLive = Layer.effect(
28
  Logger,
29
  Effect.gen(function* () {
30
    const config = yield* Config
31
    return {
32
      log: (message) =>
33
        Effect.gen(function* () {
34
          const { logLevel } = yield* config.getConfig
35
          console.log(`[${logLevel}] ${message}`)
36
        }),
37
    }
38
  }),
39
)
40

41
// Declaring a tag for the Database service
20 collapsed lines
42
class Database extends Context.Tag("Database")<
43
  Database,
44
  { readonly query: (sql: string) => Effect.Effect<unknown> }
45
>() {}
46

47
const DatabaseLive = Layer.effect(
48
  Database,
49
  Effect.gen(function* () {
50
    const config = yield* Config
51
    const logger = yield* Logger
52
    return {
53
      query: (sql: string) =>
54
        Effect.gen(function* () {
55
          yield* logger.log(`Executing query: ${sql}`)
56
          const { connection } = yield* config.getConfig
57
          return { result: `Results from ${connection}` }
58
        }),
59
    }
60
  }),
61
)
62

63
// Layer<Config | Logger, never, Config>
64
const AppConfigLive = Layer.merge(ConfigLive, LoggerLive)
65

66
// Layer<Config | Database, never, never>
67
const MainLive = DatabaseLive.pipe(Layer.provide(AppConfigLive), Layer.provideMerge(ConfigLive))

Providing a Layer to an Effect

Now that we have assembled the fully resolved MainLive for our application, we can provide it to our program to satisfy the program’s requirements using Effect.provide:

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

63 collapsed lines
3
class Config extends Context.Tag("Config")<
4
  Config,
5
  {
6
    readonly getConfig: Effect.Effect<{
7
      readonly logLevel: string
8
      readonly connection: string
9
    }>
10
  }
11
>() {}
12

13
const ConfigLive = Layer.succeed(Config, {
14
  getConfig: Effect.succeed({
15
    logLevel: "INFO",
16
    connection: "mysql://username:password@hostname:port/database_name",
17
  }),
18
})
19

20
class Logger extends Context.Tag("Logger")<
21
  Logger,
22
  { readonly log: (message: string) => Effect.Effect<void> }
23
>() {}
24

25
const LoggerLive = Layer.effect(
26
  Logger,
27
  Effect.gen(function* () {
28
    const config = yield* Config
29
    return {
30
      log: (message) =>
31
        Effect.gen(function* () {
32
          const { logLevel } = yield* config.getConfig
33
          console.log(`[${logLevel}] ${message}`)
34
        }),
35
    }
36
  }),
37
)
38

39
class Database extends Context.Tag("Database")<
40
  Database,
41
  { readonly query: (sql: string) => Effect.Effect<unknown> }
42
>() {}
43

44
const DatabaseLive = Layer.effect(
45
  Database,
46
  Effect.gen(function* () {
47
    const config = yield* Config
48
    const logger = yield* Logger
49
    return {
50
      query: (sql: string) =>
51
        Effect.gen(function* () {
52
          yield* logger.log(`Executing query: ${sql}`)
53
          const { connection } = yield* config.getConfig
54
          return { result: `Results from ${connection}` }
55
        }),
56
    }
57
  }),
58
)
59

60
const AppConfigLive = Layer.merge(ConfigLive, LoggerLive)
61

62
const MainLive = DatabaseLive.pipe(Layer.provide(AppConfigLive), Layer.provide(ConfigLive))
63

64
//      ┌─── Effect<unknown, never, Database>
65
//      ▼
66
const program = Effect.gen(function* () {
67
  const database = yield* Database
68
  const result = yield* database.query("SELECT * FROM users")
69
  return result
70
})
71

72
//      ┌─── Effect<unknown, never, never>
73
//      ▼
74
const runnable = Effect.provide(program, MainLive)
75

76
Effect.runPromise(runnable).then(console.log)
77
/*
78
Output:
79
[INFO] Executing query: SELECT * FROM users
80
{
81
  result: 'Results from mysql://username:password@hostname:port/database_name'
82
}
83
*/

Note that the runnable requirements type is never, indicating that the program does not require any additional services to run.

Converting a Layer to an Effect

Sometimes your entire application might be a Layer, for example, an HTTP server. You can convert that layer to an effect with Layer.launch. It constructs the layer and keeps it alive until interrupted.

Example (Launching an HTTP Server Layer)

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

3
class HTTPServer extends Context.Tag("HTTPServer")<HTTPServer, void>() {}
4

5
// Simulating an HTTP server
6
const server = Layer.effect(
7
  HTTPServer,
8
  // Log a message to simulate a server starting
9
  Console.log("Listening on http://localhost:3000"),
10
)
11

12
// Converts the layer to an effect and runs it
13
Effect.runFork(Layer.launch(server))
14
/*
15
Output:
16
Listening on http://localhost:3000
17
...
18
*/

Tapping

The Layer.tap and Layer.tapError functions allow you to perform additional effects based on the success or failure of a layer. These operations do not modify the layer’s signature but are useful for logging or performing side effects during layer construction.

Layer.tap: Executes a specified effect when the layer is successfully acquired.
Layer.tapError: Executes a specified effect when the layer fails to acquire.

Example (Logging Success and Failure During Layer Acquisition)

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

3
class HTTPServer extends Context.Tag("HTTPServer")<HTTPServer, void>() {}
4

5
// Simulating an HTTP server
6
const server = Layer.effect(
7
  HTTPServer,
8
  Effect.gen(function* () {
9
    const host = yield* Config.string("HOST")
10
    console.log(`Listening on http://localhost:${host}`)
11
  }),
12
).pipe(
13
  // Log a message if the layer acquisition succeeds
14
  Layer.tap((ctx) => Console.log(`layer acquisition succeeded with:\n${ctx}`)),
15
  // Log a message if the layer acquisition fails
16
  Layer.tapError((err) => Console.log(`layer acquisition failed with:\n${err}`)),
17
)
18

19
Effect.runFork(Layer.launch(server))
20
/*
21
Output:
22
layer acquisition failed with:
23
(Missing data at HOST: "Expected HOST to exist in the process context")
24
*/

Error Handling

When constructing layers, it is important to handle potential errors. The Effect library provides tools like Layer.catchAll and Layer.orElse to manage errors and define fallback layers in case of failure.

catchAll

The Layer.catchAll function allows you to recover from errors during layer construction by specifying a fallback layer. This can be useful for handling specific error cases and ensuring the application can continue with an alternative setup.

Example (Recovering from Errors During Layer Construction)

1
import { Config, Context, Effect, Layer } from "effect"
2

3
class HTTPServer extends Context.Tag("HTTPServer")<HTTPServer, void>() {}
4

5
// Simulating an HTTP server
6
const server = Layer.effect(
7
  HTTPServer,
8
  Effect.gen(function* () {
9
    const host = yield* Config.string("HOST")
10
    console.log(`Listening on http://localhost:${host}`)
11
  }),
12
).pipe(
13
  // Recover from errors during layer construction
14
  Layer.catchAll((configError) =>
15
    Layer.effect(
16
      HTTPServer,
17
      Effect.gen(function* () {
18
        console.log(`Recovering from error:\n${configError}`)
19
        console.log(`Listening on http://localhost:3000`)
20
      }),
21
    ),
22
  ),
23
)
24

25
Effect.runFork(Layer.launch(server))
26
/*
27
Output:
28
Recovering from error:
29
(Missing data at HOST: "Expected HOST to exist in the process context")
30
Listening on http://localhost:3000
31
...
32
*/

orElse

The Layer.orElse function provides a simpler way to fall back to an alternative layer if the initial layer fails. Unlike Layer.catchAll, it does not receive the error as input. Use this when you only need to provide a default layer without reacting to specific errors.

Example (Fallback to an Alternative Layer)

1
import { Config, Context, Effect, Layer } from "effect"
2

3
class Database extends Context.Tag("Database")<Database, void>() {}
4

5
// Simulating a database connection
6
const postgresDatabaseLayer = Layer.effect(
7
  Database,
8
  Effect.gen(function* () {
9
    const databaseConnectionString = yield* Config.string("CONNECTION_STRING")
10
    console.log(`Connecting to database with: ${databaseConnectionString}`)
11
  }),
12
)
13

14
// Simulating an in-memory database connection
15
const inMemoryDatabaseLayer = Layer.effect(
16
  Database,
17
  Effect.gen(function* () {
18
    console.log(`Connecting to in-memory database`)
19
  }),
20
)
21

22
// Fallback to in-memory database if PostgreSQL connection fails
23
const database = postgresDatabaseLayer.pipe(Layer.orElse(() => inMemoryDatabaseLayer))
24

25
Effect.runFork(Layer.launch(database))
26
/*
27
Output:
28
Connecting to in-memory database
29
...
30
*/

Simplifying Service Definitions with Effect.Service

The Effect.Service API provides a way to define a service in a single step, including its tag and layer. It also allows specifying dependencies upfront, making service construction more straightforward.

Defining a Service with Dependencies

The following example defines a Cache service that depends on a file system.

Example (Defining a Cache Service)

1
import { FileSystem } from "@effect/platform"
2
import { NodeFileSystem } from "@effect/platform-node"
3
import { Effect } from "effect"
4

5
// Define a Cache service
6
class Cache extends Effect.Service<Cache>()("app/Cache", {
7
  // Define how to create the service
8
  effect: Effect.gen(function* () {
9
    const fs = yield* FileSystem.FileSystem
10
    const lookup = (key: string) => fs.readFileString(`cache/${key}`)
11
    return { lookup } as const
12
  }),
13
  // Specify dependencies
14
  dependencies: [NodeFileSystem.layer],
15
}) {}

Using the Generated Layers

The Effect.Service API automatically generates layers for the service.

Layer	Description
`Cache.Default`	Provides the `Cache` service with its dependencies already included.
`Cache.DefaultWithoutDependencies`	Provides the `Cache` service but requires dependencies to be provided separately.

1
import { FileSystem } from "@effect/platform"
2
import { NodeFileSystem } from "@effect/platform-node"
3
import { Effect } from "effect"
4

5
// Define a Cache service
8 collapsed lines
6
class Cache extends Effect.Service<Cache>()("app/Cache", {
7
  effect: Effect.gen(function* () {
8
    const fs = yield* FileSystem.FileSystem
9
    const lookup = (key: string) => fs.readFileString(`cache/${key}`)
10
    return { lookup } as const
11
  }),
12
  dependencies: [NodeFileSystem.layer],
13
}) {}
14

15
// Layer that includes all required dependencies
16
//
17
//      ┌─── Layer<Cache>
18
//      ▼
19
const layer = Cache.Default
20

21
// Layer without dependencies, requiring them to be provided externally
22
//
23
//      ┌─── Layer.Layer<Cache, never, FileSystem>
24
//      ▼
25
const layerNoDeps = Cache.DefaultWithoutDependencies

Accessing the Service

A service created with Effect.Service can be accessed like any other Effect service.

Example (Accessing the Cache Service)

1
import { FileSystem } from "@effect/platform"
2
import { NodeFileSystem } from "@effect/platform-node"
3
import { Effect, Console } from "effect"
4

5
// Define a Cache service
8 collapsed lines
6
class Cache extends Effect.Service<Cache>()("app/Cache", {
7
  effect: Effect.gen(function* () {
8
    const fs = yield* FileSystem.FileSystem
9
    const lookup = (key: string) => fs.readFileString(`cache/${key}`)
10
    return { lookup } as const
11
  }),
12
  dependencies: [NodeFileSystem.layer],
13
}) {}
14

15
// Accessing the Cache Service
16
const program = Effect.gen(function* () {
17
  const cache = yield* Cache
18
  const data = yield* cache.lookup("my-key")
19
  console.log(data)
20
}).pipe(Effect.catchAllCause((cause) => Console.log(cause)))
21

22
const runnable = program.pipe(Effect.provide(Cache.Default))
23

24
Effect.runFork(runnable)
25
/*
26
{
27
  _id: 'Cause',
28
  _tag: 'Fail',
29
  failure: {
30
    _tag: 'SystemError',
31
    reason: 'NotFound',
32
    module: 'FileSystem',
33
    method: 'readFile',
34
    pathOrDescriptor: 'cache/my-key',
35
    syscall: 'open',
36
    message: "ENOENT: no such file or directory, open 'cache/my-key'",
37
    [Symbol(@effect/platform/Error/PlatformErrorTypeId)]: Symbol(@effect/platform/Error/PlatformErrorTypeId)
38
  }
39
}
40
*/

Since this example uses Cache.Default, it interacts with the real file system. If the file does not exist, it results in an error.

Injecting Test Dependencies

To test the program without depending on the real file system, we can inject a test file system using the Cache.DefaultWithoutDependencies layer.

Example (Using a Test File System)

1
import { FileSystem } from "@effect/platform"
2
import { NodeFileSystem } from "@effect/platform-node"
3
import { Effect, Console } from "effect"
4

5
// Define a Cache service
8 collapsed lines
6
class Cache extends Effect.Service<Cache>()("app/Cache", {
7
  effect: Effect.gen(function* () {
8
    const fs = yield* FileSystem.FileSystem
9
    const lookup = (key: string) => fs.readFileString(`cache/${key}`)
10
    return { lookup } as const
11
  }),
12
  dependencies: [NodeFileSystem.layer],
13
}) {}
14

15
// Accessing the Cache Service
5 collapsed lines
16
const program = Effect.gen(function* () {
17
  const cache = yield* Cache
18
  const data = yield* cache.lookup("my-key")
19
  console.log(data)
20
}).pipe(Effect.catchAllCause((cause) => Console.log(cause)))
21

22
// Create a test file system that always returns a fixed value
23
const FileSystemTest = FileSystem.layerNoop({
24
  readFileString: () => Effect.succeed("File Content..."),
25
})
26

27
const runnable = program.pipe(
28
  Effect.provide(Cache.DefaultWithoutDependencies),
29
  // Provide the mock file system
30
  Effect.provide(FileSystemTest),
31
)
32

33
Effect.runFork(runnable)
34
// Output: File Content...

Mocking the Service Directly

Alternatively, you can mock the Cache service itself instead of replacing its dependencies.

Example (Mocking the Cache Service)

1
import { FileSystem } from "@effect/platform"
2
import { NodeFileSystem } from "@effect/platform-node"
3
import { Effect, Console } from "effect"
4

5
// Define a Cache service
8 collapsed lines
6
class Cache extends Effect.Service<Cache>()("app/Cache", {
7
  effect: Effect.gen(function* () {
8
    const fs = yield* FileSystem.FileSystem
9
    const lookup = (key: string) => fs.readFileString(`cache/${key}`)
10
    return { lookup } as const
11
  }),
12
  dependencies: [NodeFileSystem.layer],
13
}) {}
14

15
// Accessing the Cache Service
5 collapsed lines
16
const program = Effect.gen(function* () {
17
  const cache = yield* Cache
18
  const data = yield* cache.lookup("my-key")
19
  console.log(data)
20
}).pipe(Effect.catchAllCause((cause) => Console.log(cause)))
21

22
// Create a mock implementation of Cache
23
const cache = new Cache({
24
  lookup: () => Effect.succeed("Cache Content..."),
25
})
26

27
// Provide the mock Cache service
28
const runnable = program.pipe(Effect.provideService(Cache, cache))
29

30
Effect.runFork(runnable)
31
// Output: Cache Content...

Alternative Ways to Define a Service

The Effect.Service API supports multiple ways to define a service:

Method	Description
`succeed`	Provides a static implementation of the service.
`sync`	Defines a service using a synchronous constructor.
`effect`	Defines a service with an effectful constructor.
`scoped`	Creates a service with lifecycle management.

Example (Defining a Service with a Static Implementation)

This is the simplest way to define a service. It is useful when you want to provide a constant value for the service.

1
import { Effect } from "effect"
2

3
class MagicNumber extends Effect.Service<MagicNumber>()("MagicNumber", {
4
  succeed: { value: 42 },
5
}) {}
6

7
//      ┌─── Effect<void, never, MagicNumber>
8
//      ▼
9
const program = Effect.gen(function* () {
10
  const magicNumber = yield* MagicNumber
11
  console.log(`The magic number is ${magicNumber.value}`)
12
})
13

14
Effect.runPromise(program.pipe(Effect.provide(MagicNumber.Default)))
15
// The magic number is 42

Example (Defining a Service with a Synchronous Constructor)

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

3
class Sync extends Effect.Service<Sync>()("Sync", {
4
  sync: () => ({
5
    next: Random.nextInt,
6
  }),
7
}) {}
8

9
//      ┌─── Effect<void, never, Sync>
10
//      ▼
11
const program = Effect.gen(function* () {
12
  const sync = yield* Sync
13
  const n = yield* sync.next
14
  console.log(`The number is ${n}`)
15
})
16

17
Effect.runPromise(program.pipe(Effect.provide(Sync.Default)))
18
// Example Output: The number is 3858843290019673

Example (Managing a Service with Lifecycle Control)

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

3
class Scoped extends Effect.Service<Scoped>()("Scoped", {
4
  scoped: Effect.gen(function* () {
5
    // Acquire the resource and ensure it is properly released
6
    const resource = yield* Effect.acquireRelease(
7
      Console.log("Acquiring...").pipe(Effect.as("foo")),
8
      () => Console.log("Releasing..."),
9
    )
10
    // Register a finalizer to run when the effect is completed
11
    yield* Effect.addFinalizer(() => Console.log("Shutting down"))
12
    return { resource }
13
  }),
14
}) {}
15

16
//      ┌─── Effect<void, never, Scoped>
17
//      ▼
18
const program = Effect.gen(function* () {
19
  const resource = (yield* Scoped).resource
20
  console.log(`The resource is ${resource}`)
21
})
22

23
Effect.runPromise(
24
  program.pipe(
25
    Effect.provide(
26
      //       ┌─── Layer<Scoped, never, never>
27
      //       ▼
28
      Scoped.Default,
29
    ),
30
  ),
31
)
32
/*
33
Acquiring...
34
The resource is foo
35
Shutting down
36
Releasing...
37
*/

The Scoped.Default layer does not require Scope as a dependency, since Scoped itself manages its lifecycle.

Enabling Direct Method Access

By setting accessors: true, you can call service methods directly using the service tag instead of first extracting the service.

Example (Defining a Service with Direct Method Access)

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

3
class Sync extends Effect.Service<Sync>()("Sync", {
4
  sync: () => ({
5
    next: Random.nextInt,
6
  }),
7
  accessors: true, // Enables direct method access via the tag
8
}) {}
9

10
const program = Effect.gen(function* () {
11
  // const sync = yield* Sync
12
  // const n = yield* sync.next
13
  const n = yield* Sync.next // No need to extract the service first
14
  console.log(`The number is ${n}`)
15
})
16

17
Effect.runPromise(program.pipe(Effect.provide(Sync.Default)))
18
// Example Output: The number is 3858843290019673

Effect.Service vs Context.Tag

Both Effect.Service and Context.Tag are ways to model services in the Effect ecosystem. They serve similar purposes but target different use-cases.

Feature	Effect.Service	Context.Tag
Tag creation	Generated for you (the class name acts as the tag)	You declare the tag manually
Default implementation	Required - supplied inline (`effect`, `sync`, etc.)	Optional - can be supplied later
Ready-made layers (`.Default`, …)	Automatically generated	You build layers yourself
Best suited for	Application code with a clear runtime implementation	Library code or dynamically-scoped values
When no sensible default exists	Not ideal; you would still have to invent one	Preferred

Key points

Less boilerplate: Effect.Service is syntactic sugar over Context.Tag plus the accompanying layer and helpers.
Default required: A class that extends Effect.Service must declare one of the built-in constructors (effect, sync, succeed, or scoped). This baseline implementation becomes part of MyService.Default, so any code that imports the service can run without providing extra layers. That is handy for app-level services where a sensible runtime implementation exists (logging, HTTP clients, real databases, and so on). If your service is inherently contextual (for example, a per-request database handle) or you are writing a library that should not assume an implementation, prefer Context.Tag: you publish only the tag and let callers supply the layer that makes sense in their environment.
The class is the tag: When you create a class with extends Effect.Service, the class constructor itself acts as the tag. You can provide alternate implementations by supplying a value for that class when wiring layers:
```
1
const mock = new MyService({
2
  /* mocked methods */
3
})
4
program.pipe(Effect.provideService(MyService, mock))
```