effect

Effect

在任务涵盖的整个应用代码中使用 Effect。将 Promise 应用包在一个 Effect 中，并不算完整采用。

已验证的参考快照为 [email protected]（首个稳定的 v4 版本、npm latest、LTS）。更改依赖前，请检查已安装的版本。不要混用 v3 和 v4 API。仍在使用 4.0.0-rc.* / beta.* 的项目，必须按照 migration.md 应用 RC → 4.0 升级（导入路径和若干名称已更改）。

必须遵循的采用策略

• 将用例、服务方法、I/O、预期失败、资源所有权和并发工作保留在 Effect 中。
• 编写自定义辅助函数或添加功能重叠的库之前，先选择匹配的 Effect 能力。请参阅下方索引。
• 应用自有的验证和编解码使用 Effect Schema；依赖使用 Context 和 Layer；清理使用 Scope。
• 使用 Effect 的调度、并发、状态、配置和可观测性能力，不要为相同职责并行构建自定义系统。
• 将 Promise、回调、框架和供应商 API 保留在具名适配器中。只在入口和出口各转换一次。
• 现有 Elysia 路由可以返回 Promise。其处理程序委托给 Effect 用例；业务逻辑留在处理程序之外。
• 不要在领域服务中调用运行时运行器，让 Effect 看起来像 Promise API。
• 保持纯计算和普通 TypeScript 数据简单。除非它们会失败或执行副作用，否则无需包装在 Effect 中。
• 优先使用 Effect 标准库，而非新增重复工具。不要机械地替换清晰的语言运算符或原生数据结构。
• 遵循请求的范围。对每个涉及的用例进行端到端转换；不要启动无关的全仓库迁移。
• 记录仍然存在的非 Effect 边界及其具体限制。仅凭便利性不足以采用第二套应用架构。

在实现、审查或迁移混合代码库时，请阅读 adoption-boundaries.md。

能力索引

选择实现前，请先使用此索引。链接的目录涵盖此快照中的所有公共模块命名空间和公共 monorepo 包。 这是能力／模块索引，并非所有函数的列表。请在已安装的声明中确认签名。标记为 unstable 的区域具有 @stability unstable（可能在次要版本中发生破坏性变更），即使其导入路径中没有 unstable 段。

职责	Effect 能力
用例、类型化失败、恢复	Effect.fn、Effect.gen、Cause、Exit、Result、Option、Match
依赖、应用生命周期	Context、Layer、ManagedRuntime、Scope、LayerMap、LayerRef
验证、编解码器、领域类型、派生格式	Schema、Brand、Data、StandardSchema、JsonSchema、Optic；不稳定的 schema JIT/AOT 编译器
配置、机密、时间、大小、随机性	Config（PascalCase 构造器）、ConfigProvider、Redacted、Clock、DateTime、Duration、ByteSize、Random
重试、重复、超时、回退	Schedule、Cron、Effect 超时／重试、ExecutionPlan
并发、取消、同步	Fiber、Fiber 集合、Deferred、Latch、Semaphore、PartitionedSemaphore
共享状态和事务状态	Ref、SynchronizedRef、SubscriptionRef、ScopedRef、Effect.tx、所有 Tx* 模块
流处理和背压	Stream、Sink、Queue、PubSub；底层的 Channel、Pull、Take、ChannelSchema
缓存、批处理、可复用资源	Cache、ScopedCache、Request、RequestResolver、Pool、Resource、RcRef、RcMap
集合、文本、数字、相等性、算法	Array/Chunk/Record/Hash 集合、Graph、Trie、HashRing、BigDecimal、基本类型和协议模块
文件、路径、终端、加密	FileSystem、Path、Stdio、Terminal、Crypto、平台实现
日志、追踪、指标、诊断	Logger、LogLevel、Tracer、Metric、ErrorReporter；不稳定的 effect/observability、effect/devtools
HTTP、类型化 API、套接字、地址、RPC	不稳定的 effect/http、effect/http-api、effect/socket、effect/net、effect/rpc
数据库、模型、迁移	不稳定的 effect/sql、effect/schema；SQL 驱动包
持久化、速率限制、事件溯源	不稳定的 effect/persistence、effect/eventlog
AI、工具、MCP、嵌入、结构化决策	不稳定的 effect/ai（包括 Decision／DecisionModel）；提供方包
UI 状态、失效、数据水合	不稳定的 effect/reactivity；React/Solid/Vue 绑定
命令、子进程、工作池	不稳定的 effect/cli、effect/process、effect/workers
分布式实体、持久化工作	不稳定的 effect/cluster、effect/workflow
字节和线路格式	effect/encoding：Base64、Base64Url、Hex（稳定）；NDJSON、SSE、YAML、TOML、INI、SchemaBinary（不稳定）。MessagePack 已移除
测试、属性检查、生成的文档／客户端	effect/testing、不稳定的 Arbitrary、@effect/vitest、docgen/doctest/OpenAPI 工具

完整清单：核心和测试、所有子路径区域、所有公共包。

工作流

1. 检查本地 Effect 情况：effect / @effect/* 的版本、导入方式（from "effect" 还是 effect/Effect）、运行时（CLI、HTTP、worker、浏览器、测试），以及是否已使用 layers/config/platform。
2. 优先在 .temp/effect 下检出与已安装版本标签一致的 Effect-TS/effect 本地仓库（例如 [email protected]）。Effect-TS/effect-smol 已归档；v4 位于 Effect-TS/effect（main），v3 位于分支 v3。浏览源代码、LLMS.md、MIGRATION.md、migration/*、packages/effect/SCHEMA.md 和 ai-docs/。详情见：source-map.md。
3. 如果已安装版本与快照不同，或任务要求使用最新 API，则刷新文档。先查阅库文档，再检查已安装的 .d.ts。
4. 按关注点选择文档：
   • 安装、Effect.fn/gen、错误、fork、运行、Config → setup-core.md
   • 服务、layers、scopes、ManagedRuntime、Layer.launch → services-layers-runtime.md
   • 完整的稳定模块目录（各模块的用途）→ modules-stable.md
   • Stream、Queue/PubSub、fiber、类似 STM 的 Tx*、缓存、请求 → concurrency.md
   • Schema v4 → schema-v4.md
   • 子路径领域（effect/http、effect/sql、effect/ai，等等）→ modules-unstable.md
   • @effect/platform-*、sql-*、ai-*、atom-*、OTel、工具 → ecosystem.md
   • @effect/vitest → vitest-testing.md
   • v3 → v4，以及 v4 RC → 4.0 → migration.md
5. 在保留项目兼容惯例的前提下，落实所需的采用策略：匹配已安装版本、保持框架边界精简、显式组合 layers；将标记为 @stability unstable 的领域（effect/http、effect/sql、effect/ai，等等）视为可能在次要版本中发生破坏性变更，并将标记为 @stability experimental 的 API 视为可能在补丁版本中发生变化。

编码风格（规范）

摘自 Effect 自带的 LLMS.md / ai-docs：

• 内联 Effect 代码使用 Effect.gen。可复用的有副作用函数在追踪 span 有用时使用 Effect.fn("name")；对于不适合作为追踪边界的库代码和热点路径，使用 Effect.fnUntraced。不要编写仅包装并返回 Effect.gen 的普通函数；不要对 Effect.fn 的结果使用 .pipe。
• 领域错误：使用 Schema.TaggedError。失败时始终使用 return yield*，以便 TypeScript 执行类型收窄。
• 服务：使用 Context.Service，标识符类似 "myapp/db/Database"，使用 Database.of({ ... }) 实现，并附加 static readonly layer。除非是单行用法，否则优先使用 yield* Service，而非 Service.use。
• 不可信数据：使用 Schema，而非临时谓词。对于 isString / isObject / 组合，使用 Predicate；不要自行编写这些辅助函数。
• Effect 程序中的日期/时间：使用 DateTime + Clock，不要直接使用 Date.now()。
• 可观测性：在 core 中使用日志/追踪/指标；新项目优先使用 effect/observability OTLP。需要使用现有 OTel SDK 时，使用 @effect/opentelemetry。
• 进程入口：使用 NodeRuntime.runMain / BunRuntime.runMain（BunRuntime 是共用的 Node runner）、DenoRuntime / BrowserRuntime，或 Layer.launch。优先使用这些方式，而非 Runtime.makeRunMain。Cloudflare：没有 platform 包 — 使用 Fetch + SQL D1/DO 驱动。
• 优先使用 Stream/Sink，而非 Channel；根据 concurrency.md 中的说明，在 Schema 与 SchemaAST 之间、Cache、ScopedCache、Pool 与 RcMap 之间选择合适的方案。

判断

• 将 v4 单体仓库集成包与 effect 对齐到同一版本。独立工具包需根据各自的对等依赖进行检查。
• TypeScript 5.9+（Effect 的 TS 工具链建议使用 7）。strict: true。通常需要 Node 18+；部分 SQL 驱动需要 Node 22.16+。
• 4.0 中的 Config 构造器使用 PascalCase（如 Config.String、Config.Int、Config.Redacted、Config.URL 等）；Config.mapOrFail 已改为 Config.mapEffect。
• v4 代码中不得使用 v3 API：Context.Tag / GenericTag、Effect.Tag / Effect.Service、Either、FiberRef、Effect.catchAll、Effect.fork（改用 forkChild）、Effect.async（改用 callback）。
• 除非设置 { local: true } 或使用 Layer.fresh，否则 Layer 会跨 Effect.provide 调用进行记忆化。
• Runtime<R> 已移除。使用 Effect.run* / run*With(context) 或 ManagedRuntime 运行。
• Ref / Deferred / Fiber 不是可 yield 的 Effect——请使用 Ref.get、Deferred.await、Fiber.join。
• 优先使用类型化失败，而非 throw/die。缺陷属于程序员错误。
• 在边界处明确区分 Schema 的 Encoded 与 Type。
• 测试：使用 @effect/vitest@4 + vitest@^5（对等依赖为 >=5 <6）。优先使用 it.effect（已设定作用域并启用 TestClock；不要再用 Effect.scoped 包裹）。从 effect/testing 导入 TestClock。it.effect 会抑制日志；it.live 不会。
• 不要使用：effect/unstable/* 导入（已在 4.0 移除）/effect/Encoding/effect/testing/FastCheck/小写的 Config.string/catchAll/fork/forkDaemon/Context.Tag/Effect.Service/.Default/Either/FiberRef/Date.now/gen 中的 try/catch/用于 ISO 字符串的 Schema.Date/Union(A,B)/it.effect 搭配额外的 Effect.scoped。

模块路由（速查）

需求	使用
工作流、错误、并发	Effect、Cause、Exit、Result、Fiber
依赖注入	Context、Layer、ManagedRuntime
配置	Config、ConfigProvider
验证 / 领域类型	Schema（+ Schema.Class / TaggedError）
时间	Clock、Duration、DateTime、Cron、Schedule
集合	Array、Chunk、HashMap、HashSet、Record、Option
一个生产者，多个消费者	PubSub
工作队列	Queue
拉取式流	Stream / Sink / Channel（底层）
原子多引用更新	Effect.tx + TxRef / TxQueue / …
HTTP 客户端/服务端	effect/http + @effect/platform-*
Schema 优先的 HTTP API	effect/http-api
SQL	effect/sql + @effect/sql-*
LLM / 工具	effect/ai + @effect/ai-*
测试 / 属性检查	@effect/vitest、effect/testing、Arbitrary

每个根模块： modules-stable.md。每个子路径领域： modules-unstable.md。

验证

• 对 Effect<A, E, R>、Layer、Schema 的编码侧/类型侧以及已安装的 API 名称进行类型检查。
• 检查所有涉及的用例，排查隐藏的 Promise、运行时调用、未托管资源和重复基础设施。
• 相关行为发生变化时，测试适配器错误映射、取消、请求清理和应用关闭。
• 说明合理的非 Effect 边界以及仍待完成的迁移工作；仍有缺口时，不要声称已完成全面采用。
• @effect/vitest：使用 it.effect、TestClock、Exit/Result；需要隔离时，在每个测试中使用 Effect.provide。
• Schema：测试有效/无效输入、默认值、多余键、类、带标签的错误和 JSON Schema。
• 迁移扫描：v3 导入、Either、FiberRef、旧版 catch/fork/runtime/Schema API；RC 遗留项（effect/unstable/、effect/Encoding、FastCheck、小写的 Config.*、旧版 Schema.is* 检查名称）。