effect-ts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Effect-TS

Overview

概述

Provide workflows, patterns, and best practices for building Effect-based TypeScript programs, with focused references for errors, dependencies, resources, runtime execution, generators, schema, testing, platform modules, sink/stream processing, and Effect AI.

Primary docs and API sources:

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)

For internal lookups, the effect-docs MCP can be used to search and fetch API references: https://github.com/tim-smart/effect-mcp.

为基于Effect的TypeScript程序提供工作流、模式与最佳实践，重点覆盖错误处理、依赖管理、资源管理、运行时执行、生成器、Schema、测试、平台模块、Sink/流处理以及Effect AI等领域。

主要文档与API来源：

https://effect.website/llms.txt (LLM相关主题索引)
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/ (简洁API列表)

内部查阅可使用effect-docs MCP搜索和获取API参考：https://github.com/tim-smart/effect-mcp.

Progressive Disclosure

渐进式查阅指南

Start with
```
references/docs-index.md
```
for topic routing.
Read one primary guide for the task.
Read one adjacent guide only if needed (for cross-cutting concerns like testing, runtime, or observability).
Avoid loading unrelated references.

从
```
references/docs-index.md
```
开始进行主题导航。
阅读与任务相关的一篇核心指南。
仅在需要时阅读相关的相邻指南（用于跨领域问题，如测试、运行时或可观测性）。
避免加载无关的参考资料。

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
```
.

若需要核心Effect数据类型或组合子，请打开
```
references/core-usage.md
```
。
若需要更广泛的数据类型选择（DateTime、BigDecimal、HashSet、Redacted），请打开
```
references/data-types-advanced.md
```
。
若需要相等性/排序/哈希语义相关内容，请打开
```
references/behavior-traits.md
```
。
若任务涉及错误建模或类型化失败处理，请打开
```
references/error-management.md
```
。
若需要错误工具（沙箱、Cause、错误通道转换），请打开
```
references/error-tooling.md
```
。
若涉及服务/依赖项，请打开
```
references/dependency-management.md
```
。
若涉及Layer构建或测试注入，请打开
```
references/layer-patterns.md
```
。
若涉及资源生命周期，请打开
```
references/resource-management.md
```
。
若涉及Effect运行或运行时选择，请打开
```
references/runtime-execution.md
```
。
若涉及Fiber或并发原语，请打开
```
references/concurrency.md
```
。
若涉及中断、监控或Fiber Ref，请打开
```
references/concurrency-advanced.md
```
。
若涉及调度或重复执行，请打开
```
references/scheduling.md
```
。
若涉及重试/退避或调度组合，请打开
```
references/scheduling-retry.md
```
。
若涉及流、队列、PubSub或STM，请打开
```
references/streams-queues-stm.md
```
。
若涉及HTTP客户端或外部API，请打开
```
references/http-client.md
```
。
若涉及HTTP服务器或API定义，请打开
```
references/http-server.md
```
。
若涉及请求批处理或数据加载器，请打开
```
references/request-resolver.md
```
。
若涉及缓存或记忆化，请打开
```
references/caching.md
```
。
若涉及配置或配置提供器，请打开
```
references/configuration.md
```
。
若涉及高级配置或脱敏处理，请打开
```
references/configuration-advanced.md
```
。
若涉及日志、指标或追踪，请打开
```
references/observability.md
```
。
若需要具体的日志/指标/追踪设置或导出器，请打开
```
references/observability-examples.md
```
。
若需要日志/指标/追踪Layer的注入，请打开
```
references/observability-wiring.md
```
。
若需要提升顺序/分支逻辑的可读性，请打开
```
references/generators.md
```
。
若需要运行时验证/解码，请打开
```
references/schema.md
```
。
若涉及使用Reducer的流消费模式，请打开
```
references/sink.md
```
。
若需要测试中的确定性时间，请打开
```
references/testing.md
```
。
若需要更全面的测试服务，请打开
```
references/testing-stack.md
```
。
若涉及命令/文件/路径/终端/键值模块，请打开
```
references/platform-primitives.md
```
。
若涉及LLM工作流、规划或通过Effect AI使用工具，请打开
```
references/ai.md
```
。
若涉及受包大小限制的运行时，请打开
```
references/micro.md
```
。
若涉及从Promise/async迁移，请打开
```
references/migration-async.md
```
。
若需要版本控制或签名变更，请打开
```
references/versioning.md
```
。
若遇到常见陷阱或运行时错误，请打开
```
references/troubleshooting.md
```
。
若需要结果检查或调试，请打开
```
references/exit-cause.md
```
。
若需要从
```
llms.txt
```
获取文档到指南的映射，请打开
```
references/docs-index.md
```
。

Core Workflow

核心工作流

Clarify boundaries and IO; keep core logic as
```
Effect
```
values.
Choose style: use pipelines for simple composition; use
```
Effect.gen
```
for sequential logic.
Model errors explicitly: type expected errors; treat defects as unexpected failures.
Model dependencies with services, tags, and layers; keep interfaces clean of construction concerns.
Manage resource lifecycles with
```
Scope
```
when opening/closing resources.
Provide the environment via layers and run effects only at the program edge.
For platform/infra code, keep side effects in dedicated adapters and expose typed services to domain code.
For agent tasks, include a concise rationale for error, concurrency, and runtime choices.

明确边界与IO；将核心逻辑保持为
```
Effect
```
值。
选择合适的风格：简单组合使用管道；顺序逻辑使用
```
Effect.gen
```
。
显式建模错误：为预期错误添加类型；将缺陷视为意外故障。
使用服务、标签和Layer建模依赖项；保持接口与构建逻辑分离。
当打开/关闭资源时，使用
```
Scope
```
管理资源生命周期。
通过Layer提供环境，仅在程序边缘运行Effect。
对于平台/基础设施代码，将副作用放在专用适配器中，并向领域代码暴露类型化服务。
对于Agent任务，简要说明错误、并发和运行时选择的理由。

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.

展示导入语句和最小可运行示例。
优先使用桶导入（
```
from "effect"
```
/
```
from "@effect/platform"
```
）而非深层模块路径。
当函数式组合更清晰时，使用
```
effect
```
中的
```
pipe
```
。
明确展示依赖图（服务、Layer、上下文标签）。
包含错误通道类型，并区分预期错误与缺陷。
避免在库内部运行Effect；在入口点或测试中展示运行时用法。
优先选择与当前Effect主版本兼容的可编译示例。

Agent Quality Checklist

Agent质量检查清单

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.

当有助于设计决策时，声明目标类型为
```
Effect<A, E, R>
```
。
明确区分预期错误（
```
E
```
）与缺陷。
指出Layer的提供位置和
```
run*
```
的调用位置。
对于并发代码，说明有界/无界行为以及关闭策略。
对于边界解码，展示Schema的用法以及故障处理位置。
对于测试，记录所提供的测试服务（
```
TestContext
```
、
```
TestClock
```
、实时覆盖）。
若对文档有疑问，在最终确定API前查阅
```
references/docs-index.md
```
和源文档。

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.

从
```
references/docs-index.md
```
开始快速选择相关指南。

对于大多数代码任务，默认使用

references/core-usage.md

、

references/error-management.md

和

references/dependency-management.md

。

对于边界与集成工作，使用平台/运行时参考资料（
```
references/platform-primitives.md
```
、
```
references/runtime-execution.md
```
）。

对于验证与调试，使用测试/诊断参考资料（

references/testing.md

、

references/testing-stack.md

、

references/troubleshooting.md

）。",