Effect 4.0.5 里哪些模块仍是 unstable?

我在 effect@4.0.5 上扫描了 dist 里的 .d.ts:230 个模块整个都是 unstable,113 个是 stable,12 个是 mixed,11 个是 experimental,还有 3 个没有标签。

HTTP、RPC、SQL、AI、Workflow、Cluster、CLI、Atom、平台抽象和 OTLP 导出整体都是 unstable;核心运行时是 stable;少数 stable 模块里夹着个别 unstable 的声明。

Effect v4 现在用每个导出上的 @stability 标签标注稳定性,路径里不再有 effect/unstable/*,所以光看 import 看不出来,这个背景见 Effect v4 怎么标注 API 的稳定性?。下面是扫描得到的具体清单。

哪些模块整个都是 unstable?

按目录归并后是:

effect/ai/* (20), effect/cli/* (12), effect/cluster/* (39), effect/devtools/* (4),
effect/encoding/* (6), effect/eventlog/* (14), effect/http-api/* (13), effect/http/* (32),
effect/net/* (2), effect/observability/* (8), effect/persistence/* (7), effect/process/* (2),
effect/reactivity/* (8), effect/rpc/* (12), effect/schema/* (6), effect/socket/* (2),
effect/sql/* (9), effect/testing/* (3), effect/workers/* (4), effect/workflow/* (8)
单文件:Arbitrary, ByteSize, ChannelSchema, Crypto, ErrorReporter, ExecutionPlan, FileSystem,
Graph, HashRing, LayerMap, LayerRef, Newtype, PartitionedSemaphore, Path, PlatformError,
Stdio, Terminal, TxChunk, Version

对日常开发影响最大的几条:

  • FileSystem、Path、Terminal、Stdio 这些平台抽象是 unstable。
  • HTTP 客户端与服务端(effect/http)、effect/http-api、effect/rpc、effect/sql、effect/ai、effect/workflow、effect/cluster、effect/cli、前端用的 effect/reactivity(Atom)、effect/observability 的 OTLP 导出,全部是 unstable。
  • LayerMap、LayerRef 虽然名字像核心模块,但也是 unstable。

哪些核心模块是 stable?

Effect、Layer、Context、Stream、Schema、Schedule、Cache、Queue、PubSub、Pool、RcMap、Resource、ManagedRuntime 是 stable。

注意 Schema 在这里有两面:effect/Schema 整体是 stable,但 effect/schema/* 下的 6 个模块是整个 unstable 的,下一节还会看到 effect/Schema 内部也有 90 个 unstable 声明。

哪些 stable 模块里夹着 unstable 声明?

这类是 mixed:模块整体 stable,个别声明不是。脚本给出的清单:

effect/Config: 1 (ByteSize)
effect/ConfigProvider: 2 (fromDotEnv, fromDir)
effect/Effect: 2 (withExecutionPlan, withErrorReporting)
effect/Logger: 1 (toFile)
effect/RequestResolver: 1 (persisted)
effect/Schema: 90 (ByteSize, MacAddress, ... 一批网络与字节大小相关的 Schema)
effect/Stream: 2 (withExecutionPlan, limitBytes)
effect/TxQueue: 34   effect/TxPubSub: 3   effect/TxSubscriptionRef: 1 (changes)
effect/net/NetAddress: 128(绝大多数 unstable)

所以在 Effect 模块里用 Effect.withExecutionPlan 或 Effect.withErrorReporting,你依赖的仍然是 unstable 的声明,哪怕 import 来自一个 stable 模块。这也是只看模块层面不够的原因,要在声明层面检查,做法见 怎么让 Effect 语言服务对 unstable API 报警告?。

哪些是 experimental?

有 11 个 experimental 模块,主要是 effect/graphql/*,以及 net/AddressResolver、net/Dns、net/Host、socket/DatagramSocket。

这份清单有多可靠?

脚本按声明统计,不看 re-export;模块内同一名字的多个重载若标签不同,以最后一次出现为准,这是脚本的简化。想自己复现,脚本和用法见 怎么用脚本统计 Effect 里每个模块的稳定性?。

本文基于 effect 4.0.5,清单来自我在该版本上运行扫描脚本的输出。脚本只统计声明,不看 re-export,同名重载标签不同时以最后一次出现为准。其他版本的清单需要重新扫描。