/effect

name: effect
description: |
  Opinionated guide for building production TypeScript applications with Effect v4. Use when implementing Effect workflows, services, layers, schemas, configuration, schedules, caches, streams, HTTP clients, or tests.
license: MIT
compatibility: Requires Effect v4. Examples are reviewed against the version documented in this repository.

Effect

Use current Effect v4 APIs and the production defaults in this skill. Established project conventions still take precedence unless the task is explicitly changing them.

Source Rule

Reviewed against Effect **4.0.0**, upstream commit [`6389d9ac6`](https://github.com/Effect-TS/effect/tree/6389d9ac64c0f62ccc8b575fb9afc65fc104e814). Read `references/V4_APIS.md` when upgrading from v3 or a v4 prerelease. The installed version takes precedence: prerelease APIs and import paths can differ.

Check these before guessing:

• the nearest `AGENTS.md` and any project-local Effect practices doc
• the project-pinned `effect` package source and version
• current upstream Effect source when the installed package does not answer the question

Branch Chooser

Read only the branch references that match the task.

• Data models, schemas, brands, variants, optional keys, or decoders: read `references/SCHEMA.md`.
• Services, module surfaces, layers, runtime wiring, errors, `Effect.fn`, or test services: read `references/SERVICES_LAYERS.md`.
• Runtime config, env variables, `ConfigProvider`, or `layerConfig`: read `references/CONFIG.md`.
• Retry, repeat, polling, backoff, jitter, rate-limit-aware policies, or pass loops: read `references/SCHEDULING.md`.
• Memoization, per-key TTL caches, deduplicating concurrent lookups, or request batching: read `references/CACHING.md`.
• Streams, event sources, async iterables, queues/pubsubs, pagination, backpressure, or stream consumers: read `references/STREAMS.md`.
• Outgoing HTTP calls, Effect HttpClient, status handling, or HTTP rate limiting: read `references/HTTP_CLIENTS.md`.
• Effect tests, time, sleeps, concurrency synchronization, or fakes: read `references/TESTING.md`.

If a task spans several branches, read all matching files before editing.

Core Defaults

• Compose workflows with `Effect.gen(function* () { ... })`.
• Define public service methods and non-trivial internal service methods with `Effect.fn("Domain.operation")`.
• Use `Effect.fnUntraced` only for internal helpers where stack-frame/span metadata is intentionally unnecessary.
• Prefer `Context.Service` for application services when the codebase has not standardized on another current service-tag style.
• Build real service implementations with `Layer.effect(Service, Effect.gen(...))` and return `Service.of({ ... })`.
• Model records with `Schema.Struct(...)` plus a same-name `interface`.
• Model typed Effect errors with `Schema.TaggedError`.
• Read runtime config through `Config`, not direct `process.env` access in application logic.
• Use `Schedule` for retry, repeat, polling, pacing, and backoff policies.
• Use `Stream` for effectful sources that emit many values over time and need pull, backpressure, interruption, or transformation.
• Prefer Effect HTTP client modules for outgoing HTTP in Effect applications when their typed errors, layers, and client transforms are useful.
• Prefer Effect-aware tests, explicit layers, and deterministic synchronization over sleeps.
• Decode unknown wire input with `Schema.decodeUnknownEffect(...)`; use `schema.makeEffect(...)` for typed constructor input with validation. Reserve throwing `schema.make(...)` for trusted construction, and never use casts to skip validation.

Quick Selection Guide

• Ordinary object record: `Schema.Struct(...)` plus same-name `interface`.
• Scalar ID/value object: constrained branded schema.
• Internal workflow decision or state: `Data.TaggedEnum<...>` plus `Data.taggedEnum<...>()` constructors and exhaustive `$match`.
• Reusable boundary-crossing tagged variant: `Schema.TaggedStruct(...)` plus same-name `interface`.
• Boundary-crossing tagged union: `Schema.TaggedUnion(...)` with `.cases`, `.guards`, and `.match`.
• External/custom discriminator such as `type`: `Schema.Struct({ type: Schema.tag("variant"), ... })` plus `Schema.toTaggedUnion("type")` when union helpers are needed.
• Expected typed failure: `Schema.TaggedError`.
• Unknown boundary payload: `Schema.decodeUnknownEffect(...)`.
• Service boundary: `Context.Service<Service, Interface>()(...)` plus `Layer.effect(...)` plus `Service.of(...)`.
• Public or non-trivial internal service method: `Effect.fn("Domain.operation")`.
• Runtime configuration: `Config` recipes read in layers; override with `ConfigProvider` in tests.
• Event source: `Stream` consumed with `Stream.runForEach(...)` and forked with `Effect.forkScoped` in the owning layer.
• Queue-backed event source: `Queue` for the producer boundary, `Stream.fromQueue(...)` for consumers.
• Broadcast event source: `PubSub` / `Stream.fromPubSub(...)` or `SubscriptionRef` for latest-value state.
• Polling worker: `runPass().pipe(Effect.repeat(Schedule.spaced(...)))`, with typed pass failures handled before repeat.
• Retry transient operation: `Effect.retry(...)` / `Effect.retryOrElse(...)` with a bounded `Schedule`.
• Keyed lookup cache with TTL and concurrent-lookup dedupe: prefer `Cache.make(...)` / exit-aware `Cache.makeWith(...)` when their lifecycle and eviction model fit.
• Memoize a single effect result: `Effect.cached(...)` / `Effect.cachedWithTTL(...)`.
• Batch N keys into one backend call (only when a real batch endpoint exists): `Effect.request(...)` + `RequestResolver`.
• HTTP request in an Effect application: prefer Effect `HttpClient` plus request/response schema decoding.
• HTTP transient retry: `HttpClient.retryTransient(...)`.
• Time-sensitive test: `TestClock`, not real sleeping.
• Concurrent/background test synchronization: `Deferred`, `Queue`, `Latch`, `Ref`, or explicit test hooks.

Boundary Rules

• Keep HTTP ha