SuperAPI AI 工具集

humanlayer-effect-machine

编程与开发

查看项目

更新于 10-20 05:26

技能介绍

humanlayer-effect-machine 是 Effect 生态中的类型安全状态机库,导入路径为 @humanlayer/effect-machine。资料将其定位为使用 Schema 定义状态、事件并编写转移处理器的工具,内容按用途划分为 Schema、转移、副作用、测试、Actor、请求响应、生命周期、超时与 postpone、服务与 Layer 等主题。

用途上,它适合在 TypeScript 项目中以声明方式描述有限状态机:状态和事件本身就是 Schema,State({}) 与 Event({}) 会生成带构造函数的标签联合类型。空字段状态是普通值(如 S.Idle),非空状态是构造函数(如 S.Loading({ url }))。可通过 with 从现有状态挑选或覆盖字段,用 $is 做类型守卫、$match 做模式匹配。

主要能力包括:用 Machine.make 设置初始状态,用 .on 注册单状态或多状态来源的转移处理器,用 .onAny 处理任意状态的通配事件(具体 .on 优先),用 .reenter 重入同一状态,用 .final 标记终止状态。处理器可返回纯状态或 Effect<State>,需要回复时返回 Machine.reply。副作用方面,spawn 为状态作用域并在退出时自动取消,task 在 spawn 基础上自动把成功/失败映射为事件,background 作用于机器生命周期。服务依赖通过 Effect 的 Context/Layer 提供,转移处理器保持纯粹,I/O 放在状态副作用中并以事件回流。

使用方式上,Actor 通过 Machine.spawn 创建,返回的是未启动的冷 Actor,需要显式调用 actor.start 才启动事件循环,启动前发送的事件会排队;ActorSystem 的 spawn 则自动启动。ActorRef 提供 start、send、cast、call、ask、snapshot、changes、transitions、waitFor、sendAndWait、awaitFinal 及同步变体等 API。ask 要求事件使用 Event.reply 声明回复 Schema,处理器必须返回 Machine.reply,否则是类型错误;.onAny 处理器不能提供回复。超时采用 gen_statem 风格,进入状态时启动计时、退出时取消,支持由状态动态计算时长,reenter 会用新状态值重启计时。postpone 同样为 gen_statem 风格,状态变化时按 FIFO 排空缓冲事件并循环至稳定。

持久化与恢复:Machine.spawn 或 system.spawn 可传入 lifecycle 选项,recovery.resolve 在 actor.start 期间运行,可返回 Some 覆盖初始状态或 None 冷启动;durability.save 在每次提交转移后运行,可配 shouldSave 过滤。generation 为 0 表示冷启动,1 及以上表示监督重启。hydrate 优先于 recovery,设置后不再调用 resolve。Machine.replay 可折叠事件日志还原状态,replay 中 self.send/self.spawn 为无操作,spawn 副作用、background 副作用和超时不会运行,postpone 规则仍生效,遇到终止状态停止,未处理事件静默跳过。

测试方面提供 simulate(运行事件得到全部状态与最终状态)、assertPath、assertReaches、assertNeverReaches 以及可逐步操作的 createTestHarness。

适用场景为需要在 Effect 中构建强类型、可测试、带副作用与持久化状态机的应用,如加载流程、连接状态、带请求响应的 Actor 交互等。限制与注意事项:Machine.spawn 返回未启动 Actor 必须 start;服务实现需通过 Layer 提供;空状态与非空状态的构造方式不同;hydrate 会重新运行该状态下的 spawn 副作用;transitions 是观察性流,晚订阅会丢失边,不构成持久化保证;ask 仅接受声明回复 Schema 的事件,回复解码失败在运行时视为缺陷。安装命令、版本要求、许可证与性能数据暂未提供。