Overview

Effect is a TypeScript library that makes errors, dependencies, and async operations explicit in the type system. Instead of try-catch with unknown errors, every function declares exactly what can go wrong. Instead of global imports, every dependency is tracked in the type. The result: code that's easier to test, refactor, and reason about.

When to Use

Business logic where knowing every possible error matters (payments, auth, data pipelines)
Applications with complex dependency graphs that need testability
Concurrent operations that need structured concurrency (not just Promise.all)
Data validation and transformation pipelines
Replacing error-prone try-catch chains with typed error handling

Instructions

Core Concept: Effect<Success, Error, Requirements>

Every Effect value has three type parameters:

Success: what it returns when it works
Error: what errors it can produce
Requirements: what services/dependencies it needs

typescript

// core.ts — Effect basics: typed errors and pipe
import { Effect, pipe } from "effect";

// Define typed errors (not just Error/string)
class UserNotFound {
  readonly _tag = "UserNotFound";
  constructor(readonly userId: string) {}
}

class DatabaseError {
  readonly _tag = "DatabaseError";
  constructor(readonly cause: unknown) {}
}

// Function that can fail with typed errors
//           Success ───┐  Error ──────────────────────────┐  Requirements ─┐
//                      ▼                                   ▼                ▼
const getUser = (id: string): Effect.Effect<User, UserNotFound | DatabaseError, never> =>
  pipe(
    Effect.tryPromise({
      try: () => db.user.findUnique({ where: { id } }),
      catch: (e) => new DatabaseError(e),
    }),
    Effect.flatMap((user) =>
      user ? Effect.succeed(user) : Effect.fail(new UserNotFound(id))
    )
  );

// Handle specific errors
const getUserOrDefault = (id: string) =>
  pipe(
    getUser(id),
    Effect.catchTag("UserNotFound", () =>
      Effect.succeed({ id: "default", name: "Guest", email: "guest@example.com" })
    )
    // DatabaseError is NOT caught — it propagates up in the type
  );

Dependency Injection with Layers

typescript

// services.ts — Dependency injection without classes
import { Effect, Context, Layer } from "effect";

// Define a service interface
class UserRepo extends Context.Tag("UserRepo")<
  UserRepo,
  {
    findById: (id: string) => Effect.Effect<User | null, DatabaseError>;
    create: (data: NewUser) => Effect.Effect<User, DatabaseError>;
  }
>() {}

// Business logic that REQUIRES UserRepo (tracked in type)
const getUser = (id: string) =>
  pipe(
    UserRepo,                    // Access the service
    Effect.flatMap((repo) => repo.findById(id)),
    Effect.flatMap((user) =>
      user ? Effect.succeed(user) : Effect.fail(new UserNotFound(id))
    )
  );
//   ^? Effect<User, UserNotFound | DatabaseError, UserRepo>
//                                                  ^^^^^^^^ dependency tracked!

// Production implementation
const UserRepoLive = Layer.succeed(UserRepo, {
  findById: (id) =>
    Effect.tryPromise({
      try: () => prisma.user.findUnique({ where: { id } }),
      catch: (e) => new DatabaseError(e),
    }),
  create: (data) =>
    Effect.tryPromise({
      try: () => prisma.user.create({ data }),
      catch: (e) => new DatabaseError(e),
    }),
});

// Test implementation
const UserRepoTest = Layer.succeed(UserRepo, {
  findById: (id) => Effect.succeed({ id, name: "Test", email: "test@test.com" }),
  create: (data) => Effect.succeed({ id: "new-id", ...data }),
});

// Run with real dependencies
Effect.runPromise(
  pipe(getUser("123"), Effect.provide(UserRepoLive))
);

// Run with test dependencies
Effect.runPromise(
  pipe(getUser("123"), Effect.provide(UserRepoTest))
);

Concurrency and Scheduling

typescript

// concurrent.ts — Structured concurrency with Effect
import { Effect, Schedule, Duration } from "effect";

// Run tasks concurrently with a limit
const processItems = (items: string[]) =>
  Effect.forEach(items, (item) => processItem(item), {
    concurrency: 5,    // Max 5 concurrent
    batching: true,     // Batch database calls
  });

// Retry with exponential backoff
const resilientFetch = (url: string) =>
  pipe(
    Effect.tryPromise(() => fetch(url).then((r) => r.json())),
    Effect.retry(
      Schedule.exponential(Duration.seconds(1)).pipe(
        Schedule.compose(Schedule.recurs(3)),  // Max 3 retries
        Schedule.jittered,                      // Add random jitter
      )
    ),
  );

// Timeout
const withTimeout = pipe(
  slowOperation(),
  Effect.timeout(Duration.seconds(5)),
);

// Race — first to complete wins
const fastest = Effect.race(
  fetchFromPrimary(),
  fetchFromFallback(),
);

Schema — Runtime Validation + Type Inference

typescript

// schema.ts — Validation with Effect Schema (replaces Zod)
import { Schema } from "effect";

const User = Schema.Struct({
  id: Schema.UUID,
  name: Schema.String.pipe(Schema.minLength(2), Schema.maxLength(100)),
  email: Schema.String.pipe(Schema.pattern(/^[^@]+@[^@]+\.[^@]+$/)),
  age: Schema.Number.pipe(Schema.int(), Schema.between(13, 120)),
  role: Schema.Literal("user", "admin"),
  createdAt: Schema.Date,
});

// Type is inferred — no duplicate definition
type User = Schema.Schema.Type<typeof User>;

// Decode (parse + validate)
const parseUser = Schema.decodeUnknown(User);
const result = Effect.runSync(parseUser({ id: "...", name: "Kai", email: "kai@example.com", age: 25, role: "user", createdAt: new Date() }));

Examples

Example 1: Build a payment processing pipeline

User prompt: "Build a payment flow with typed errors for each failure case — card declined, insufficient funds, fraud detected, network timeout."

The agent will define tagged error types for each failure, compose the payment pipeline with Effect.pipe, add retry for network errors, and propagate card/fraud errors to the caller with full type information.

Example 2: Testable service with dependency injection

User prompt: "I want to test my business logic without hitting the database."

The agent will define services as Effect Context.Tags, write business logic that depends on service interfaces, create Layer.succeed implementations for both production and test, and run the same logic against fake data in tests.

Guidelines

Start with Effect.tryPromise — wrap existing async code first, then gradually adopt more Effect patterns
Tag your errors — readonly _tag = "ErrorName" enables catchTag for precise error handling
Layers for DI — define service interfaces with Context.Tag, implement with Layer
pipe everything — Effect uses pipe-based composition; avoid nesting
Don't runPromise inside Effects — compose Effects together, run once at the entry point
Schema over Zod — Effect Schema integrates with the Effect ecosystem and is more composable
Concurrency is explicit — { concurrency: 5 } not hidden behind promise pools
Learning curve is real — Effect is powerful but complex; introduce gradually to a team
Effect is a runtime — it manages execution; don't mix with raw Promises inside Effects

effect-ts

Usage

Getting Started

Example Prompts

Documentation

Overview

When to Use

Instructions

Core Concept: Effect<Success, Error, Requirements>

Dependency Injection with Layers

Concurrency and Scheduling

Schema — Runtime Validation + Type Inference

Examples

Example 1: Build a payment processing pipeline

Example 2: Testable service with dependency injection

Guidelines

Information