跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

effect

Apply Effect v4 conventions for services, layers, tagged errors, boundary runners, resources, retries, deadlines, HTTP, and tests. Use when writing or reviewing TypeScript that imports effect, adds a service or error class, chooses where to run a program, bounds external I/O, or tests Effect code.

jpoehnelt · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add jpoehnelt/skills --skill effect

技能说明


name: effect description: Apply Effect v4 conventions for services, layers, tagged errors, boundary runners, resources, retries, deadlines, HTTP, and tests. Use when writing or reviewing TypeScript that imports effect, adds a service or error class, chooses where to run a program, bounds external I/O, or tests Effect code.

Effect v4

Assumes Effect v4 (the effect@4.0.x line, including its release candidates). Effect 3 differs in names and modules (Context.Tag, Effect.catchAll, @effect/platform); do not mix the two. Read the installed version before using an API you have not seen in the repo, and follow the repo's AGENTS.md where it differs from this skill: a repo rule or a documented exception wins.

Repo facts (from AGENTS.md): pinned Effect version and how bumps land, import policy (deep imports, effect/unstable/* barrels), boundary runners and the shared ManagedRuntime, the house error file, Effect lint gates, test runner and helpers, check and test commands.

Boundaries

A boundary is where a Promise or process exit is the contract: an HTTP or route handler, a framework load or action, a Durable Object method, a queue or workflow step body, an extension or CLI entrypoint. Everything else returns an Effect under its own name and composes with yield*.

  • Run programs only at boundaries, through the repo's runner and one ManagedRuntime per process (NodeRuntime.runMain for Node entrypoints). No Effect.runPromise/runSync/runFork in domain code outside tests.
  • No fooEffect twin, no Promise wrapper lifted back with Effect.promise, no runner's Promise re-entered as an Effect.
  • Browser code may import pure modules (Schema, Option, Data, Result) but never runs a program that needs services.
  • Deep imports (import * as Effect from "effect/Effect") unless the repo says otherwise. Keep every package on the same exact Effect version; bump it in its own change.

Errors

  • One class per expected failure, owned by the package that raises it. Schema.TaggedError when the error crosses a serialization boundary (wire, RPC, journal); Data.TaggedError is fine in-process if the repo allows it. Type cause as Schema.Defect().
  • Class name, _tag, wire code, and catchTag argument are one identifier, unique across everything a consumer can see. The compiler cannot catch a duplicate tag; use the repo's check if it has one.
  • Derive message on the class; never author it at the call site.
class OrderNotFound extends Schema.TaggedError<OrderNotFound>()("OrderNotFound", {
  id: Schema.String,
}) {
  override get message() {
    return `order ${this.id} not found`;
  }
}
const load = Effect.fn("loadOrder")(function* (id: string) {
  const row = yield* findOrder(id);
  if (!row) return yield* new OrderNotFound({ id });
  return row;
});
  • Narrow with Effect.catchTag/catchTags, never by comparing a code or message string.
  • Lift a Promise API with Effect.tryPromise({ try, catch: (cause) => new SpecificError({ cause }) }). Never a zero-arg catch, never one generic catch-all class. An unmapped throw stays a defect.
  • Decode an error of unknown shape (RPC envelope, stored JSON, step failure) with a Schema.Union of the classes that operation admits, and derive the type from that schema. Never guess a class.
  • The public wire shape is an explicit projection ({ code, message } plus any public fields). Never encode the error class itself: that emits name, message, and nested cause.
  • Defects (bugs, missing config, broken bindings, failed setup) stay defects. Do not wrap setup or pure factories in Effect.try, and do not Effect.catchDefect/catchCause them into a domain error. The boundary runner reports and sanitizes them.
  • Retry policy lives where the retry happens (a while guard naming tags); errors carry no retryable flag.

Services and resources

  • A service is a Context.Service class with a concrete shape (class Db extends Context.Service<Db, DbShape>()("Db") {}). Dependencies travel in R and are supplied by Layer at the composition root. Tags expose shapes, not fallible Effects that produce shapes.
  • No deps = liveDeps parameter bags or module singletons. Build clients, pools, and connections in a scoped layer with Effect.acquireRelease so they close on shutdown and interruption.
  • On serverless runtimes (Workers), request-scoped I/O never lives in a memoized layer.
  • Read config with Config inside the layer that needs it; missing required config is a startup defect.

Functional core

  • Pure calculation (scoring, state transitions, diffing, decoding) stays synchronous and outside Effect.gen. Do not wrap a pure decision in an Effect.
  • Inside programs read time and randomness through Clock and Random, never Date.now(), new Date(), Math.random(), or ambient crypto.randomUUID(). In durable workflows, read time through the workflow's journaled step before branching.
  • Brand entity IDs at ingress with Schema.brand (or Brand.nominal outside schemas). Use Data.Class for in-memory equality; keep wire and journal values plain JSON.

State machines

Effect v4 has no state-machine module. Follow eng-state-machine for the design; this is how its parts map to Effect.

  • decide is plain TypeScript with no Effect, Clock, or service. If the repo provides a machine kernel (see its repo facts), use that kernel's decide. Otherwise match on both dimensions so a missing (state, command) pair is a type error: an outer Match.exhaustive over the state union with an inner one over the Schema.TaggedUnion of commands, or one match over a union of pairs. Matching commands alone only proves every command has a handler.
  • Decode the stored status at the boundary with Schema.Literals([...states]), so an unknown value never reaches decide, unless the kernel's decide already rejects unknown states as data.
  • decide returns a rejection as data. The write turns it into the owning p
阅读完整来源 ↗