Effect-TS

Overview

• https://effect.website/llms.txt (LLM-oriented topic index)
• https://effect.website/docs
• https://effect.website/docs/platform
• https://effect.website/docs/ai/introduction
• https://effect.website/docs/additional-resources/api-reference
• https://tim-smart.github.io/effect-io-ai/ (concise API list)

Progressive Disclosure

1. Start with

   references/docs-index.md

   for topic routing.
2. Read one primary guide for the task.
3. Read one adjacent guide only if needed (for cross-cutting concerns like testing, runtime, or observability).
4. Avoid loading unrelated references.

Quick Triage

• If it needs core Effect data types or combinators, open

  references/core-usage.md

  .
• If it needs broader data-type choices (DateTime, BigDecimal, HashSet, Redacted), open

  references/data-types-advanced.md

  .
• If it needs equality/order/hash semantics, open

  references/behavior-traits.md

  .
• If the task is about error modeling or typed failures, open

  references/error-management.md

  .
• If it needs error tooling (sandboxing, Cause, error-channel transforms), open

  references/error-tooling.md

  .
• If it involves services/dependencies, open

  references/dependency-management.md

  .
• If it involves layer construction or test wiring, open

  references/layer-patterns.md

  .
• If it involves resource lifecycles, open

  references/resource-management.md

  .
• If it involves running effects or runtime choice, open

  references/runtime-execution.md

  .
• If it involves fibers or concurrency primitives, open

  references/concurrency.md

  .
• If it involves interruption, supervision, or fiber refs, open

  references/concurrency-advanced.md

  .
• If it involves schedules or repetition, open

  references/scheduling.md

  .
• If it involves retries/backoff or schedule composition, open

  references/scheduling-retry.md

  .
• If it involves streams, queues, pubsub, or STM, open

  references/streams-queues-stm.md

  .
• If it involves HTTP clients or external APIs, open

  references/http-client.md

  .
• If it involves HTTP servers or API definitions, open

  references/http-server.md

  .
• If it involves request batching or data loaders, open

  references/request-resolver.md

  .
• If it involves caching or memoization, open

  references/caching.md

  .
• If it involves configuration or config providers, open

  references/configuration.md

  .
• If it involves advanced config or redaction, open

  references/configuration-advanced.md

  .
• If it involves logs, metrics, or tracing, open

  references/observability.md

  .
• If it needs concrete logger/metrics/tracing setups or exporters, open

  references/observability-examples.md

  .
• If it needs wiring of log/metric/trace layers, open

  references/observability-wiring.md

  .
• If it needs sequential/branching readability, open

  references/generators.md

  .
• If it needs runtime validation/decoding, open

  references/schema.md

  .
• If it involves stream consumption patterns with reducers, open

  references/sink.md

  .
• If it needs deterministic time in tests, open

  references/testing.md

  .
• If it needs broader testing services, open

  references/testing-stack.md

  .
• If it involves command/file/path/terminal/key-value modules, open

  references/platform-primitives.md

  .
• If it involves LLM workflows, planning, or tool use via Effect AI, open

  references/ai.md

  .
• If it involves bundle-size constrained runtimes, open

  references/micro.md

  .
• If it involves migrating from Promise/async, open

  references/migration-async.md

  .
• If it needs versioning or signature changes, open

  references/versioning.md

  .
• If it hits common pitfalls or runtime errors, open

  references/troubleshooting.md

  .
• If it needs result inspection or debugging, open

  references/exit-cause.md

  .
• If it needs a docs-to-guide map from

  llms.txt

  , open

  references/docs-index.md

  .

Core Workflow

1. Clarify boundaries and IO; keep core logic as

   Effect

   values.
2. Choose style: use pipelines for simple composition; use

   Effect.gen

   for sequential logic.
3. Model errors explicitly: type expected errors; treat defects as unexpected failures.
4. Model dependencies with services, tags, and layers; keep interfaces clean of construction concerns.
5. Manage resource lifecycles with

   Scope

   when opening/closing resources.
6. Provide the environment via layers and run effects only at the program edge.
7. For platform/infra code, keep side effects in dedicated adapters and expose typed services to domain code.
8. For agent tasks, include a concise rationale for error, concurrency, and runtime choices.

Output Standards

• Show imports and minimal runnable examples.
• Prefer barrel imports (

  from "effect"

  /

  from "@effect/platform"

  ) over deep module paths.
• When function-style composition is clearer, use

  pipe

  from

  effect

  .
• Keep dependency graphs explicit (services, layers, context tags).
• Include error channel types and call out expected vs defect errors.
• Avoid running effects inside libraries; show runtime usage in entrypoints or tests.
• Prefer examples that compile under current Effect major versions.

Agent Quality Checklist

• State the target shape as

  Effect<A, E, R>

  when it helps design decisions.
• Explicitly separate expected errors (

  E

  ) from defects.
• Identify where layers are provided and where

  run*

  is called.
• For concurrent code, state bounded/unbounded behavior and shutdown strategy.
• For boundary decoding, show Schema usage and where failures are handled.
• For tests, note which test services are provided (

  TestContext

  ,

  TestClock

  , live overrides).
• For docs uncertainty, consult

  references/docs-index.md

  and source docs before finalizing APIs.

References

• Start at

  references/docs-index.md

  to choose relevant guides quickly.
• Use

  references/core-usage.md

  ,

  references/error-management.md

  , and

  references/dependency-management.md

  as defaults for most code tasks.
• Use platform/runtime references (

  references/platform-primitives.md

  ,

  references/runtime-execution.md

  ) for boundary and integration work.
• Use testing/diagnostic references (

  references/testing.md

  ,

  references/testing-stack.md

  ,

  references/troubleshooting.md

  ) for verification and debugging.