Idiomatic Effect-TS

Write Effect code that looks like it came from the Effect core team.

Prerequisites (Optional)

• Effect source (recommended): git clone https://github.com/Effect-TS/effect for pattern verification
• Effect MCP: https://github.com/tim-smart/effect-mcp for API lookups (fallback: https://effect.website/docs)

Research First (ALWAYS)

1. Effect Docs MCP (preferred for concepts)

If you have effect-mcp configured:

// Search documentation
mcp__effect-docs__effect_docs_search({ query: "Layer composition" })

// Then read specific doc
mcp__effect-docs__get_effect_doc({ documentId: 123 })

Otherwise, check https://effect.website/docs for API reference.

2. Effect Source (preferred for real patterns)

# Clone Effect source for pattern verification (if not already done)
# git clone https://github.com/Effect-TS/effect <effect-repo>

# Service patterns (Context.Tag for libraries)
rg "class .* extends Context\.Tag" <effect-repo>/packages/workflow/src
rg "class .* extends Context\.Tag" <effect-repo>/packages/cluster/src

# Effect.Service for concrete impls/tests
rg "Effect\.Service" <effect-repo>/packages/cluster/src

# Error patterns
rg "Schema\.TaggedError" <effect-repo>/packages/cluster/src

# Layer composition
rg "Layer.provideMerge" <effect-repo>/packages/platform/src

Use parallel searches when patterns are unclear.

Quick Reference

Service Patterns (Choose Based on Use Case)

Pattern	Use When	Layer Access
Context.Tag	Library interfaces, multiple impls	ServiceName.Live
Effect.Service	Concrete impls, tests, apps	ServiceName.Default

// Library interface (Context.Tag) - canonical for libraries
export class MyService extends Context.Tag("app/MyService")<MyService, {
  readonly doThing: (x: string) => Effect.Effect<Result, MyError>
}>() {
  static readonly Live: Layer.Layer<MyService, never, Deps> = Layer.effect(...)
}

// Concrete impl (Effect.Service) - convenient for apps/tests
export class AppCache extends Effect.Service<AppCache>()("app/Cache", {
  effect: Effect.gen(function* () {
    return { get: (k) => ..., set: (k, v) => ... }
  }),
  dependencies: [SomeDep.Default]  // auto-composed
}) {}

Domain Errors

export class MyError extends Schema.TaggedError<MyError>()("MyError", {
  reason: Schema.Literal("NotFound", "Invalid"),
  cause: Schema.optional(Schema.Defect)
}) {
  static is(u: unknown): u is MyError {
    return hasProperty(u, "_tag") && isTagged(u, "MyError")
  }
}

Domain Types

// Value objects
export class Address extends Schema.Class<Address>("Address")({
  host: Schema.String,
  port: Schema.Number
}) {}

// Branded IDs — always with REAL constraints
export const UserId = Schema.NonEmptyString.pipe(
  Schema.pattern(/^usr_[a-z0-9]+$/),
  Schema.brand("UserId")
)
export type UserId = typeof UserId.Type

Layer Composition — COMMON GOTCHA

This causes most Effect type errors. Know the difference:

Method	Deps Satisfied	Available to Program	Use When
Layer.provide	Yes	No	Internal layer building
Layer.provideMerge	Yes	Yes	Tests using multiple services
Layer.mergeAll	No	Yes	Combining independent layers

// WRONG - test can't access FileSystem
const TestLive = MyService.Live.pipe(Layer.provide(PlatformLive))
// yield* FileSystem.FileSystem -> ERROR

// RIGHT - both services available
const TestLive = MyService.Live.pipe(Layer.provideMerge(PlatformLive))
// yield* MyService -> works
// yield* FileSystem.FileSystem -> also works!

Error pattern to recognize:

Effect<A, E, SomeService> is not assignable to Effect<A, E, never>

or diagnostic: Missing 'SomeService' in the expected Effect context

-> Means SomeService still required. Use provideMerge instead of provide.

Test Pattern

it.effect("works", () =>
  Effect.gen(function* () {
    const svc = yield* MyService
    expect(yield* svc.doThing("x")).toBe(expected)
  }).pipe(Effect.provide(TestLive))  // <- MUST provide at boundary
)

References (Read When Needed)

Topic	File	When to Read
Service & Layer patterns	references/services.md	Creating services, Context.Tag vs Effect.Service, layer composition
Layer dependencies	references/layer-dependencies.md	How services access deps (yield + closure), why NOT factory functions
Schema decision matrix	references/schema-decision.md	Schema.Class vs Struct vs TaggedClass, branded types, migration patterns
Error handling	references/errors.md	Schema.TaggedError, TypeId, refail patterns
Domain types	references/domain-types.md	Schema.Class, branded types, TaggedRequest
Testing	references/testing.md	@effect/vitest setup, TDD workflow, test helpers
Collections & State	references/data.md	Chunk, Option, Ref patterns
Process management	references/processes.md	Scope, Command, background processes

Anti-Patterns

Anti-Pattern	Fix
Data.TaggedError for domain errors	Use Schema.TaggedError
Layer.mergeAll with dependent layers	Use Layer.provideMerge
try/catch in Effect.gen	Use Effect.try or mapError
Missing Effect.provide(...) in tests	Always provide at test boundary
Plain interfaces for domain types	Use Schema.Struct (or Schema.Class if needs behavior)
String IDs without branding	Use Schema.brand()
Guessing patterns	Grep Effect source first
Effect.Service for library interfaces	Use Context.Tag
Factory function with service param	Yield deps in Effect.gen, close over (see layer-dependencies.md)
Schema.Class for simple DTOs	Use Schema.Struct unless needs Equal/Hash
String literal union in struct	Use Schema.TaggedClass for variants
Phantom type & { _tag }	Use Schema.brand() for runtime validation
Bare Schema.String.pipe(Schema.brand(...))	Add real constraints: NonEmptyString, pattern(), etc.