effect-layer-design

Use Layer.effect with Effect.gen to yield the dependency service inside the constructor, then return the new service via Service.of. The layer type becomes Layer<Output, Error, Dependency>, making the requirement explicit in the type signature.

Layer.merge combines independent layers in parallel, unioning both outputs and requirements. Layer.provide chains layers sequentially, satisfying the inner layer's requirements with the outer layer and removing them from the output type.

No. In Effect v4, Layer.effect automatically handles the Scope lifecycle, so Layer.scoped is no longer needed. Acquire resources with Effect.acquireRelease or Effect.addFinalizer directly inside the Layer.effect constructor.

Use Layer.provideMerge when building test layer stacks where multiple downstream layers need access to the same upstream services. It satisfies the dependency while keeping it in the output type, unlike Layer.provide which removes it.

Use Layer.suspend only for real circular-import or module-evaluation hazards, runtime-selected layer variants, or recursive layer graphs. In the normal case, compose defaultLayer directly with Layer.provide without deferral.

Combine SynchronizedRef.modifyEffect with a Deferred-based state machine. The atomic modify ensures only one execution starts, while concurrent callers awaiting the same Deferred share the in-flight result.