Agent Skills: effect-ts

<version_info> <current_version>Effect 3.x (verified against effect 3.19.x)</current_version> <companions> <item>@effect/vitest 0.25.x — Effect-native test bindings (it.effect / it.scoped / it.live)</item> <item>vitest 3.2.x — underlying runner (expect still imported from vitest)</item> </companions> <api_stability> <item>Effect.Service, Layer.provide/provideMerge/merge/mergeAll, Effect.scoped, TestClock, and Schema.Struct are stable across the Effect 3.x line. Patterns below were confirmed against the official Effect documentation.</item> <item>Import everything from the single "effect" package (import { Effect, Layer, Schema, Ref } from "effect"); test bindings come from "@effect/vitest".</item> </api_stability> <caution> <item>Effect 2.x and pre-3.x tutorials predate Effect.Service and the current Schema module location (Schema moved into the core "effect" package). Do not mix guidance across major versions.</item> </caution> </version_info>

<service_definition> <description> Prefer one uniform way to declare services. Effect.Service is syntactic sugar over a tag plus a default Layer: it generates the tag from the identifier string, builds the implementation from a constructor (effect / scoped / sync / succeed), and exposes a .Default Layer. Reserve the manual Context.GenericTag + Layer.effect form for cases where a default implementation must not be assumed. </description>

  // The class value doubles as the tag; the string is the stable identifier.
  class Database extends Effect.Service<Database>()("app/Database", {
    // `effect` runs when the layer is built and returns the implementation.
    effect: Effect.gen(function* () {
      const config = yield* Config
      return {
        query: (sql: string) => Effect.succeed(`result of ${sql} @ ${config.url}`),
      } as const
    }),
    // Dependencies needed to BUILD this service.
    dependencies: [Config.Default],
  }) {}

  // Generated layers:
  //   Database.Default                 -> Layer<Database>            (deps baked in)
  //   Database.DefaultWithoutDependencies -> Layer<Database, never, Config> (deps external)
</example>
<notes>
  <item>Consumers write `const db = yield* Database` regardless of how the service was defined — migrating from Context.GenericTag to Effect.Service does not change call sites.</item>
  <item>Use a stable, namespaced identifier string (e.g. "app/Database"). It participates in tag identity.</item>
</notes>

  class Clock extends Context.Tag("app/Clock")<
    Clock,
    { readonly now: Effect.Effect<number> }
  >() {}

  const ClockLive = Layer.effect(
    Clock,
    Effect.sync(() => ({ now: Effect.sync(() => performance.now()) })),
  )
</example>
<notes>
  <item>Context.Tag makes the default implementation optional; Effect.Service requires one. Choose Context.Tag only when "no assumed implementation" is the point.</item>
</notes>

<decision_tree name="service_style"> <question>Does this service have one sensible runtime implementation owned by the app?</question> <if_yes>Use Effect.Service with effect/scoped constructor and dependencies.</if_yes> <if_no>Use Context.Tag + a separately provided Layer so callers choose the implementation.</if_no> </decision_tree> </service_definition>

<layer_composition> <description> Layers form a dependency graph. The discipline that avoids type errors and leaked requirements is: sequence dependent layers with provide / provideMerge, and reserve flat merge for genuinely independent layers. </description>

<decision_tree name="composition_operator"> <question>Does one layer depend on another?</question> <branch condition="Dependency, and the provider should stay hidden">Layer.provide</branch> <branch condition="Dependency, and the provider must remain in the final environment">Layer.provideMerge</branch> <branch condition="No dependency relationship (independent services)">Layer.merge / Layer.mergeAll</branch> </decision_tree> </layer_composition>

<escape_effect_late> <description> "Escape the Effect runtime as late as possible." Each Effect.runPromise / Effect.runSync crosses the boundary out of Effect: it forfeits typed errors, interruption, structured concurrency, and scheduling. Entering that boundary once per hot iteration (render frame, stream item, request) multiplies the cost and fragments error handling into many independent .catch() sites. </description>

<anti_pattern name="runtime_escape_in_hot_loop"> <problem>A per-iteration callback fires many independent Effect.runPromise calls, each with its own ad-hoc .catch.</problem> <example> // BAD: N runtime entries per tick, N separate error paths, no interruption. const tick = () => { Effect.runPromise(stepA()).catch(console.error) Effect.runPromise(stepB()).catch(console.error) Effect.runPromise(stepC()).catch(console.error) scheduleNext(tick) } </example> </anti_pattern>

  const makeLoop = Effect.gen(function* () {
    const commands = yield* Queue.unbounded<number>()

    // Single processing fiber: one runtime, unified error channel.
    yield* Effect.forever(
      Effect.gen(function* () {
        const ts = yield* Queue.take(commands)
        yield* stepA(ts)
        yield* stepB(ts)
        yield* stepC(ts)
      }),
    ).pipe(Effect.forkScoped)

    // The ONLY escape: hand each external event to the queue.
    const onTick = (ts: number) => Effect.runFork(Queue.offer(commands, ts))
    return { onTick } as const
  })
</example>
<notes>
  <item>Prefer `Effect.runFork` over `Effect.runPromise` at the boundary when you are firing-and-forgetting; it returns a Fiber you can interrupt and does not create an unhandled-rejection surface.</item>
  <item>Attach `Effect.catchAllCause(cause =&gt; Effect.logError(...))` to the forked program so failures land in Effect's logger instead of a bare `.catch(console.error)`.</item>
  <item>One processing fiber gives a single pause/resume/interrupt control point that the multi-escape version cannot.</item>
</notes>

<imperative_to_effect> <description>Correspondence table for replacing imperative constructs with Effect equivalents that preserve the typed error channel and interruption.</description> <mapping> <row imperative="try/catch around sync code" effect="Effect.try({ try, catch }) — models the failure as a typed error E instead of swallowing it" /> <row imperative="try/catch around a Promise / async fn" effect="Effect.tryPromise({ try, catch })" /> <row imperative="throw new DomainError()" effect="Effect.fail(new DomainError()) with a Data.TaggedError subclass" /> <row imperative="setInterval / clearInterval" effect="Effect.repeat(effect, Schedule.spaced(...)) on a forked fiber; interrupt to stop" /> <row imperative="setTimeout(fn, ms)" effect="Effect.delay(effect, Duration) or Effect.sleep" /> <row imperative="addEventListener / removeEventListener pair" effect="Effect.acquireRelease inside a scoped layer" /> <row imperative="let mutable = ...; mutable = next" effect="Ref.make + Ref.set/Ref.update for shared state that outlives a single expression" /> <row imperative="console.log / warn / error" effect="Effect.log / Effect.logWarning / Effect.logError (structured, testable)" /> <row imperative="new Promise + resolve/reject callback API" effect="Effect.async(register) to lift a callback source into an interruptible Effect" /> <row imperative="throw to abort a batch" effect="Effect.fail short-circuits the Effect.gen; recover with Effect.catchTag / catchAll" /> </mapping> <caveats> <item>An async function passed to Effect.tryPromise is already correctly wrapped — rewriting its internal await chain into Promise combinators is a style change, not a correctness fix; leave it unless there is a reason.</item> <item>Not every callback must be lifted. Event-emitter integrations with third-party libraries whose API is fundamentally callback-based are legitimate boundaries; wrap the surface in an Effect interface rather than abstracting the whole library.</item> <item>Local loop counters and accumulators inside a single function are fine as plain let. Reserve Ref for state that is shared across effects or must survive between fiber steps.</item> </caveats> </imperative_to_effect>

<schema_as_ssot> <description> Define data with Schema and DERIVE the static type from it, so a value type and its validator can never diverge. This is the default for domain/application value types. </description>

  export const PositionSchema = Schema.Struct({
    x: Schema.Number,
    y: Schema.Number,
    z: Schema.Number,
  })
  export type Position = Schema.Schema.Type<typeof PositionSchema>

  // Branded identifiers via Schema (nominal typing over primitives):
  export const EntityIdSchema = Schema.String.pipe(Schema.brand("EntityId"))
  export type EntityId = Schema.Schema.Type<typeof EntityIdSchema>

  // Tagged unions:
  export const CommandSchema = Schema.TaggedStruct("Tick", { at: Schema.Number })
</example>
<notes>
  <item>Universal pattern: `export const XSchema = Schema.Struct({...})` then `export type X = Schema.Schema.Type&lt;typeof XSchema&gt;`. Never hand-write a parallel interface.</item>
  <item>Decode at boundaries with `Schema.decodeUnknown` (Effect-returning) or `decodeUnknownSync`; keep structural validation in the schema and push value-range clamping into an explicit follow-up step when bounds are business rules rather than shape.</item>
  <item>For JS `Date` instances use `Schema.DateFromSelf`; for ISO-string dates use `Schema.Date`. Choosing the wrong one silently changes the decoded representation.</item>
</notes>

  describe("Database", () => {
    // it.effect: body returns an Effect; TestContext (incl. TestClock) auto-provided.
    it.effect("returns a result", () =>
      Effect.gen(function* () {
        const db = yield* Database
        const out = yield* db.query("SELECT 1")
        expect(out).toContain("SELECT 1")
      }).pipe(Effect.provide(TestLayer)),
    )
  })
</example>
<notes>
  <item>`describe`/`it` come from "@effect/vitest"; `expect` still comes from "vitest".</item>
  <item>`it.effect` provides the Test services (TestClock, TestRandom, …) automatically. Use `it.scoped` when the body opens a Scope, and `it.live` when you deliberately want the real clock/services.</item>
</notes>

  const program = subjectUnderTest.pipe(Effect.provide(
    Subject.DefaultWithoutDependencies.pipe(Layer.provide(NoiseMock)),
  ))
</example>
<notes>
  <item>For an Effect.Service you can alternatively construct a mock instance (`new Subject({ ...methods })`) and inject it with `Effect.provideService`.</item>
  <item>Keep mocks synchronous where possible (`Effect.sync`, `Effect.void`, `Effect.succeed`) so tests stay deterministic.</item>
</notes>

  it.effect("fires after the interval", () =>
    Effect.gen(function* () {
      const before = yield* pollOutput
      yield* TestClock.adjust("60 minutes") // advance virtual time
      const after = yield* pollOutput
      expect(before).not.toEqual(after)
    }),
  )
</example>
<notes>
  <item>`TestClock.adjust` advances the virtual clock and runs any effects scheduled within that window — recurring/delayed effects become synchronous and deterministic.</item>
  <item>To flush forked handlers inside a test, prefer an Effect-based pause such as `Effect.yieldNow()` over a raw `Promise` sleep; wall-clock sleeps are both flaky and, in strict Effect codebases, flagged as domain-layer violations.</item>
</notes>

<best_practices> <practice priority="critical">Sequence dependent layers with provide/provideMerge; never rely on mergeAll to wire a dependency.</practice> <practice priority="critical">Enter the Effect runtime once at the program edge; do not scatter runPromise/runSync through hot paths.</practice> <practice priority="high">Standardize on Effect.Service for app services with a real implementation; reserve Context.Tag for "no assumed implementation".</practice> <practice priority="high">Derive every value type from its Schema; do not hand-maintain a parallel interface.</practice> <practice priority="high">Model failures as typed errors (Effect.fail / Data.TaggedError), not thrown exceptions or silent catch blocks.</practice> <practice priority="high">Apply Effect.provide before Effect.scoped; keep scoping at the outermost layer of the pipeline.</practice> <practice priority="medium">Use Effect.acquireRelease inside scoped layers for every acquire/release pair (listeners, intervals, connections).</practice> <practice priority="medium">Test with it.effect and Layer-based mocks; use TestClock for anything time-dependent.</practice> <practice priority="medium">Route failures to Effect.logError via catchAllCause rather than bare .catch(console.error).</practice> </best_practices>

<anti_patterns> <avoid name="mergeall_for_dependencies"> <description>Using Layer.mergeAll to combine layers that depend on one another.</description> <instead>Wire with Layer.provide/provideMerge so the dependency is discharged at the composition site, not leaked to the top-level provide.</instead> </avoid> <avoid name="runtime_escape_per_iteration"> <description>Calling Effect.runPromise/runSync inside a render frame, stream item, or request handler.</description> <instead>Bridge the external event into a Queue once and process on a single forked fiber.</instead> </avoid> <avoid name="silent_try_catch"> <description>Raw try/catch whose catch block returns a default and discards the cause.</description> <instead>Effect.try with an explicit error constructor, so the failure is typed and observable.</instead> </avoid> <avoid name="parallel_interface_and_schema"> <description>Declaring both a Schema and a separate interface for the same data.</description> <instead>Keep the Schema as SSOT and derive the type with Schema.Schema.Type.</instead> </avoid> <avoid name="schema_on_hot_or_opaque_types"> <description>Forcing TypedArrays, external class instances, or mutable caches into Schema.</description> <instead>Leave them as native types; Schema is for plain value data only.</instead> </avoid> <avoid name="scoped_inside_provision_pipeline"> <description>Wrapping a partially-provided program in Effect.scoped before provide.</description> <instead>Provide first, then scope the fully-provided program.</instead> </avoid> </anti_patterns>

<error_escalation inherits="core-patterns#error_escalation"> <examples> <example severity="low">Style-only difference (async closure inside a correctly-wrapped Effect.tryPromise)</example> <example severity="medium">Requirement leak from mergeAll surfacing as a top-level provide type error</example> <example severity="high">Hot-path runtime escapes dropping the error channel and interruption</example> <example severity="critical">Silent catch blocks hiding failures with no logging or typed error</example> </examples> </error_escalation>

<related_skills> <skill name="typescript-ecosystem">Underlying TypeScript config, generics, and utility types Effect builds on</skill> <skill name="testing-patterns">General test strategy that @effect/vitest patterns plug into</skill> <skill name="context7-usage">Verify current Effect / @effect/vitest APIs and version behavior</skill> <skill name="investigation-patterns">Evidence-based tracing of requirement leaks and runtime-boundary issues</skill> </related_skills> <related_agents> <agent name="explore">Locate service, layer, and schema declarations across the codebase</agent> <agent name="quality-assurance">Review Effect composition and error-channel discipline</agent> <agent name="test">Design it.effect + TestClock coverage for converted logic</agent> </related_agents>