Effect-TS Expert

Expert-level guidance for Effect-TS functional programming with typed errors, dependency injection, concurrency, and production-ready patterns.

Core Concepts

The Effect Type

typescript

Effect<Success, Error, Requirements>
//     ^        ^       ^
//     |        |       └── Services/dependencies needed (Context)
//     |        └────────── Typed error channel
//     └─────────────────── Success value type

Key insight: Effects are lazy descriptions of computations. They don't execute until run.

Creating Effects

typescript

import { Effect } from "effect"

// From pure values
const success = Effect.succeed(42)
const failure = Effect.fail(new Error("oops"))

// From sync code (may throw)
const sync = Effect.sync(() => JSON.parse(data))
const trySync = Effect.try({
  try: () => JSON.parse(data),
  catch: (e) => new ParseError(e)
})

// From async code
const promise = Effect.promise(() => fetch(url))
const tryPromise = Effect.tryPromise({
  try: () => fetch(url).then(r => r.json()),
  catch: (e) => new FetchError(e)
})

// From callbacks
const callback = Effect.async<string, Error>((resume) => {
  someCallbackApi((err, result) => {
    if (err) resume(Effect.fail(err))
    else resume(Effect.succeed(result))
  })
})

Running Effects

typescript

// Development/testing
Effect.runSync(effect)           // Sync, throws on async/error
Effect.runPromise(effect)        // Returns Promise<A>
Effect.runPromiseExit(effect)    // Returns Promise<Exit<A, E>>

// Production (with runtime)
const runtime = ManagedRuntime.make(AppLayer)
await runtime.runPromise(effect)

Building Pipelines

pipe and Effect.gen

typescript

import { Effect, pipe } from "effect"

// Using pipe (point-free style)
const program = pipe(
  Effect.succeed(5),
  Effect.map(n => n * 2),
  Effect.flatMap(n => n > 5
    ? Effect.succeed(n)
    : Effect.fail(new Error("too small"))
  ),
  Effect.tap(n => Effect.log(`Result: ${n}`))
)

// Using Effect.gen (generator style - RECOMMENDED)
const program = Effect.gen(function* () {
  const n = yield* Effect.succeed(5)
  const doubled = n * 2
  if (doubled <= 5) {
    return yield* Effect.fail(new Error("too small"))
  }
  yield* Effect.log(`Result: ${doubled}`)
  return doubled
})

Recommendation: Prefer Effect.gen for readability. Use pipe for simple transformations.

Error Handling

Typed Errors vs Defects

Type	Use Case	Recovery
Typed Error	Domain failures (validation, not found, permissions)	Yes - caller can handle
Defect	Bugs, invariant violations, unrecoverable	No - terminates fiber

typescript

// Typed errors - tracked in type system
class NotFoundError extends Data.TaggedError("NotFoundError")<{
  readonly id: string
}> {}

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

const findUser = (id: string): Effect.Effect<User, NotFoundError> =>
  pipe(
    db.query(id),
    Effect.flatMap(user =>
      user ? Effect.succeed(user) : Effect.fail(new NotFoundError({ id }))
    )
  )

// Defects - for bugs, not domain errors
const divide = (a: number, b: number): Effect.Effect<number> =>
  b === 0
    ? Effect.die(new Error("Division by zero - this is a bug!"))
    : Effect.succeed(a / b)

Error Recovery

typescript

// Catch all errors
Effect.catchAll(effect, (error) => Effect.succeed(fallback))

// Catch specific tagged errors
Effect.catchTag(effect, "NotFoundError", (e) =>
  Effect.succeed(defaultUser)
)

// Catch multiple tags
Effect.catchTags(effect, {
  NotFoundError: (e) => Effect.succeed(defaultUser),
  ValidationError: (e) => Effect.fail(new HttpError(400, e.message))
})

// Convert to Either (errors become Left)
Effect.either(effect)  // Effect<Either<E, A>, never, R>

// Retry on failure
Effect.retry(effect, Schedule.recurs(3))

Best Practice: Error Design

typescript

// DO: Use tagged errors with Schema
import { Schema } from "effect"

class ApiError extends Schema.TaggedError<ApiError>()("ApiError", {
  status: Schema.Number,
  message: Schema.String,
}) {}

// DON'T: Use plain Error or strings
Effect.fail(new Error("something went wrong"))  // Loses type info
Effect.fail("error")  // Not an Error type

Dependency Injection

Services with Context.Tag

typescript

import { Context, Effect, Layer } from "effect"

// 1. Define service interface
class UserRepository extends Context.Tag("UserRepository")<
  UserRepository,
  {
    readonly findById: (id: string) => Effect.Effect<User, NotFoundError>
    readonly save: (user: User) => Effect.Effect<void>
  }
>() {}

// 2. Use in effects
const getUser = (id: string) => Effect.gen(function* () {
  const repo = yield* UserRepository
  return yield* repo.findById(id)
})
// Type: Effect<User, NotFoundError, UserRepository>

// 3. Create layer implementation
const UserRepositoryLive = Layer.succeed(UserRepository, {
  findById: (id) => Effect.tryPromise(() => db.users.find(id)),
  save: (user) => Effect.tryPromise(() => db.users.save(user))
})

// 4. Provide to run
const program = getUser("123")
const runnable = Effect.provide(program, UserRepositoryLive)

Effect.Service (Simplified Pattern)

typescript

// Combines Tag + Layer in one declaration
class Logger extends Effect.Service<Logger>()("Logger", {
  // Option 1: Sync implementation
  sync: () => ({
    log: (msg: string) => console.log(msg)
  }),

  // Option 2: Effect-based with dependencies
  effect: Effect.gen(function* () {
    const config = yield* Config
    return {
      log: (msg: string) => Effect.sync(() =>
        console.log(`[${config.level}] ${msg}`)
      )
    }
  }),
  dependencies: [ConfigLive]
}) {}

// Use directly
const program = Logger.log("Hello")

// Access via Layer
Effect.provide(program, Logger.Default)

Layer Composition

typescript

// Merge independent layers
const BaseLayer = Layer.merge(ConfigLive, LoggerLive)

// Provide dependencies
const DbLayer = Layer.provide(DatabaseLive, ConfigLive)

// Full composition
const AppLayer = pipe(
  Layer.merge(ConfigLive, LoggerLive),
  Layer.provideMerge(DatabaseLive),
  Layer.provideMerge(UserRepositoryLive)
)

See references/layers.md for advanced patterns.

Concurrency

Fibers

typescript

// Fork to run concurrently
const fiber = yield* Effect.fork(longRunningTask)

// Wait for result
const result = yield* Fiber.join(fiber)

// Interrupt
yield* Fiber.interrupt(fiber)

// Race - first to complete wins
const fastest = yield* Effect.race(task1, task2)

// All - run all, collect results
const results = yield* Effect.all([task1, task2, task3])

// All with concurrency limit
const results = yield* Effect.all(tasks, { concurrency: 5 })

Synchronization Primitives

typescript

// Ref - mutable reference
const counter = yield* Ref.make(0)
yield* Ref.update(counter, n => n + 1)
const value = yield* Ref.get(counter)

// Queue - bounded producer/consumer
const queue = yield* Queue.bounded<number>(100)
yield* Queue.offer(queue, 42)
const item = yield* Queue.take(queue)

// Semaphore - limit concurrent access
const sem = yield* Effect.makeSemaphore(3)
yield* sem.withPermits(1)(expensiveOperation)

// Deferred - one-shot signal
const deferred = yield* Deferred.make<string, Error>()
yield* Deferred.succeed(deferred, "done")
const value = yield* Deferred.await(deferred)

Resource Management

Scoped Resources

typescript

// Acquire/release pattern
const file = Effect.acquireRelease(
  Effect.sync(() => fs.openSync(path, "r")),  // acquire
  (fd) => Effect.sync(() => fs.closeSync(fd))  // release
)

// Use with scoped
const program = Effect.scoped(
  Effect.gen(function* () {
    const fd = yield* file
    return yield* readFile(fd)
  })
)
// File automatically closed after scope

Finalizers

typescript

const program = Effect.gen(function* () {
  yield* Effect.addFinalizer((exit) =>
    Effect.log(`Cleanup: ${exit._tag}`)
  )
  // ... do work
})

const runnable = Effect.scoped(program)

Quick Reference

Common Operators

Operator	Purpose
`Effect.map`	Transform success value
`Effect.flatMap`	Chain effects (monadic bind)
`Effect.tap`	Side effect, keep original value
`Effect.andThen`	Sequence, can be value or effect
`Effect.catchAll`	Handle all errors
`Effect.catchTag`	Handle specific tagged error
`Effect.provide`	Inject dependencies
`Effect.retry`	Retry with schedule
`Effect.timeout`	Add timeout
`Effect.fork`	Run concurrently
`Effect.all`	Parallel execution

When to Use What

Scenario	Use
Transform value	`Effect.map`
Chain effects	`Effect.flatMap` or `Effect.gen`
Error recovery	`Effect.catchTag` / `Effect.catchAll`
Add logging	`Effect.tap` + `Effect.log`
Run in parallel	`Effect.all` with `concurrency`
Limit concurrency	`Semaphore`
Share mutable state	`Ref`
Producer/consumer	`Queue`
One-time signal	`Deferred`
Cleanup resources	`Effect.acquireRelease`

Reference Documents

•references/error-handling.md - Typed errors, defects, recovery patterns
•references/layers.md - Dependency injection, service composition
•references/concurrency.md - Fibers, synchronization, parallelism
•references/streams.md - Stream, Sink, Channel patterns
•references/schema.md - Validation, encoding/decoding
•references/testing.md - Test layers, mocking, vitest integration
•references/config.md - Configuration management
•references/anti-patterns.md - Common mistakes and fixes
•references/fp-ts-migration.md - Migration from fp-ts

Usage

This skill activates automatically when working with Effect-TS files or when the user mentions Effect, functional TypeScript, or typed errors.

Explicit invocation:

code

/effect-ts help me refactor this to use Effect
/effect-ts create a service with dependency injection
/effect-ts fix error handling in this code