effect
Guides working with Effect-TS in TypeScript codebases. Use when writing Effect programs, defining services/layers, handling errors, running effects, or when code uses effect, Context, Layer, Effect.ge
SKILL.mddataset/repos/dxos§dxos/.cursor/skills/effect/SKILL.md
GitHubWorking with Effect
Effect is a TypeScript library for building complex synchronous and asynchronous programs with typed errors, dependency injection, and resource management. Reference: https://effect.website/llms.txt.
Core Principles (Inlined)
The Effect Type
Effect<Success, Error, Requirements> is a lazy, immutable description of a workflow:
- Success: Value on success.
- Error: Expected (typed) errors; use
neverwhen effect cannot fail. - Requirements: Services/dependencies from
Context; useneverwhen none needed.
Effects are descriptions, not executions. They run via the Effect runtime at a single entry point.
import { Effect, Context, Layer } from 'effect';
// Effect<number, never, never> - succeeds with number, no errors, no deps
const pure = Effect.succeed(42);
// Effect<never, Error, never> - fails with Error
const failure = Effect.fail(new Error('failed'));
Two Types of Errors
| Type | Tracked in type | Purpose |
|---|---|---|
| Expected | Yes (Error in Effect) |
Anticipated, domain errors, recoverable (like checked exceptions) |
| Unexpected | No | Defects, bugs, unanticipated (like unchecked exceptions) |
Use Effect.fail() for expected errors. Thrown errors in sync/async code become defects. Avoid throw; prefer Effect.fail or Effect.try.
Creating Effects
| Constructor | Use case |
|---|---|
Effect.succeed(v) |
Pure success |
Effect.fail(e) |
Expected failure |
Effect.sync(() => x) |
Sync side effect; must not throw |
Effect.try(() => x) |
Sync that may throw → defect or caught |
Effect.promise(() => Promise) |
Wrap Promise (reject → defect) |
Effect.gen(function* () { ... }) |
Generator style, like async/await |
const program = Effect.gen(function* () {
const a = yield* Effect.succeed(1);
const b = yield* Effect.succeed(2);
return a + b;
});
Running Effects
| Function | Returns | When to use |
|---|---|---|
Effect.runSync(e) |
A |
Sync only, no fail; throws otherwise |
Effect.runPromise(e) |
Promise<A> |
Async; rejects on failure |
Effect.runPromiseExit(e) |
Promise<Exit<A, E>> |
Get Exit for custom handling |
Provide requirements before running: Effect.runPromise(Effect.provide(program, layer)).
Services and Context
- Define a service with
Context.Tag:
class MyService extends Context.Tag('MyService')<
MyService,
{ readonly doSomething: () => Effect.Effect<string, never> }
>() {}
- Use in effects – the service appears in
Requirements:
const program = Effect.gen(function* () {
const service = yield* MyService;
return yield* service.doSomething();
});
// Effect<string, never, MyService>
- Provide with
Effect.provideServiceorEffect.provide+Layer.
Layers
Layers construct services and hide implementation dependencies. Avoid leaking internal deps in service interfaces.
Layer.succeed(Tag, implementation)– static implementationLayer.effect(Tag, Effect)– effectful constructionLayer.merge(a, b)– combine layers- Compose with
Layer.provide/Layer.provideMergefor dependency graphs
Provide at the edge: Effect.provide(program, AppLive).
Common Patterns
- Do notation: Prefer
Effect.genover manualflatMapchains. - Error recovery:
Effect.catchAll,Effect.catchTag,Effect.orElse,Effect.retry. - Resource management:
Effect.scoped,Scope,acquireRelease. - Concurrency:
Effect.all(parallel),Effect.forEachwith concurrency. - Tagged errors: Use
Data.TaggedClassorData.TaggedEnumfor typed domain errors.
Quick Reference
Import:
import { Effect, Context, Layer, Data } from 'effect';
Run program with layer:
const runnable = Effect.provide(program, AppLive);
Effect.runPromise(runnable);
Typed error:
class HttpError extends Data.TaggedClass('HttpError')<{ readonly status: number }> {}
Documentation Index
For deeper topics, see https://effect.website/docs/:
- Getting started: Creating Effects, Running Effects, The Effect Type, Using Generators
- Error management: Two Error Types, Expected Errors, Fallback, Retrying
- Services: Managing Services, Managing Layers, Default Services
- Concurrency: Basic Concurrency, Fibers, Queue, Semaphore
- Schema: effect/Schema for validation and encoding
- API: https://effect.website/docs/additional-resources/api-reference/