effect-ts

Effect-TS guide for TypeScript, v4 default with v3 support. Use when writing, debugging, or reviewing Effect code across errors, concurrency, services, streams, and schema, or when code imports from 'effect' or any '@effect/*' package.

Effect is a TypeScript library for building production-grade software with typed errors, structured concurrency, dependency injection, and built-in observability.

Version Detection

Before writing Effect code, detect which version the user is on:

bash

# Check installed version
cat package.json | grep '"effect"'

• v4.x (recommended, the direction Effect is heading): Context.Service, Effect.catch, Effect.forkChild, Schema.TaggedErrorClass
• v3.x (stable, still common in production): Context.Tag, Effect.catchAll, Effect.fork, Data.TaggedError

Note: v4 beta briefly used a ServiceMap module, renamed back to Context on 2026-04-07 (PR #1961). If you see ServiceMap.* in any doc or older beta code, it is the current Context.*. Both v3 and v4 import Context from "effect"; the exports inside differ (Context.Service in v4 vs Context.Tag in v3).

Prefer v4 for new projects - it's where Effect is going. In an existing codebase, match the installed version: don't rewrite v3 code in v4 syntax unless asked. If the version is genuinely unclear, default to v4 and say so. v4 is still in beta, so pin an exact version (4.0.0-beta.x) and expect occasional API churn.

Primary Documentation Sources

v4 (primary):

• https://github.com/Effect-TS/effect-smol (v4 source + migration guides)
• https://github.com/Effect-TS/effect-smol/blob/main/LLMS.md (v4 LLM guide)

v3 (for existing codebases):

• https://effect.website/docs (v3 stable docs)
• https://effect.website/llms.txt (LLM topic index)
• https://effect.website/llms-full.txt (full docs for large context)

Both versions:

• https://tim-smart.github.io/effect-io-ai/ (concise API list)

AI Guardrails: Critical Corrections

LLM outputs frequently contain incorrect Effect APIs. Verify every API against the reference docs before using it.

Common hallucinations (both versions):

Wrong (AI often generates)	Correct
Effect.cachedWithTTL(...)	Cache.make({ capacity, timeToLive, lookup })
Effect.cachedInvalidateWithTTL(...)	cache.invalidate(key) / cache.invalidateAll()
Effect.mapError(effect, fn)	Effect.mapError(fn) in pipe, or use Effect.catchTag
import { Schema } from "@effect/schema"	import { Schema } from "effect" (v3.10+ and all v4)
import { JSONSchema } from "@effect/schema"	import { JSONSchema } from "effect" (v3.10+)
JSON Schema Draft 2020-12	Effect Schema generates Draft-07
"thread-local storage"	"fiber-local storage" via FiberRef (v3) / Context.Reference (v4)
fibers are "cancelled"	fibers are "interrupted"
all queues have back-pressure	only bounded queues; sliding/dropping do not
new MyError("message")	new MyError({ message: "..." }) (Schema errors take objects)

v3-specific hallucinations:

Wrong	Correct (v3)
Effect.Service (function call)	class Foo extends Effect.Service<Foo>()("id", {})
Effect.match(effect, { ... })	Effect.match(effect, { onSuccess, onFailure })
Effect.provide(layer1, layer2)	Effect.provide(Layer.merge(layer1, layer2))

v4-specific hallucinations (AI may mix v3/v4):

Wrong (v3 API used in v4 code)	Correct (v4)
Context.Tag("X") (v3 shape)	Context.Service<X>(id) or class syntax
ServiceMap.Service / ServiceMap.Reference	Renamed back to Context.Service / Context.Reference on 2026-04-07
Effect.catchAll(fn)	Effect.catch(fn)
Effect.fork(effect)	Effect.forkChild(effect)
Effect.forkDaemon(effect)	Effect.forkDetach(effect)
Data.TaggedError	Schema.TaggedErrorClass
FiberRef.get(ref)	yield* References.X (a Context.Reference)
yield* ref (Ref as Effect)	yield* Ref.get(ref) (Ref is no longer an Effect)
yield* fiber (Fiber as Effect)	yield* Fiber.join(fiber) (Fiber is no longer Effect)
Logger.Default / Logger.Live	Logger.layer (v4 naming convention)
Schema.TaggedError	Schema.TaggedErrorClass
Schema.makeUnsafe(input)	Schema.make(input) (throws SchemaError); also instance methods schema.makeOption(...), schema.makeEffect(...)
ParseResult (from "effect")	SchemaIssue module + SchemaError class; narrow with Schema.isSchemaError
HttpApiEndpoint.get(n, p).pipe(HttpApiEndpoint.setPath(...), setPayload(...), setSuccess(...))	HttpApiEndpoint.get(n, p, { params, query, payload, success, error }) (object-option form)
Otlp.layer({ url, serviceName })	OtlpTracer.layer({ url, resource: { serviceName } }) + OtlpSerialization.layerJson + FetchHttpClient.layer
import { HttpApi } from "@effect/platform" (v4)	import { HttpApi } from "effect/unstable/httpapi"
HttpApi endpoint schema errors are typed errors by default	In current v4 betas they default to defects unless transformed

Read references/llm-corrections.md for the exhaustive corrections table.

Progressive Disclosure

Read only the reference files relevant to your task:

• Error modeling or typed failures → references/error-modeling.md
• Services, DI, or Layer wiring → references/dependency-injection.md
• Per-key dynamic layers (per-tenant resources, LayerMap) → references/dependency-injection.md
• Bridging Effect into non-Effect frameworks (Hono/Express, ManagedRuntime) → references/dependency-injection.md
• Retries, timeouts, or backoff → references/retry-scheduling.md
• Fibers, forking, or parallel work → references/concurrency.md
• Request batching, N+1 elimination, DataLoader pattern → references/concurrency.md
• Multi-provider fallback (ExecutionPlan) → references/effect-ai.md / references/retry-scheduling.md
• Streams, queues, or SSE → references/streams.md
• Framing streams (NDJSON / MessagePack encode-decode) → references/streams.md
• Running child processes / shelling out → references/concurrency.md
• Resource lifecycle or cleanup → references/resource-management.md
• Refreshable values (rotating credentials, polled config) → references/resource-management.md
• Reference-counted shared resources (RcRef/RcMap) → references/resource-management.md
• Schema validation or decoding → references/schema.md
• Branded / nominal types (Brand) → references/schema.md
• Logging, metrics, or tracing → references/observability.md
• HTTP clients or API calls → references/http.md
• HTTP API servers → references/http.md (covers both client and server)
• File uploads / multipart form-data → references/http.md
• LLM/AI integration → references/effect-ai.md
• Configuration, env vars, secrets → references/configuration.md
• SQL / database access → references/sql.md
• Command-line apps → references/cli.md
• Typed client/server RPC → references/rpc.md
• Sharded entities, durable workflows, event sourcing → references/distributed.md
• Transactional state (STM, Tx*) → references/stm.md
• Date/time handling → references/datetime.md
• Immutable nested updates (optics) → references/optics.md
• Graphs, dependency ordering, shortest paths, cycle detection → references/graph.md
• Pattern matching (Match) → references/core-patterns.md
• Pooling resources (Pool) → references/resource-management.md
• Fiber sets, SubscriptionRef, worker threads → references/concurrency.md
• Testing Effect code → references/testing.md
• Property-based testing / generating data from schemas → references/testing.md
• Migrating from async/await → references/migration-async.md
• Migrating from v3 to v4 → references/migration-v4.md
• Core types, gen, pipe, running → references/core-patterns.md
• Full wrong-vs-correct API table → references/llm-corrections.md

Core Workflow

1. Detect version from package.json before writing any code
2. Clarify boundaries: identify where IO happens, keep core logic as Effect values
3. Choose style: use Effect.gen for sequential logic, pipelines for simple transforms. In v4, prefer Effect.fn("name") for named functions
4. Model errors explicitly: type expected errors in the E channel; treat bugs as defects
5. Model dependencies with services and layers; keep interfaces free of construction logic
6. Manage resources with Scope when opening/closing things (files, connections, etc.)
7. Provide layers and run effects only at program edges (NodeRuntime.runMain or ManagedRuntime)
8. Verify APIs exist before using them - consult https://tim-smart.github.io/effect-io-ai/ or source docs

Starter Function Set

Start with these ~20 functions (the official recommended set):

Creating effects: Effect.succeed, Effect.fail, Effect.sync, Effect.tryPromise

Composition: Effect.gen (+ Effect.fn in v4), Effect.andThen, Effect.map, Effect.tap, Effect.all

Running: Effect.runPromise, NodeRuntime.runMain (preferred for entry points)

Error handling: Effect.catchTag, Effect.catch (v4) / Effect.catchAll (v3), Effect.orDie

Resources: Effect.acquireRelease, Effect.acquireUseRelease, Effect.scoped

Dependencies: Effect.provide, Effect.provideService

Key modules: Effect, Schema, Layer, Option, Result (v4) / Either (v3), Array, Match

DI (v4): Context.Service, Context.Reference, Layer.effect, Effect.fn("name") DI (v3): Context.Tag, Context.Reference

Import Patterns

Always use barrel imports from "effect":

typescript

import { Context, Effect, Schema, Layer, Option, Stream } from "effect"

For companion packages, import from the package name. v3 and v4 differ here:

typescript

// v4 (recommended) - platform transports still separate, but HttpApi / observability
// moved under effect/unstable/*
import { NodeRuntime } from "@effect/platform-node"
import { FetchHttpClient } from "effect/unstable/http"
import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiBuilder, HttpApiScalar } from "effect/unstable/httpapi"
import { OtlpLogger, OtlpSerialization, OtlpTracer } from "effect/unstable/observability"

// v3 (stable) companion packages
import { NodeRuntime } from "@effect/platform-node"
import { HttpClient } from "@effect/platform"
import { NodeSdk } from "@effect/opentelemetry"

Avoid deep module imports (effect/Effect) unless your bundler requires it for tree-shaking.

Output Standards

• Show imports in every code example
• Prefer Effect.gen (imperative) for multi-step logic; pipelines for transforms
• In v4, use Effect.fn("name") instead of bare Effect.gen for named functions; use Effect.fnUntraced for internal helpers that don't need a span/stack-frame
• Never call Effect.runPromise / Effect.runSync inside library code - only at program edges
• Use NodeRuntime.runMain for CLI/server entry points (handles SIGINT gracefully)
• Use ManagedRuntime when integrating Effect into non-Effect frameworks (Hono, Express, etc.)
• Always return yield* when raising an error in a generator (ensures TS understands control flow)
• Avoid point-free/tacit usage: write Effect.map((x) => fn(x)) not Effect.map(fn) (generics get erased)
• Keep dependency graphs explicit (services, layers, tags)
• State the Effect<A, E, R> shape when it helps design decisions

Agent Quality Checklist

Before outputting Effect code, verify:

• Every API exists (check against tim-smart API list or source docs)
• Imports are from "effect" (not @effect/schema, @effect/io, etc.)
• Version matches the user's codebase (v3 vs v4 syntax)
• Expected errors are typed in E; unexpected failures are defects
• run* is called only at program edges, not inside library code
• Resources opened with acquireRelease are wrapped in Effect.scoped
• Layers are provided before running (no missing R requirements)
• Generator bodies use yield* (not yield without *)
• Error raises in generators use return yield* pattern