Layers & Services

When to use

• You need DI boundaries or swapping test/live implementations

• You want to compose infra (logger, db, http) once for the app

Define Service

class UserRepo extends Effect.Service<UserRepo>()("UserRepo", { sync: () => ({ find: (id: string) => Effect.succeed({ id }) }) }) {}

Provide Layer

const program = Effect.gen(function* () { const repo = yield* UserRepo return yield* repo.find("123") }).pipe(Effect.provide(UserRepo.Default))

Compose

const AppLayer = Layer.merge(UserRepo.Default, Logger.Default)

Test vs Live

const layer = process.env.NODE_ENV === "test" ? UserRepoTest : UserRepo.Default

Guidance

• Services define interfaces; Layers bind implementations

• Compose layers at the app boundary; keep handlers unaware of wiring

• Use .Default for quick live/test setup; add custom layers as needed

Pitfalls

• Circular layer dependencies → split modules, provide from above

• Providing layers too deep → centralize to avoid duplication and confusion

Cross-links

• Foundations: requirement channel R and provisioning

• Resources: scoped resources exposed via layers

• EffectPatterns inspiration: https://github.com/PaulJPhilp/EffectPatterns

Local Source Reference

CRITICAL: Search local Effect source before implementing

The full Effect source code is available at docs/effect-source/ . Always search the actual implementation before writing Effect code.

Key Source Files

• Layer: docs/effect-source/effect/src/Layer.ts

• Effect: docs/effect-source/effect/src/Effect.ts

• Context: docs/effect-source/effect/src/Context.ts

Example Searches

Find Layer composition patterns

grep -F "Layer.merge" docs/effect-source/effect/src/Layer.ts grep -F "Layer.provide" docs/effect-source/effect/src/Layer.ts

Study Effect.Service patterns

grep -F "Effect.Service" docs/effect-source/effect/src/Effect.ts

Find Context usage

grep -F "Tag" docs/effect-source/effect/src/Context.ts grep -F "make" docs/effect-source/effect/src/Context.ts

Look at Layer test examples

grep -F "Layer." docs/effect-source/effect/test/Layer.test.ts

Workflow

• Identify the Layer or Service API you need

• Search docs/effect-source/effect/src/Layer.ts for the implementation

• Study the types and composition patterns

• Look at test files for usage examples

• Write your code based on real implementations

Real source code > documentation > assumptions

References

• Agent Skills overview: https://www.anthropic.com/news/skills

• Skills guide: https://docs.claude.com/en/docs/claude-code/skills