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
ManagedRuntimeper process (NodeRuntime.runMainfor Node entrypoints). NoEffect.runPromise/runSync/runForkin domain code outside tests. - No
fooEffecttwin, no Promise wrapper lifted back withEffect.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.TaggedErrorwhen the error crosses a serialization boundary (wire, RPC, journal);Data.TaggedErroris fine in-process if the repo allows it. TypecauseasSchema.Defect(). - Class name,
_tag, wirecode, andcatchTagargument 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
messageon 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 acodeor message string. - Lift a Promise API with
Effect.tryPromise({ try, catch: (cause) => new SpecificError({ cause }) }). Never a zero-argcatch, 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.Unionof 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 emitsname,message, and nestedcause. - Defects (bugs, missing config, broken bindings, failed setup) stay defects. Do not wrap setup or pure factories in
Effect.try, and do notEffect.catchDefect/catchCausethem into a domain error. The boundary runner reports and sanitizes them. - Retry policy lives where the retry happens (a
whileguard naming tags); errors carry no retryable flag.
Services and resources
- A service is a
Context.Serviceclass with a concrete shape (class Db extends Context.Service<Db, DbShape>()("Db") {}). Dependencies travel inRand are supplied byLayerat the composition root. Tags expose shapes, not fallible Effects that produce shapes. - No
deps = liveDepsparameter bags or module singletons. Build clients, pools, and connections in a scoped layer withEffect.acquireReleaseso they close on shutdown and interruption. - On serverless runtimes (Workers), request-scoped I/O never lives in a memoized layer.
- Read config with
Configinside 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
ClockandRandom, neverDate.now(),new Date(),Math.random(), or ambientcrypto.randomUUID(). In durable workflows, read time through the workflow's journaled step before branching. - Brand entity IDs at ingress with
Schema.brand(orBrand.nominaloutside schemas). UseData.Classfor 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.
decideis plain TypeScript with noEffect,Clock, or service. If the repo provides a machine kernel (see its repo facts), use that kernel'sdecide. Otherwise match on both dimensions so a missing (state, command) pair is a type error: an outerMatch.exhaustiveover the state union with an inner one over theSchema.TaggedUnionof 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 reachesdecide, unless the kernel'sdecidealready rejects unknown states as data. decidereturns a rejection as data. The write turns it into the owning p