Effect Layers

In Effect, a service is reusable code that other code depends on, typically a domain abstraction, an API, or an architectural layer.

Effect uses the type system to ensure all dependencies are satisfied before the program runs. This moves dependency management to compile-time, making missing dependencies impossible to miss.

There are two ways to define a service: with or without the Layer abstraction.

We’ll use a GameRepository service (encapsulating in-memory game state) as our example. First, we’ll build it without Layer and hit a wall when our service depends on another service. Then we’ll see how Layer solves this.

Defining a Service Without Layers

The Simple Case: No Dependencies

This is the interface for the GameRepository:

1
interface GameRepositoryInterface {
2
  readonly getAllGames: () => Effect.Effect<GameStorage[]>;
3
}

We define the service by tagging it and associating it with the interface. We also declare local state for storing games:

1
class GameRepository extends Context.Tag("GameRepository")<
2
  GameRepository,
3
  GameRepositoryInterface
4
>() {
5
  static readonly games = new Map<GameStorage["id"], GameStorage>();
6
}

Now we can use this service in our program:

1
const program = Effect.gen(function* () {
2
  const gameRepository = yield* GameRepository;
3
  const games = yield* gameRepository.getAllGames();
4

5
  for (const game of games) {
6
    yield* Effect.log(game.status);
7
  }
8
});

However, we cannot run this program. The type system tells us this. The Requirements channel shows GameRepository is unsatisfied.

1
//       ┌─ Effect<void, never, GameRepository>
2
//       ▼
3
const program = Effect.gen(function* () {
4
  const gameRepository = yield* GameRepository;
5
  const games = yield* gameRepository.getAllGames();
6

7
  for (const game of games) {
8
    yield* Effect.log(game.status);
9
  }
10
});

Attempting to run it fails:

1
//       ┌─ Argument of type 'Effect<void, never, GameRepository>'
2
//       |  is not assignable to parameter of type 'Effect<void,
3
//       |  never, never>'
4
//       ▼
5
Effect.runFork(program);

The reason? Well, we’ve defined an interface but haven’t provided an implementation. Here is an implementation:

1
export const GameRepositoryImplementation = {
2
  getAllGames: () => {
3
    return Effect.succeed(Array.from(GameRepository.games.values()));
4
  },
5
};

Which we can then supply to the program with Effect.provideService. The Requirements channel is now empty:

1
//       ┌─ Effect<void, never, never>
2
//       ▼
3
const runnable = program.pipe(Effect.provideService(GameRepository, GameRepositoryImplementation));
4

5
Effect.runFork(runnable);

This works. But what happens when GameRepository depends on another service?

The Problem: Service-to-Service Dependencies

Suppose we have a Config service:

1
class Config extends Context.Tag("Config")<Config, {}>() {}

That getAllGames depends on:

1
export const GameRepositoryImplementation = {
2
  getAllGames: () =>
3
    Effect.gen(function* () {
4
      const config = yield* Config; // Used for some purpose or another ...
5

6
      return Array.from(GameRepository.games.values());
7
    }),
8
};

And because we have not yet provided an implementation for Config, our program will not run.

1
const runnable = program.pipe(
2
  //                                                    ┌─ Type 'Config' is not
3
  //                                                    |  assignable to type 'never'
4
  //                                                    ▼
5
  Effect.provideService(GameRepository, GameRepositoryImplementation),
6
);

We fix this by providing an implementation. For simplicities sake, it is an empty object.

1
const runnable = program.pipe(
2
  Effect.provideService(GameRepository, GameRepositoryImplementation),
3
  Effect.provideService(Config, {}),
4
);

However, you may have noticed, there is drift between our GameRepository interface and implementation definitions where the implementation now has a dependency on Config. So, we update our GameRepository interface.

1
export interface GameRepositoryInterface {
2
  readonly getAllGames: () => Effect.Effect<GameStorage[], never, Config>;
3
}

But this is bad. We have leaked details about the service dependency into our interface and made aware our service aware of its dependencies ¹. This is problematic:

• Coupling: Consumers of GameRepository now depend on Config, even if they don’t use it directly.

• Rigidity: If we later change the implementation to not use Config, the interface still demands it.

• Interface drift: The interface and implementation can diverge. We might declare a dependency we never use.

This also violates something of a soft principle of Effect when it comes to services. That “service functions should avoid requiring dependencies directly” ². What this means is that at the point we are providing a service to our program, the type signature of that service should have an empty Requirements channel. Ideally, we should not be fulfilling dependency obligations at the level (the context) where a dependency is being consumed.

There is a better way. We can provide dependencies at the point of implementation construction, instead of against the interface. Enter constructor effects.

Constructor Effects

The first step is to not express Config as a dependency on the interface.

1
readonly getAllGames: () => Effect.Effect<GameStorage[], never>;

We then create an Effect that constructs or builds the implementation, getAllGames, capturing the dependencies through a closure.

1
//                     ┌─ Effect.Effect<GameRepositoryInterface, never, Config>
2
//                     ▼
3
const makeGameRepositoryImplementationWithConfigDep = Effect.gen(function* () {
4
  const config = yield* Config;
5
  return GameRepository.of({
6
    getAllGames: () =>
7
      Effect.gen(function* () {
8
        // yield* config.? // Do something with config
9
        return Array.from(GameRepository.games.values());
10
      }),
11
  });
12
});

We then provide the GameRepository service and its implementation with the Config dependency to the program using .provideServiceEffect.

1
//        ┌─ Effect.Effect<void, never, Config>
2
//        ▼
3
const nonrunnable = program.pipe(
4
  Effect.provideServiceEffect(GameRepository, makeGameRepositoryImplementationWithConfigDep),
5
);
6

7
//        ┌─ Effect.Effect<void, never, never>
8
//        ▼
9
const runnable = nonrunnable.pipe(Effect.provideService(Config, {}));

Config is a requirement to build a certain implementation of GameRepository, not a requirement to use it. The interface stays clean.

As a side note, I do find this a little complex as we sort of invert the dependency graph as the last dependency we provided, what we pipe to nonrunnable, is the one that is used at the lowest level.

Again, there is a better way. Enter Layers.

Defining a Service With Layers

Layers are an abstraction that leverage the act of building the service and handling dependencies at the construction level rather than the service level. They are constructors for services ³. They achieve the same ends as we did with our makeGameRepositoryImplementationWithConfigDep implementation.

Layers separate implementation details from the service interface, handling dependency graphs through compositional APIs:

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

We can use Layers to define services that are without dependencies, like how we had before introducing Config.

1
const GameRepositoryLive = Layer.succeed(GameRepository, {
2
  getAllGames: () => Effect.succeed(Array.from(GameRepository.games.values())),
3
});

Our program consumes it in the same way:

1
const runnable = Effect.provide(program, GameRepositoryLive);

But they really shine once we are presented with the scenario of having a dependency between our services. Under these conditions Layer.succeed will not work.

1
//           ┌─ Type 'Config' is not assignable to type 'never'
2
//           ▼
3
const GameRepositoryLive = Layer.succeed(GameRepository, {
4
  getAllGames: () =>
5
    Effect.gen(function* () {
6
      const config = yield* Config;
7
      // yield* config.? // Do something with config
8
      return Array.from(GameRepository.games.values());
9
    }),
10
});

This is because there is a type mismatch between what we having defined on our GameRepository interface, where we haven’t changed the signature to include Config, and our implementation where it is very apparently depended upon.

1
// 1. Interface signature
2
Effect<GameStorage[], never, never>
3

4
// 2. Implementation signature
5
Effect<GameStorage[], never, Config>

Use Layer.effect instead. It accepts an Effect that constructs the service ⁴.

1
//           ┌─ Layer.Layer<GameRepository, never, Config>
2
//           ▼
3
const GameRepositoryLive = Layer.effect(
4
  GameRepository,
5
  Effect.gen(function* () {
6
    const config = yield* Config;
7
    // yield* config.? // Do something with config
8
    return {
9
      getAllGames: () => Effect.succeed(Array.from(GameRepository.games.values())),
10
    };
11
  }),
12
);

Before we can use this layer, we need to satisfy its Config dependency.

1
const ConfigLive = Layer.succeed(Config, {});
2

3
//        ┌─ Layer.Layer<GameRepository, never, never>
4
//        ▼
5
const MainLive = GameRepositoryLive.pipe(Layer.provide(ConfigLive));
6

7
const runnable = Effect.provide(program, MainLive);

It is worth pointing out that these two composition styles are equivalent:

1
const MainLive = GameRepositoryLive.pipe(Layer.provide(ConfigLive));
2

3
const MainLive = Layer.provide(GameRepositoryLive, ConfigLive);

Best Practices

Provide Dependencies at the Declaration Site

A best practice is to provide dependencies where the service is declared.

1
const GameRepositoryLive = Layer.effect(
2
  GameRepository,
3
  Effect.gen(function* () {
4
    ...,
5
  })
6
).pipe(Layer.provide(ConfigLive));

Now the entry point only needs to provide GameRepositoryLive:

1
const MainLive = GameRepositoryLive;
2

3
const runnable = Effect.provide(program, MainLive);

The dependency on Config is an implementation detail, invisible to consumers.

Conclusion

Without Layers, service-to-service dependencies leak into interfaces, coupling consumers to implementation details. The workaround—constructor Effects with closures—is verbose and scales poorly.

Layers formalise this pattern. They separate what a service provides from what it needs to be built. Dependencies become construction-time concerns, invisible to consumers. The compositional API (Layer.provide, Layer.merge) handles complex dependency graphs without manual wiring.

Use Layer.succeed for services with no dependencies. Use Layer.effect when construction requires other services. Provide dependencies at the declaration site to keep implementation details encapsulated.