effect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Effect

Use this skill when work touches Effect v4 beta usage, service/layer architecture, runtime entrypoints, Schema v4, platform modules, testing, or migrations from Effect v3.

当你的工作涉及Effect v4 beta使用、服务/层架构、运行时入口点、Schema v4、平台模块、测试或从Effect v3迁移时，可使用此技能。

Workflow

工作流程

Inspect the local Effect surface before changing code:
- Package versions for
```
effect
```
  ,
```
@effect/*
```
  , TypeScript, runtime platform packages, test libraries, and adapters.
- Imports: root
```
effect
```
  , direct modules like
```
effect/Effect
```
  ,
```
effect/Schema
```
  ,
```
effect/unstable/*
```
  , platform packages, or old v3 packages.
- Runtime boundary: CLI, HTTP handler, worker, server, browser, test, library, or framework-managed entrypoint.
- Dependency shape: services, layers, config providers, platform layers, managed runtimes, and scope ownership.
Clone
```
Effect-TS/effect-smol
```
into
```
.temp/effect-smol
```
(if missing) and always browse that checkout when referencing Effect v4 code — APIs, migration guides, package READMEs, and tests. Do not rely on memory or stale docs alone. Details: source-map.md.
Refresh current docs whenever the task asks for latest behavior or the local beta version is different. Start from source-map.md.
For install/version, core Effect usage, generator style, typed errors, async interop, config, and runtime boundaries, use setup-core.md.
For services,
```
Context.Service
```
, references, layers, memoization, scopes, and
```
ManagedRuntime
```
, use services-layers-runtime.md.
For Schema v4 shapes, validation, classes, tagged errors, transformations, codecs, serialization, and JSON Schema generation, use schema-v4.md.
For
```
@effect/vitest
```
(runners, TestClock, layers, flaky/live, good/bad patterns), use vitest-testing.md.
For v3 to v4 migration, unstable modules, and HTTP/platform packages, use migration-platform-testing.md.
Implement in the existing project style:
- Match the installed beta version and local import style.
- Prefer explicit service and layer composition over hidden globals.
- Keep framework/process edges thin; push business logic into Effects, services, and layers.
- Treat
```
effect/unstable/*
```
  APIs as beta-plus-unstable. Check installed declarations before using or recommending them.

在修改代码前检查本地Effect的相关情况：
- 包版本：
```
effect
```
  、
```
@effect/*
```
  、TypeScript、运行时平台包、测试库和适配器的版本。
- 导入情况：根目录
```
effect
```
  、直接模块如
```
effect/Effect
```
  、
```
effect/Schema
```
  、
```
effect/unstable/*
```
  、平台包或旧版v3包。
- 运行时边界：CLI、HTTP处理器、工作线程、服务器、浏览器、测试、库或框架管理的入口点。
- 依赖形态：服务、层、配置提供器、平台层、托管运行时和作用域归属。
将
```
Effect-TS/effect-smol
```
克隆到
```
.temp/effect-smol
```
目录（若不存在），并且在查阅Effect v4代码（包括API、迁移指南、包README和测试）时，务必查看该克隆版本。不要仅依赖记忆或过时文档。详情：source-map.md。
当任务要求最新行为或本地beta版本不同时，刷新最新文档。从source-map.md开始。
关于安装/版本、核心Effect使用、生成器风格、类型化错误、异步互操作、配置和运行时边界，请参考setup-core.md。
关于服务、
```
Context.Service
```
、引用、层、 memoization、作用域和
```
ManagedRuntime
```
，请参考services-layers-runtime.md。
关于Schema v4的形态、验证、类、标记错误、转换、编解码器、序列化和JSON Schema生成，请参考schema-v4.md。
关于
```
@effect/vitest
```
（运行器、TestClock、层、不稳定/实时测试、优劣模式），请参考vitest-testing.md。
关于v3到v4的迁移、不稳定模块和HTTP/平台包，请参考migration-platform-testing.md。
按照现有项目风格实现：
- 匹配已安装的beta版本和本地导入风格。
- 优先选择显式的服务和层组合，而非隐藏的全局变量。
- 保持框架/进程边缘简洁；将业务逻辑推入Effects、服务和层中。
- 将
```
effect/unstable/*
```
  API视为beta加不稳定版本。在使用或推荐前检查已安装的声明文件。

Effect Judgment

Effect使用判断

Effect v4 is beta. Be honest about API drift and verify local declarations before making broad changes.

Use

Context.Service

for v4 services. Do not introduce v3

Context.Tag

Context.GenericTag

Effect.Tag

, or

Effect.Service

patterns in v4 code.

Prefer
```
yield* Service
```
inside
```
Effect.gen
```
for service access. Use
```
Service.use
```
and
```
useSync
```
only for small, local one-liners.

Define layers explicitly with

Layer.succeed

Layer.effect

, or

Layer.effectDiscard

; wire dependencies with

Layer.provide

and

Layer.provideMerge

Compose and provide layers once when possible. Use
```
Layer.fresh
```
or
```
Effect.provide(..., { local: true })
```
only for intentional isolation.
Use
```
ManagedRuntime.make(layer)
```
for repeated JS entrypoint runs against shared services, and dispose it when done.
Use
```
Effect.runPromise
```
,
```
runPromiseExit
```
,
```
runFork
```
, or their
```
With
```
variants only at application edges.
Inside
```
Effect.gen
```
,
```
yield*
```
works with Yieldable values. Outside generators, convert non-Effect Yieldables explicitly or use module functions such as
```
Ref.get
```
,
```
Deferred.await
```
, and
```
Fiber.join
```
.
Prefer typed failures and tagged error classes over throwing. Use defects only for unrecoverable programmer errors.
Keep Schema v4 encode/decode direction visible at boundaries; do not assume decoded
```
Type
```
and encoded input are the same.
For tests: install v4
```
@effect/vitest@beta
```
(→
```
4.0.0-beta.x
```
; never bare/
```
latest
```
→
```
0.30.x
```
v3). Prefer
```
it.effect
```
(already scoped + TestClock/TestConsole). Import
```
TestClock
```
from
```
effect/testing
```
. Do not use
```
it.scoped
```
/
```
it.scopedLive
```
for Effect Scope. Treat
```
layer()
```
as shared across tests unless you
```
Effect.provide
```
per test.

Effect v4处于beta阶段。对于API变化要诚实告知，在进行大范围修改前先验证本地声明文件。

v4服务使用

Context.Service

。不要在v4代码中引入v3的

Context.Tag

、

Context.GenericTag

、

Effect.Tag

或

Effect.Service

模式。

在
```
Effect.gen
```
内部优先使用
```
yield* Service
```
来访问服务。仅在小型本地单行代码中使用
```
Service.use
```
和
```
useSync
```
。

使用

Layer.succeed

、

Layer.effect

或

Layer.effectDiscard

显式定义层；使用

Layer.provide

和

Layer.provideMerge

连接依赖。

尽可能一次性组合并提供层。仅在需要刻意隔离时使用
```
Layer.fresh
```
或
```
Effect.provide(..., { local: true })
```
。
针对共享服务的重复JS入口点运行，使用
```
ManagedRuntime.make(layer)
```
，完成后销毁它。
仅在应用边缘使用
```
Effect.runPromise
```
、
```
runPromiseExit
```
、
```
runFork
```
或它们的
```
With
```
变体。
在
```
Effect.gen
```
内部，
```
yield*
```
可处理Yieldable值。在生成器外部，显式转换非Effect的Yieldable值，或使用模块函数如
```
Ref.get
```
、
```
Deferred.await
```
和
```
Fiber.join
```
。
优先使用类型化失败和标记错误类，而非抛出异常。仅将缺陷用于不可恢复的程序员错误。
在边界处保持Schema v4的编码/解码方向可见；不要假设解码后的
```
Type
```
与编码输入相同。
测试相关：安装v4版本的
```
@effect/vitest@beta
```
（即
```
4.0.0-beta.x
```
；绝不要使用裸版本/
```
latest
```
对应的
```
0.30.x
```
v3版本）。优先使用
```
it.effect
```
（已包含作用域 + TestClock/TestConsole）。从
```
effect/testing
```
导入
```
TestClock
```
。不要将
```
it.scoped
```
/
```
it.scopedLive
```
用于Effect Scope。除非你在每个测试中使用
```
Effect.provide
```
，否则将
```
layer()
```
视为跨测试共享。

Verification

验证

Prefer the repo's existing checks. For meaningful Effect v4 work, include the relevant subset:

Typecheck for
```
Effect<A, E, R>
```
requirements, service availability, layer composition, Schema encoded/type sides, and beta API names.
Focused tests with
```
@effect/vitest@beta
```
(
```
it.effect
```
, TestClock, scoped resources, typed Exit/Result failures). Use per-test
```
Effect.provide
```
when isolation matters; treat shared
```
layer()
```
as suite-scoped.
Runtime smoke at JS/framework edges where Effects are run or managed runtimes are disposed.
Schema decode/encode tests for valid input, invalid input, defaults, excess properties, transformations, classes, tagged errors, and generated JSON Schema.
Migration scans for v3-only APIs, old package imports, old catch/fork names, old runtime patterns,
```
FiberRef
```
,
```
Either
```
, and removed Schema APIs.

优先使用仓库现有的检查机制。对于重要的Effect v4工作，需包含以下相关子集：

类型检查：验证
```
Effect<A, E, R>
```
要求、服务可用性、层组合、Schema编码/类型侧以及beta API名称。
聚焦测试：使用
```
@effect/vitest@beta
```
（
```
it.effect
```
、TestClock、作用域资源、类型化Exit/Result失败）。当需要隔离时，在每个测试中使用
```
Effect.provide
```
；将共享的
```
layer()
```
视为套件作用域。
运行时冒烟测试：在JS/框架边缘处测试Effects的运行或托管运行时的销毁。
Schema编码/解码测试：针对有效输入、无效输入、默认值、多余属性、转换、类、标记错误和生成的JSON Schema进行测试。
迁移扫描：检查仅v3可用的API、旧包导入、旧catch/fork名称、旧运行时模式、
```
FiberRef
```
、
```
Either
```
以及已移除的Schema API。