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):

Effect.cachedWithTTL(...)

Cache.make({ capacity, timeToLive, lookup })

Effect.cachedInvalidateWithTTL(...)

cache.invalidate(key)

cache.invalidateAll()

Effect.mapError(effect, fn)

Effect.mapError(fn)

Effect.catchTag

import { Schema } from "@effect/schema"

import { Schema } from "effect"

import { JSONSchema } from "@effect/schema"

import { JSONSchema } from "effect"

FiberRef

ServiceMap.Reference

new MyError("message")

new MyError({ message: "..." })

v3-specific hallucinations:

Effect.Service

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):

Context.Tag("X")

ServiceMap.Service<X>(id)

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

yield* ref

yield* Ref.get(ref)

yield* fiber

yield* Fiber.join(fiber)

Logger.Default

Logger.Live

Logger.layer

Schema.TaggedError

Schema.TaggedErrorClass

Read

references/llm-corrections.md

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

Effect.andThen

Effect.map

Effect.tap

Effect.all

Running:

Effect.runPromise

NodeRuntime.runMain

Error handling:

Effect.catchTag

Effect.catchAll

Effect.catch

Effect.orDie

Resources:

Effect.acquireRelease

Effect.acquireUseRelease

Effect.scoped

Dependencies:

Effect.provide

Effect.provideService

Key modules:

Effect

Schema

Layer

Option

Either

Result

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

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