/effect-ts

name: effect-ts
description: 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.
metadata:
  version: "0.6.5"
  categories: "development"
  topics: "effect, typescript, functional-programming, concurrency, error-handling"
  upstream: "effect@4.0.0-beta.92"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/effect-ts
    emoji: "🌀"
    envVars:
      - name: OPENAI_API_KEY
        required: false
        description: OpenAI API key for Effect AI examples using the OpenAI provider.

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"'

• **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` modul