effect

Effect

Use Effect throughout the application code covered by the task. A Promise application wrapped in one Effect is incomplete adoption.

The verified reference snapshot is [email protected] (first stable v4 release, npm latest, LTS). Check installed versions before changing dependencies. Do not mix v3 and v4 APIs. Projects still on 4.0.0-rc.* / beta.* must apply the RC → 4.0 upgrade in migration.md (import paths and several renames changed).

Required adoption policy

• Keep use cases, service methods, I/O, expected failures, resource ownership, and concurrent work inside Effect.
• Choose the matching Effect capability before writing a custom helper or adding an overlapping library. Consult the index below.
• Use Effect Schema for application-owned validation and codecs; Context and Layer for dependencies; Scope for cleanup.
• Use Effect scheduling, concurrency, state, configuration, and observability instead of parallel custom systems for the same responsibility.
• Keep Promise, callback, framework, and vendor APIs at named adapters. Convert once on entry and once on exit.
• Existing Elysia routes may return Promises. Their handlers delegate to Effect use cases; business logic stays outside handlers.
• Never call a runtime runner inside a domain service to make Effect look like a Promise API.
• Keep pure calculations and ordinary TypeScript data simple. They need no Effect wrapper unless they fail or perform effects.
• Prefer Effect's standard library over new duplicate utilities. Do not mechanically replace clear language operators or native data structures.
• Respect the requested scope. Convert each touched use case end to end; do not start an unrelated repository-wide migration.
• Record remaining non-Effect boundaries and their concrete constraints. Convenience alone does not justify a second application architecture.

Read adoption-boundaries.md when implementing, reviewing, or migrating a mixed codebase.

Dense capability index

Use this map before choosing an implementation. The linked catalogs cover every public module namespace and public monorepo package in the snapshot. This is a capability/module index, not a list of every function. Confirm signatures in installed declarations. Areas marked unstable are @stability unstable (may break in minor releases) even though their import paths have no unstable segment.

Responsibility	Effect capability
Use cases, typed failure, recovery	Effect.fn, Effect.gen, Cause, Exit, Result, Option, Match
Dependencies, application lifetime	Context, Layer, ManagedRuntime, Scope, LayerMap, LayerRef
Validation, codecs, domain types, derived formats	Schema, Brand, Data, StandardSchema, JsonSchema, Optic; unstable schema JIT/AOT compilers
Configuration, secrets, time, sizes, randomness	Config (PascalCase constructors), ConfigProvider, Redacted, Clock, DateTime, Duration, ByteSize, Random
Retry, repeat, timeout, fallback	Schedule, Cron, Effect timeout/retry, ExecutionPlan
Concurrency, cancellation, synchronization	Fiber, fiber collections, Deferred, Latch, Semaphore, PartitionedSemaphore
Shared and transactional state	Ref, SynchronizedRef, SubscriptionRef, ScopedRef, Effect.tx, all Tx* modules
Streaming and backpressure	Stream, Sink, Queue, PubSub; low-level Channel, Pull, Take, ChannelSchema
Cache, batching, reusable resources	Cache, ScopedCache, Request, RequestResolver, Pool, Resource, RcRef, RcMap
Collections, text, numbers, equality, algorithms	Array/Chunk/Record/Hash collections, Graph, Trie, HashRing, BigDecimal, primitive and protocol modules
Files, paths, terminal, crypto	FileSystem, Path, Stdio, Terminal, Crypto, platform implementations
Logs, traces, metrics, diagnostics	Logger, LogLevel, Tracer, Metric, ErrorReporter; unstable effect/observability, effect/devtools
HTTP, typed APIs, sockets, addresses, RPC	unstable effect/http, effect/http-api, effect/socket, effect/net, effect/rpc
Database, models, migrations	unstable effect/sql, effect/schema; SQL driver packages
Persistence, rate limits, event sourcing	unstable effect/persistence, effect/eventlog
AI, tools, MCP, embeddings, structured decisions	unstable effect/ai (incl. Decision / DecisionModel); provider packages
UI state, invalidation, hydration	unstable effect/reactivity; React/Solid/Vue bindings
Commands, subprocesses, worker pools	unstable effect/cli, effect/process, effect/workers
Distributed entities, durable work	unstable effect/cluster, effect/workflow
Byte and wire formats	effect/encoding: Base64, Base64Url, Hex (stable); NDJSON, SSE, YAML, TOML, INI, SchemaBinary (unstable). MessagePack was removed
Tests, property checks, generated docs/clients	effect/testing, unstable Arbitrary, @effect/vitest, docgen/doctest/OpenAPI tools

Exact inventories: core and testing, all subpath areas, all public packages.

Workflow

1. Inspect the local Effect surface: effect / @effect/* versions, import style (from "effect" vs effect/Effect), runtime (CLI, HTTP, worker, browser, test), and whether layers/config/platform are already in play.
2. Prefer a local checkout of Effect-TS/effect at the installed release tag (e.g. [email protected]) under .temp/effect. Effect-TS/effect-smol is archived; v4 lives in Effect-TS/effect (main), v3 on branch v3. Browse sources, LLMS.md, MIGRATION.md, migration/*, packages/effect/SCHEMA.md, and ai-docs/. Details: source-map.md.
3. Refresh docs when the installed version differs from the snapshot or the task asks for latest APIs. Resolve library docs, then check installed .d.ts.
4. Route by concern:
   • Install, Effect.fn/gen, errors, forks, run, Config → setup-core.md
   • Services, layers, scopes, ManagedRuntime, Layer.launch → services-layers-runtime.md
   • Full stable module catalog (what each module is for) → modules-stable.md
   • Stream, Queue/PubSub, fibers, STM-like Tx*, caching, requests → concurrency.md
   • Schema v4 → schema-v4.md
   • Subpath areas (effect/http, effect/sql, effect/ai, …) → modules-unstable.md
   • @effect/platform-*, sql-*, ai-*, atom-*, OTel, tools → ecosystem.md
   • @effect/vitest → vitest-testing.md
   • v3 → v4, and v4 RC → 4.0 → migration.md
5. Implement the required adoption policy, preserving compatible project conventions: match the installed version, keep framework edges thin, compose layers explicitly, treat @stability unstable areas (effect/http, effect/sql, effect/ai, …) as subject to breaking changes in minor releases and @stability experimental APIs as subject to change in patches.

Coding style (canonical)

From Effect’s own LLMS.md / ai-docs:

• Inline Effect code uses Effect.gen. Reusable effectful functions use Effect.fn("name") when a tracing span is useful, Effect.fnUntraced for library code and hot paths that are not useful tracing boundaries. Do not write plain functions that only wrap and return Effect.gen; do not .pipe the result of Effect.fn.
• Domain errors: Schema.TaggedError. Always return yield* when failing so TypeScript narrows.
• Services: Context.Service, identifier like "myapp/db/Database", implement with Database.of({ ... }), attach static readonly layer. Prefer yield* Service over Service.use except one-liners.
• Untrusted data: Schema, not ad-hoc predicates. Use Predicate for isString / isObject / composition — do not invent those helpers.
• Dates/time in Effect programs: DateTime + Clock, not raw Date.now().
• Observability: logs/traces/metrics in core; new projects prefer effect/observability OTLP. Use @effect/opentelemetry when an existing OTel SDK is required.
• Process entry: NodeRuntime.runMain / BunRuntime.runMain (BunRuntime is the shared Node runner) or DenoRuntime / BrowserRuntime, or Layer.launch. Prefer those over Runtime.makeRunMain. Cloudflare: no platform package — Fetch + SQL D1/DO drivers.
• Prefer Stream/Sink over Channel; Schema over SchemaAST; Cache vs ScopedCache vs Pool vs RcMap per concurrency.md.

Judgment

• Align v4 monorepo integration packages to the same release as effect. Check independent tooling packages against their own peers.
• TypeScript 5.9+ (7 recommended for Effect’s TS tooling). strict: true. Node 18+ generally; some SQL drivers need Node 22.16+.
• Config constructors are PascalCase in 4.0 (Config.String, Config.Int, Config.Redacted, Config.URL, …); Config.mapOrFail is Config.mapEffect.
• No v3 APIs in v4 code: Context.Tag / GenericTag, Effect.Tag / Effect.Service, Either, FiberRef, Effect.catchAll, Effect.fork (use forkChild), Effect.async (use callback).
• Layers memoize across Effect.provide unless { local: true } or Layer.fresh.
• Runtime<R> is gone. Run with Effect.run* / run*With(context) or ManagedRuntime.
• Ref / Deferred / Fiber are not yieldable Effects — use Ref.get, Deferred.await, Fiber.join.
• Prefer typed failures over throw/die. Defects are programmer errors.
• Keep Schema Encoded vs Type visible at boundaries.
• Tests: @effect/vitest@4 + vitest@^5 (peer >=5 <6). Prefer it.effect (already scoped + TestClock; do not wrap in Effect.scoped). Import TestClock from effect/testing. it.effect suppresses logs; it.live does not.
• Do not: effect/unstable/* imports (removed in 4.0)/effect/Encoding/effect/testing/FastCheck/lowercase Config.string/catchAll/fork/forkDaemon/Context.Tag/Effect.Service/.Default/Either/FiberRef/Date.now/try/catch in gen/Schema.Date for ISO strings/Union(A,B)/it.effect + extra Effect.scoped.

Module routing (quick)

Need	Use
Workflows, errors, concurrency	Effect, Cause, Exit, Result, Fiber
DI	Context, Layer, ManagedRuntime
Config	Config, ConfigProvider
Validation / domain types	Schema (+ Schema.Class / TaggedError)
Time	Clock, Duration, DateTime, Cron, Schedule
Collections	Array, Chunk, HashMap, HashSet, Record, Option
One producer, many consumers	PubSub
Work queue	Queue
Pull streams	Stream / Sink / Channel (low-level)
Atomic multi-ref updates	Effect.tx + TxRef / TxQueue / …
HTTP client/server	effect/http + @effect/platform-*
Schema-first HTTP API	effect/http-api
SQL	effect/sql + @effect/sql-*
LLM / tools	effect/ai + @effect/ai-*
Tests / property checks	@effect/vitest, effect/testing, Arbitrary

Every root module: modules-stable.md. Every subpath area: modules-unstable.md.

Verification

• Typecheck Effect<A, E, R>, layers, Schema encoded/type sides, and installed API names.
• Review the whole touched use case for hidden Promises, runtime calls, unmanaged resources, and duplicate infrastructure.
• Test adapter error mapping, cancellation, request cleanup, and application shutdown where those behaviors change.
• Report justified non-Effect boundaries and any remaining migration work; do not claim complete adoption while gaps remain.
• @effect/vitest: it.effect, TestClock, Exit/Result, per-test Effect.provide when isolation matters.
• Schema: valid/invalid input, defaults, excess keys, classes, tagged errors, JSON Schema.
• Migration scan: v3 imports, Either, FiberRef, old catch/fork/runtime/Schema APIs; RC leftovers (effect/unstable/, effect/Encoding, FastCheck, lowercase Config.*, old Schema.is* check names).