Effect-TS

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:

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

• v3.x (stable, most production codebases): Context.Tag, Effect.catchAll, Effect.fork, Data.TaggedError
• v4.x (beta, Feb 2026+): ServiceMap.Service, Effect.catch, Effect.forkChild, Schema.TaggedErrorClass

If the version is unclear, ask the user. Default to v3 patterns for existing codebases, v4 for new projects.

Primary Documentation Sources

• 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)
• https://tim-smart.github.io/effect-io-ai/ (concise API list)
• 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)

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) / ServiceMap.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")	ServiceMap.Service<X>(id) or class syntax
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 (ServiceMap.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

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
• Retries, timeouts, or backoff → references/retry-scheduling.md
• Fibers, forking, or parallel work → references/concurrency.md
• Streams, queues, or SSE → references/streams.md
• Resource lifecycle or cleanup → references/resource-management.md
• Schema validation or decoding → 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)
• LLM/AI integration → references/effect-ai.md
• Testing Effect code → 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.catchAll (v3) / Effect.catch (v4), Effect.orDie

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

Dependencies: Effect.provide, Effect.provideService

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

Import Patterns

Always use barrel imports from "effect":

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

For companion packages, import from the package name:

import { NodeRuntime } from "@effect/platform-node"
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
• 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