effect-ts-layer-architect

Define the service interface, create a Tag with Context.GenericTag, then implement a Live layer using Layer.succeed, Layer.effect, or Layer.scoped depending on setup and cleanup needs. Always pair it with a Test layer built from Layer.succeed for mocking.

Layer.effect builds a service that needs setup but no cleanup, while Layer.scoped is for services holding resources that must be released, using Effect.acquireRelease. Use Layer.scoped for connections, clients, or anything with a close or disconnect method.

Wrap fallible async calls with Effect.tryPromise, non-failing async with Effect.promise, and synchronous code with Effect.try or Effect.sync. Replace async/await chains with Effect.gen to compose the steps with typed errors.

Use Effect.all with a concurrency option, such as Effect.all([...], { concurrency: N }), for bounded parallelism. For background work use Effect.fork with Fiber.join, and Effect.race when the first completed result wins.

Define tagged error classes with Data.TaggedError and declare them in each Effect's error channel. Handle them with Effect.catchTag, Effect.catchAll, or Effect.orElse so no service accidentally exposes a never error type.

Stateless services with no setup can use plain Layer.succeed without scoped lifecycle machinery. The full Layer discipline adds the most value when services have dependencies, resource lifecycles, or error channels that callers must handle explicitly.