effect-v4

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Effect v4 (Beta) - Development & Migration

Effect v4 (Beta) - 开发与迁移

Overview

概述

Comprehensive guidance for Effect v4 development and migration from v3. This skill provides:

v4 Core Patterns - Guide to building new v4 code with ServiceMap, layers, generators, schema codecs
v3 → v4 Migration - Step-by-step migration guidance with API renames, behavior changes, and before/after examples

Status: Effect v4 is beta software under active development in effect-smol. The core programming model is stable, but

effect/unstable/*

modules may receive breaking changes in minor releases. For production use, review official v4 beta guidance and stability notes.

All bundled migration guides are sourced from the official effect-smol migration documentation.

本指南为Effect v4开发及从v3版本迁移提供全面指导，包含以下内容：

v4核心模式 - 指导如何使用ServiceMap、层、生成器、schema编解码器构建新的v4代码
v3 → v4迁移 - 分步迁移指导，包含API重命名、行为变更及前后对比示例

状态说明： Effect v4是effect-smol中正在积极开发的测试版软件。核心编程模型已稳定，但

effect/unstable/*

模块在小版本更新中可能会出现破坏性变更。若用于生产环境，请查阅官方v4测试版指南及稳定性说明。所有附带的迁移指南均源自官方effect-smol迁移文档。

Quick Triage

快速分类导航

Building v4 Code

构建v4代码

Core Effect types and combinators (Result, Option, Chunk, Duration):
```
references/core-usage.md
```
Broader data types (DateTime, BigDecimal, HashSet, Redacted):
```
references/data-types-advanced.md
```
Equality, Order, Hash, Equivalence semantics:
```
references/behavior-traits.md
```
Expected errors vs defects,
```
catch*
```
combinators:
```
references/error-management.md
```
Sandboxing, Cause inspection,
```
catchCause
```
:
```
references/error-tooling.md
```
Exit and Cause structure, result inspection:
```
references/exit-cause.md
```
Services and dependency injection (ServiceMap, layers):
```
references/dependency-management.md
```

Layer construction, memoization,

{ local: true }

references/layer-patterns.md

Resource lifecycles, Scope,

acquireRelease

references/resource-management.md

Running effects,
```
Runtime
```
removal, run boundaries:
```
references/runtime-execution.md
```

Fibers,

forkChild

forkDetach

, fork options:

references/concurrency.md

References (replaces FiberRef),

ServiceMap.Reference

references/concurrency-advanced.md

Schedules, repetition, spaced/fixed/exponential:
```
references/scheduling.md
```
Retries, backoff, schedule composition:
```
references/scheduling-retry.md
```
Streams, queues, PubSub, STM:
```
references/streams-queues-stm.md
```
HTTP clients and external APIs:
```
references/http-client.md
```
HTTP servers and API definitions:
```
references/http-server.md
```
Request batching and data loaders:
```
references/request-resolver.md
```
Caching and memoization:
```
references/caching.md
```
Configuration and config providers:
```
references/configuration.md
```
Advanced config, redaction:
```
references/configuration-advanced.md
```
Logs, metrics, tracing:
```
references/observability.md
```
Logger/metrics/tracing setups and exporters:
```
references/observability-examples.md
```
Wiring log/metric/trace layers:
```
references/observability-wiring.md
```
Sequential workflows and yieldable patterns:
```
references/generators.md
```
Schema validation, parsing, encoding (codecs):
```
references/schema.md
```
Stream consumption with reducers (Sink):
```
references/sink.md
```
Deterministic time in tests (TestClock):
```
references/testing.md
```
Broader testing services and test layers:
```
references/testing-stack.md
```
Command, FileSystem, Path, Terminal, KeyValueStore:
```
references/platform-primitives.md
```
LLM workflows, planning, tool use via Effect AI:
```
references/ai.md
```
Bundle-size constrained runtimes (Micro):
```
references/micro.md
```
Migrating from Promise/async:
```
references/migration-async.md
```
Common pitfalls and runtime errors:
```
references/troubleshooting.md
```
Docs-to-guide map from
```
llms.txt
```
:
```
references/docs-index.md
```

核心Effect类型与组合子（Result、Option、Chunk、Duration）：
```
references/core-usage.md
```
进阶数据类型（DateTime、BigDecimal、HashSet、Redacted）：
```
references/data-types-advanced.md
```
相等性、排序、哈希、等价语义：
```
references/behavior-traits.md
```
预期错误与缺陷、
```
catch*
```
组合子：
```
references/error-management.md
```
沙箱机制、Cause检查、
```
catchCause
```
：
```
references/error-tooling.md
```
Exit与Cause结构、结果检查：
```
references/exit-cause.md
```
服务与依赖注入（ServiceMap、层）：
```
references/dependency-management.md
```

层构建、记忆化、

{ local: true }

：

references/layer-patterns.md

资源生命周期、Scope、

acquireRelease

：

references/resource-management.md

运行Effect、
```
Runtime
```
移除、运行边界：
```
references/runtime-execution.md
```

纤程、

forkChild

、

forkDetach

、fork选项：

references/concurrency.md

引用（替代FiberRef）、

ServiceMap.Reference

：

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
```
日志/指标/链路追踪层的集成：
```
references/observability-wiring.md
```
顺序工作流与可yield模式：
```
references/generators.md
```
Schema验证、解析、编码（编解码器）：
```
references/schema.md
```
使用归约器（Sink）消费流：
```
references/sink.md
```
测试中的确定性时间（TestClock）：
```
references/testing.md
```
进阶测试服务与测试层：
```
references/testing-stack.md
```
命令、文件系统、路径、终端、键值存储：
```
references/platform-primitives.md
```
基于Effect AI的LLM工作流、规划、工具调用：
```
references/ai.md
```
受包大小限制的运行时（Micro）：
```
references/micro.md
```
从Promise/async迁移：
```
references/migration-async.md
```
常见陷阱与运行时错误：
```
references/troubleshooting.md
```
基于
```
llms.txt
```
的文档-指南映射：
```
references/docs-index.md
```

Migrating from v3

从v3版本迁移

Full migration overview, quick-reference table, ordered checklist:
```
references/migration.md
```
Runtime and run functions:
```
references/migration/runtime.md
```
Error handling and error channel changes:
```
references/migration/error-handling.md
```
Cause flattening and new structure:
```
references/migration/cause.md
```
Services and environment changes (Context.Tag → ServiceMap.Service):
```
references/migration/services.md
```
Fiber references and context locals:
```
references/migration/fiberref.md
```
Forking and fiber APIs (fork → forkChild, etc.):
```
references/migration/forking.md
```

Fiber keep-alive behavior changes:

references/migration/fiber-keep-alive.md

Scope and resource lifecycle patterns:
```
references/migration/scope.md
```

Layer memoization and Layer.fresh:

references/migration/layer-memoization.md

Generator and Effect.gen changes:
```
references/migration/generators.md
```
Yieldable protocol (non-Effect yieldables):
```
references/migration/yieldable.md
```
Equality and structural comparison:
```
references/migration/equality.md
```

完整迁移概述、速查表、有序检查清单：
```
references/migration.md
```
运行时与运行函数：
```
references/migration/runtime.md
```
错误处理与错误通道变更：
```
references/migration/error-handling.md
```
Cause扁平化与新结构：
```
references/migration/cause.md
```
服务与环境变更（Context.Tag → ServiceMap.Service）：
```
references/migration/services.md
```
纤程引用与上下文本地变量：
```
references/migration/fiberref.md
```
Fork与纤程API（fork → forkChild等）：
```
references/migration/forking.md
```

纤程保活行为变更：

references/migration/fiber-keep-alive.md

Scope与资源生命周期模式：
```
references/migration/scope.md
```

层记忆化与Layer.fresh：

references/migration/layer-memoization.md

生成器与Effect.gen变更：
```
references/migration/generators.md
```
可yield协议（非Effect类型的可yield值）：
```
references/migration/yieldable.md
```
相等性与结构比较：
```
references/migration/equality.md
```

Workflow

工作流程

Ask which v3 APIs or files are in scope and which failures or regressions to avoid.
Open only the relevant migration notes from
```
references/migration/
```
.
Produce a mapping of v3 to v4 APIs, including before/after code snippets.
Call out behavior changes, edge cases, and test updates needed.
Provide a short, ordered migration checklist tailored to the code in question.

询问需要处理的v3 API或文件范围，以及需要避免的错误或回归问题。
仅打开
```
references/migration/
```
下的相关迁移文档。
生成v3到v4 API的映射，包含前后代码示例。
指出行为变更、边缘情况及需要更新的测试内容。
根据目标代码提供简短的有序迁移检查清单。

Example Requests

示例请求

"Migrate this v3
```
Runtime
```
usage to v4 and explain the new run functions."
"Update our v3 error handling to v4 and show before/after examples."
"We use FiberRefs and forking; what needs to change in v4?"
"Explain the generator/yieldable changes and update this Effect.gen usage."
"Do we need to change any Scope or Layer memoization behavior in v4?"

"将这段v3的
```
Runtime
```
用法迁移到v4，并解释新的运行函数。"
"将我们的v3错误处理更新到v4，并展示前后示例。"
"我们使用FiberRef和forking；v4中需要做哪些变更？"
"解释生成器/可yield的变更，并更新这段Effect.gen用法。"
"v4中我们需要修改Scope或Layer记忆化的行为吗？"

References - v4 Core

参考文档 - v4核心

Comprehensive v4-specific guides (all updated for v4 APIs, no deprecated patterns):

```
references/core-usage.md
```
- Core Effect types and combinators (Result, Option, Chunk)
```
references/data-types-advanced.md
```
- DateTime, BigDecimal, HashSet, Redacted
```
references/behavior-traits.md
```
- Structural equality by default, Equal, Order, Hash

references/error-management.md

catch*

renames,

catchReason

catchEager

```
references/error-tooling.md
```
-
```
catchCause
```
, sandboxing, Cause inspection
```
references/exit-cause.md
```
- Flattened Cause structure, Reason iteration
```
references/dependency-management.md
```
- ServiceMap, services, layers

references/layer-patterns.md

- Cross-provide memoization,

{ local: true }

references/resource-management.md

Scope.provide

(was

Scope.extend

)

references/runtime-execution.md

Runtime<R>

removed, run* at the edge

references/concurrency.md

forkChild

forkDetach

, fork options, keep-alive

references/concurrency-advanced.md

ServiceMap.Reference

(was

FiberRef

)

```
references/scheduling.md
```
- Schedules and repetition
```
references/scheduling-retry.md
```
- Retries and backoff
```
references/streams-queues-stm.md
```
- Streams, queues, PubSub, STM
```
references/http-client.md
```
- HTTP clients
```
references/http-server.md
```
- HTTP servers
```
references/request-resolver.md
```
- Request batching
```
references/caching.md
```
- Caching and memoization
```
references/configuration.md
```
- Configuration
```
references/configuration-advanced.md
```
- Advanced config, redaction
```
references/observability.md
```
- Logs, metrics, tracing
```
references/observability-examples.md
```
- Concrete logger/metrics/tracing setups
```
references/observability-wiring.md
```
- Wiring observability layers
```
references/generators.md
```
- Effect.gen and yieldable patterns
```
references/schema.md
```
- Schema codecs (decode/encode)
```
references/sink.md
```
- Stream consumption with Sink
```
references/testing.md
```
- TestClock and deterministic time
```
references/testing-stack.md
```
- Test layer composition
```
references/platform-primitives.md
```
- Command, FileSystem, Path, Terminal
```
references/ai.md
```
- LLM workflows via Effect AI
```
references/micro.md
```
- Bundle-size constrained runtimes
```
references/migration-async.md
```
- Migrating from Promise/async
```
references/troubleshooting.md
```
- Common pitfalls
```
references/versioning.md
```
- Version guidance
```
references/docs-index.md
```
- Docs-to-guide routing map

全面的v4专属指南（均已针对v4 API更新，无已弃用模式）：

```
references/core-usage.md
```
- 核心Effect类型与组合子（Result、Option、Chunk）
```
references/data-types-advanced.md
```
- DateTime、BigDecimal、HashSet、Redacted
```
references/behavior-traits.md
```
- 默认结构相等性、Equal、Order、Hash

references/error-management.md

catch*

重命名、

catchReason

、

catchEager

```
references/error-tooling.md
```
-
```
catchCause
```
、沙箱机制、Cause检查
```
references/exit-cause.md
```
- 扁平化的Cause结构、Reason遍历
```
references/dependency-management.md
```
- ServiceMap、服务、层

references/layer-patterns.md

- 跨提供记忆化、

{ local: true }

references/resource-management.md

Scope.provide

（原

Scope.extend

）

references/runtime-execution.md

Runtime<R>

已移除，在边界处使用run*

references/concurrency.md

forkChild

forkDetach

、fork选项、保活机制

references/concurrency-advanced.md

ServiceMap.Reference

（原

FiberRef

）

```
references/scheduling.md
```
- 调度器与重复执行
```
references/scheduling-retry.md
```
- 重试与退避
```
references/streams-queues-stm.md
```
- 流、队列、PubSub、STM
```
references/http-client.md
```
- HTTP客户端
```
references/http-server.md
```
- HTTP服务器
```
references/request-resolver.md
```
- 请求批处理
```
references/caching.md
```
- 缓存与记忆化
```
references/configuration.md
```
- 配置
```
references/configuration-advanced.md
```
- 进阶配置、脱敏处理
```
references/observability.md
```
- 日志、指标、链路追踪
```
references/observability-examples.md
```
- 具体的日志/指标/链路追踪配置
```
references/observability-wiring.md
```
- 集成可观测性层
```
references/generators.md
```
- Effect.gen与可yield模式
```
references/schema.md
```
- Schema编解码器（解码/编码）
```
references/sink.md
```
- 使用Sink消费流
```
references/testing.md
```
- TestClock与确定性时间
```
references/testing-stack.md
```
- 测试层组合
```
references/platform-primitives.md
```
- 命令、文件系统、路径、终端
```
references/ai.md
```
- 基于Effect AI的LLM工作流
```
references/micro.md
```
- 受包大小限制的运行时
```
references/migration-async.md
```
- 从Promise/async迁移
```
references/troubleshooting.md
```
- 常见陷阱
```
references/versioning.md
```
- 版本指导
```
references/docs-index.md
```
- 文档-指南路由映射

References - v3 → v4 Migration

参考文档 - v3 → v4迁移

```
references/migration.md
```
- Start here: full overview, quick-reference table, ordered checklist
```
references/migration/cause.md
```
- Cause flattening and structure
```
references/migration/equality.md
```
- Equality and comparison changes
```
references/migration/error-handling.md
```
- Error channel and catch* renames

references/migration/fiber-keep-alive.md

- Fiber lifecycle changes

```
references/migration/fiberref.md
```
- FiberRef and References changes
```
references/migration/forking.md
```
- Fork, forkChild, forkDetach changes
```
references/migration/generators.md
```
- Effect.gen pattern updates

references/migration/layer-memoization.md

- Layer.fresh and memoization

```
references/migration/runtime.md
```
- Runtime and run* functions
```
references/migration/scope.md
```
- Scope and resource lifecycle
```
references/migration/services.md
```
- Context.Tag → ServiceMap.Service
```
references/migration/yieldable.md
```
- Yieldable protocol changes

```
references/migration.md
```
- 从这里开始：完整概述、速查表、有序检查清单
```
references/migration/cause.md
```
- Cause扁平化与结构
```
references/migration/equality.md
```
- 相等性与比较变更
```
references/migration/error-handling.md
```
- 错误通道与catch*重命名

references/migration/fiber-keep-alive.md

- 纤程生命周期变更

```
references/migration/fiberref.md
```
- FiberRef与引用变更
```
references/migration/forking.md
```
- Fork、forkChild、forkDetach变更
```
references/migration/generators.md
```
- Effect.gen模式更新

references/migration/layer-memoization.md

- Layer.fresh与记忆化

```
references/migration/runtime.md
```
- 运行时与run*函数
```
references/migration/scope.md
```
- Scope与资源生命周期
```
references/migration/services.md
```
- Context.Tag → ServiceMap.Service
```
references/migration/yieldable.md
```
- 可yield协议变更