effect

Files (5)

• SKILL.md
• effect-code-style.md · references/
• effect-constructors.md · references/
• effect-running.md · references/
• effect-setup.md · references/

SKILL.md (first lines)

# Effect

Checked against `effect` 4.0.0. When the project has a newer version, check each API in the project's own copy: read `node_modules/effect/src/<Module>.ts` (each export has a doc comment with **When to use** and **Gotchas**) and `node_modules/effect/AGENTS.md`. The installed source wins over this skill and over every website page.

## Pick the skill

This skill holds the core: the `Effect` type, setup and imports, creating effects, `Effect.gen` and `Effect.fn`, pipelines, running at the edge, house style, and where to look an API up. Load the skill that matches the task as well:

| Skill | Reach for it when you |
| --- | --- |
| `effect-errors` | define a tagged error, recover from a failure, read a `Cause` or `Exit`, set a retry or a timeout |
| `effect-concurrency` | run work in parallel, fork or interrupt a fiber, race, use `Deferred`, `Queue`, `PubSub`, `Semaphore`, `Latch`, `Ref`, or a `Schedule` |
| `effect-streams` | produce or consume a `Stream`, or use `Sink`, `Channel` or a stream encoding |
| `effect-services` | define a service with `Context.Service`, build a `Layer`, manage a `Scope` or resource, read `Config`, use `ManagedRuntime` or a platform module |
| `effect-schema` | decode, encode or validate data with `Schema` |
| `effect-data` | use `Option`, `Result`, `Duration`, `DateTime`, `Chunk`, `HashMap`, `Data`, `Equal`, `Order`, a cache or request batching |
| `effect-observability` | add logs, spans or metrics, or export them |
| `effect-testing` | test Effect code with `@effect/vitest`, `TestClock` or test layers |
| `effect-adoption` | bring Effect into a Promise codebase one module at a time |
| `effect-v3-to-v4` | meet Effect 3 code or Effect 3 API names |

These eleven skills are one set and name each other: install them together. If a skill named here is missing, use **Look an API up** below.

An API name that you remember from Effect 3 (`catchAll`, `Either`, `Context.Tag`, `Effect.fork`) is a migration case: load `effect-v3-to-v4` before you write it.

## The Effect type

`Effect<A, E, R>` is a value that describes a program: it succeeds with `A`, fails with an expected error `E`, and needs the services `R`. `E` and `R` default to `never`. Read the parts of an existing effect with `Effect.Success<typeof x>`, `Effect.Error<typeof x>` and `Effect.Services<typeof x>`.

- An effect is lazy. Building it runs nothing; each run runs it again from the start.
- An effect is immutable. Every operator returns a new effect.
- An effect that you build and then drop never runs. Inside a callback, return it or `yield*` it.

## Create effects

| You have | Write | Failure mode |
| --- | --- | --- |
| a value | `Effect.succeed(value)` | none |
| an expected error | `Effect.fail(error)` | typed `E` |
| sync code that cannot throw | `Effect.sync(() => ...)` | a throw becomes a defect |
| sync code that can throw | `Effect.try({ try, catch })` | `catch` maps the throw to `E` |
| a Promise that cannot reject | `Effect.promise((signal) => ...)` | a rejection becomes a defect |
| a Promise that can reject | `Effect.tryPromise({ try: (signal) => ..., catch })` | `catch` maps the rejection to `E` |
| a callback API | `Effect.callback<A, E>((resume, signal) => ...)` | what you pass to `resume` |
| a value that can be `null` or `undefined` | `Effect.fromNullishOr(value)` | `Cause.NoSuchElementError` |
| an `Option` or a `Result` | `Effect.fromOption(o)`, `Effect.fromResult(r)` | `NoSuchElementError`, or the `Result` error |
| an effect to build on each run | `Effect.suspend(() => effect)` | that of the effect |

Traps:

- `Effect.succeed(expr)` evaluates `expr` once, when you build the effect. For a fresh value on each run, use `Effect.sync` or `Effect.suspend`.
- `Effect.try` and `Effect.tryPromise` without `catch` fail with `Cause.UnknownError`, which loses the type of the cause. Pass `catch` and map to a tagged error (see `effect-errors`).
- Pass the `signal` of `promise` and `tryPromise` on to `fetch` and other abortable APIs. Effect aborts it when the fiber is interrupted, for example by a timeout.

More constructors and the callback contract: [references/effect-constructors.md](references/effect-constructors.md).

## Write sequential code with Effect.gen

Use `Effect.gen` for inline code. `yield*` an effect to get its value; the first failure stops the generator.

```ts
import * as Data from "effect/Data"
import * as Effect from "effect/Effect"

class InsufficientFunds extends Data.TaggedError("InsufficientFunds")<{
  readonly balance: number
  readonly message: string
}> {}

declare const readBalance: (account: string) => Effect.Effect<number>

export const program = Effect.gen(function*() {
  const balance = yield* readBalance("acc-1")
  if (balance < 100) {
    return yield* new InsufficientFunds({ balance, message: `balance ${balance} is below 100` })
  }
  return balance - 100
})
```

- Write `return yield*` for every failure. Without `return`, TypeScript does not narrow the code after it.
- Use `if`, `for` and `while` as in plain code.
- Keep `try`/`catch`/`finally` away from `yield*`. In 4.0.0 a `catch` block does not see a failed effect, and a `finally` block does not run when the effect fails, dies or is interrupted. Use `Effect.catch*` operators for recovery and `Effect.ensuring`, `Effect.onExit` or `Effect.acquireRelease` for cleanup.
- To bind `this`, pass it first: `Effect.gen({ self: this }, function*() { ... })`.
- `Option` and `Result` are not yieldable in `Effect.gen` in 4.0.0, despite what the v4 migration guide says. Convert first: `yield* Effect.fromOption(option)`.

## Write reusable functions with Effect.fn

For a function that returns an effect, use `Effect.fn("Name")` with the function's own name. It creates a tracing span with that name when the effect runs, and adds the call site and definition site to `Cause.pretty` output. Use `Effect.fnUntraced` in hot paths and library internals, where a span costs more than it gives. Do not write a plain function that only returns `Effect.gen`.

```ts
import * as Effect from "effect/Effect"
import * as Schema from "effect/Schema"

class PriceNotFound extends Schema.TaggedError<PriceNotFound>()("PriceNotFound", {
  sku: Schema.String
}) {}

declare const lookup: (sku: string) => Effect.Effect<number | undefined>

export const priceOf = Effect.fn("priceOf")(
  function*(sku: string): Effect.fn.Return<number, PriceNotFound> {
    const price = yield* lookup(sku)
    if (price === undefined) return yield* new PriceNotFound({ sku })
    return price
  },
  (effect, sku) => Effect.annotateLogs(effect, { sku })
)
```

- Put extra behaviour (`Effect.catchTag`, `Effect.retry`, `Effect.annotateLogs`) in the arguments after the body. Each one receives the effect and the call's arguments, and runs inside the span. A `.pipe` on the call result runs outside the span.
- `Effect.fn.Return<A, E, R>` annotates the generator's return type. Use it to fix the public type of the function, so that a change in the body cannot widen it. It does not catch a narrower type: a body that stops raising a declared error still compiles. For a public error type, let `Effect.fn` infer it and pin it with a type test (see `effect-errors`).
- `Effect.fn` also accepts a body that returns an effect directly: `Effect.fn("parse")((input: string) => Effect.try(...))`. `Effect.fnUntraced` accepts only a generator.
- Calling the function runs nothing. Each run of the returned effect runs the body.

## Build pipelines

`effect.pipe(f, g, h)` is `h(g(f(effect)))`. Most operators are dual: `Effect.map(effect, f)` and `effect.pipe(Effect.map(f))` are the same.

From andabove/skills, MIT.

More from andabove/skills