requirements

Requirements Management in Effect

Overview

The third type parameter in Effect<A, E, R> represents requirements - services and dependencies the effect needs to run:

Effect<Success, Error, Requirements>;
//                     ^^^^^^^^^^^^ Services needed

Effect uses a powerful dependency injection system based on Context and Layer.

The primary reason to define services is testability. Every external dependency (API calls, databases, file systems, third-party SDKs) MUST be wrapped in a Context.Tag service so that tests can provide a test implementation instead of hitting real systems. This is how Effect achieves 100% test coverage — business logic depends only on service interfaces, and tests swap in test layers that control all I/O.

Defining Services

Using Effect.Tag (Recommended)

import { Effect, Context } from "effect";

// Define service interface and tag together
class UserRepository extends Context.Tag("UserRepository")<
  UserRepository,
  {
    readonly findById: (id: string) => Effect.Effect<User, UserNotFound>;
    readonly save: (user: User) => Effect.Effect<void>;
  }
>() {}

// Using the service
const program = Effect.gen(function* () {
  const repo = yield* UserRepository;
  const user = yield* repo.findById("123");
  return user;
});
// Type: Effect<User, UserNotFound, UserRepository>

Alternative: Context.Tag Directly

interface UserRepository {
  readonly findById: (id: string) => Effect.Effect<User, UserNotFound>;
}

const UserRepository = Context.Tag<UserRepository>("UserRepository");

Using Services

const program = Effect.gen(function* () {
  const userRepo = yield* UserRepository;
  const emailService = yield* EmailService;

  const user = yield* userRepo.findById(userId);
  yield* emailService.send(user.email, "Welcome!");
});

Creating Layers

Layers are recipes for building services:

Layer.succeed - Simple Value

const LoggerLive = Layer.succeed(Logger, {
  log: (msg) => Effect.sync(() => console.log(msg)),
});

Layer.effect - Effect-Based Construction

const ConfigLive = Layer.effect(
  Config,
  Effect.gen(function* () {
    const env = yield* Effect.sync(() => process.env);
    return {
      apiUrl: env.API_URL ?? "http://localhost:3000",
      debug: env.DEBUG === "true",
    };
  }),
);

Layer.scoped - Resource with Lifecycle

const DatabaseLive = Layer.scoped(
  Database,
  Effect.gen(function* () {
    const pool = yield* Effect.acquireRelease(createPool(), (pool) => Effect.promise(() => pool.end()));
    return {
      query: (sql) => Effect.promise(() => pool.query(sql)),
    };
  }),
);

Layer.function - From Function

const HttpClientLive = Layer.function(HttpClient, (baseUrl: string) => ({
  get: (path) => Effect.tryPromise(() => fetch(baseUrl + path)),
}));

Providing Dependencies

Effect.provide - Provide Layer

const program = getUserById("123");

const runnable = program.pipe(Effect.provide(AppLive));

await Effect.runPromise(runnable);

Effect.provideService - Provide Single Service

const runnable = program.pipe(
  Effect.provideService(UserRepository, {
    findById: (id) => Effect.succeed(mockUser),
    save: (user) => Effect.void,
  }),
);

Composing Layers

Layer.merge - Combine Independent Layers

const InfraLive = Layer.merge(DatabaseLive, LoggerLive);

Layer.provide - Layer Dependencies

const UserRepositoryLive = Layer.effect(
  UserRepository,
  Effect.gen(function* () {
    const db = yield* Database;
    return {
      findById: (id) => db.query(`SELECT * FROM users WHERE id = ${id}`),
    };
  }),
);

const FullUserRepo = UserRepositoryLive.pipe(Layer.provide(DatabaseLive));

Layer.provideMerge - Provide and Keep

const Combined = UserRepositoryLive.pipe(Layer.provideMerge(DatabaseLive));

Building Application Layers

Typical Pattern

const InfraLive = Layer.mergeAll(DatabaseLive, LoggerLive, HttpClientLive);

const RepositoryLive = Layer.mergeAll(UserRepositoryLive, OrderRepositoryLive).pipe(Layer.provide(InfraLive));

const ServiceLive = Layer.mergeAll(UserServiceLive, OrderServiceLive).pipe(Layer.provide(RepositoryLive));

const AppLive = ServiceLive.pipe(Layer.provide(InfraLive));

Layer Memoization

Layers are memoized by default - each service is created once:

const AppLive = Layer.mergeAll(UserServiceLive, OrderServiceLive).pipe(Layer.provide(DatabaseLive));

Fresh Layers (No Memoization)

const FreshDatabase = Layer.fresh(DatabaseLive);

Default Services

Effect provides default implementations for common services:

const program = Effect.gen(function* () {
  const now = yield* Clock.currentTimeMillis;
  const random = yield* Random.next;
});

Overriding Defaults

import { TestClock } from "effect";

const testProgram = program.pipe(Effect.provide(TestClock.layer));

Testing with Services (CRITICAL for 100% Coverage)

Every service MUST have a test layer. This is how you achieve complete test coverage without hitting real external systems.

Simple Test Layer (Stateless)

Use Layer.succeed for services that don't need to track state:

const EmailServiceTest = Layer.succeed(EmailService, {
  send: (to, subject, body) => Effect.void, // No-op in tests
  sendBulk: (recipients, subject, body) => Effect.void,
});

Stateful Test Layer (Repositories)

Use Layer.effect with Ref for services that need to maintain state:

const UserRepositoryTest = Layer.effect(
  UserRepository,
  Effect.gen(function* () {
    const store = yield* Ref.make<Map<string, User>>(new Map());

    return {
      findById: (id: string) =>
        Effect.gen(function* () {
          const users = yield* Ref.get(store);
          return yield* Option.match(Option.fromNullable(users.get(id)), {
            onNone: () => Effect.fail(new UserNotFound({ userId: id })),
            onSome: Effect.succeed,
          }).pipe(Effect.flatten);
        }),
      save: (user: User) => Ref.update(store, (m) => new Map(m).set(user.id, user)),
    };
  }),
);

Composing Test Layers

const TestEnv = Layer.mergeAll(UserRepositoryTest, EmailServiceTest, PaymentGatewayTest);

Using Test Layers with @effect/vitest

import { it, expect, layer } from "@effect/vitest";
import { Effect } from "effect";

layer(TestEnv)("UserService", (it) => {
  it.effect("should create user and send welcome email", () =>
    Effect.gen(function* () {
      const repo = yield* UserRepository;
      const email = yield* EmailService;

      const user = new User({ id: "1", name: "Alice", email: "alice@test.com" });
      yield* repo.save(user);
      yield* email.send(user.email, "Welcome!", "Hello Alice");

      const found = yield* repo.findById("1");
      expect(found.name).toBe("Alice");
    }),
  );
});

Combining Test Layers with Property Testing

The ultimate testing pattern — service test layers control all I/O, Arbitrary generates all data:

layer(TestEnv)("UserService Properties", (it) => {
  it.effect.prop("should save and retrieve any valid user", [Arbitrary.make(User)], ([user]) =>
    Effect.gen(function* () {
      const repo = yield* UserRepository;
      yield* repo.save(user);
      const found = yield* repo.findById(user.id);
      expect(found).toEqual(user);
    }),
  );
});

Best Practices

1. Define service interface with Tag - Keeps interface and tag together
2. ALWAYS create a test layer for every service - This is required, not optional. Without test layers, your code is untestable.
3. Wrap ALL external dependencies in services - API calls, database queries, file I/O, third-party SDKs, email, caches, queues — everything external MUST go through a service
4. Use Layer.scoped for resources - Ensures proper cleanup
5. Compose layers bottom-up - Infrastructure → Repositories → Services
6. Keep layers focused - One service per layer typically
7. Name convention - *Live for production layers, *Test for test layers (e.g., UserRepositoryLive, UserRepositoryTest)
8. Use Layer.effect with Ref for stateful test layers - Repositories and caches need state tracking
9. Combine test layers with Arbitrary - Services control I/O, Arbitrary generates data — together they enable 100% coverage

Additional Resources

For comprehensive requirements management documentation, consult ${CLAUDE_PLUGIN_ROOT}/references/llms-full.txt.

Search for these sections:

• "Managing Services" for service patterns
• "Managing Layers" for layer composition
• "Layer Memoization" for sharing services
• "Default Services" for built-in services