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

1. Identify the Layer or Service API you need
2. Search docs/effect-source/effect/src/Layer.ts for the implementation
3. Study the types and composition patterns
4. Look at test files for usage examples
5. 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