Effect-TS Expert

Expert guidance for functional programming with the Effect library, covering error handling, dependency injection, composability, and testing patterns.

Prerequisites Check

Before starting any Effect-related work, verify the Effect-TS source code exists at ~/.effect.

If missing, stop immediately and inform the user. Clone it before proceeding:

bash
1git clone https://github.com/Effect-TS/effect.git ~/.effect

Research Strategy

Effect-TS has many ways to accomplish the same task. Proactively research best practices using the Task tool to spawn research agents when working with Effect patterns, especially for moderate to high complexity tasks.

Research Sources (Priority Order)

1. Codebase Patterns First — Examine similar patterns in the current project before implementing. If Effect patterns exist in the codebase, follow them for consistency. If no patterns exist, skip this step.

2. Effect Source Code — For complex type errors, unclear behavior, or implementation details, examine the Effect source at ~/.effect/packages/effect/src/. This contains the core Effect logic and modules.

When to Research

HIGH Priority (Always Research):

• Implementing Services, Layers, or complex dependency injection
• Error handling with multiple error types or complex error hierarchies
• Stream-based operations and reactive patterns
• Resource management with scoped effects and cleanup
• Concurrent/parallel operations and performance-critical code
• Testing patterns, especially unfamiliar test scenarios

MEDIUM Priority (Research if Complex):

• Refactoring imperative code (try-catch, promises) to Effect patterns
• Adding new service dependencies or restructuring service layers
• Custom error types or extending existing error hierarchies
• Integrations with external systems (databases, APIs, third-party services)

Research Approach

• Spawn multiple concurrent Task agents when investigating multiple related patterns
• Focus on finding canonical, readable, and maintainable solutions rather than clever optimizations
• Verify suggested approaches against existing codebase patterns for consistency (if patterns exist)
• When multiple approaches are possible, research to find the most idiomatic Effect-TS solution

Codebase Pattern Discovery

When working in a project that uses Effect, check for existing patterns before implementing new code:

1. Search for Effect imports — Look for files importing from 'effect' to understand existing usage
2. Identify service patterns — Find how Services and Layers are structured in the project
3. Note error handling conventions — Check how errors are defined and propagated
4. Examine test patterns — Look at how Effect code is tested in the project

If no Effect patterns exist in the codebase, proceed using canonical patterns from the Effect source and examples. Do not block on missing codebase patterns.

Effect Principles

Apply these core principles when writing Effect code:

Error Handling

• Use Effect's typed error system instead of throwing exceptions
• Define descriptive error types with proper error propagation
• Use Effect.fail, Effect.catchTag, Effect.catchAll for error control flow
• See ./references/CRITICAL_RULES.md for forbidden patterns

Dependency Injection

• Implement dependency injection using Services and Layers
• Define services with Context.Tag
• Compose layers with Layer.merge, Layer.provide
• Use Effect.provide to inject dependencies

Composability

• Leverage Effect's composability for complex operations
• Use appropriate constructors: Effect.succeed, Effect.fail, Effect.tryPromise, Effect.try
• Apply proper resource management with scoped effects
• Chain operations with Effect.flatMap, Effect.map, Effect.tap

Code Quality

• Write type-safe code that leverages Effect's type system
• Use Effect.gen for readable sequential code
• Implement proper testing patterns using Effect's testing utilities
• Prefer Effect.fn() for automatic telemetry and better stack traces

Critical Rules

Read and internalize ./references/CRITICAL_RULES.md before writing any Effect code. Key guidelines:

• INEFFECTIVE: try-catch in Effect.gen (Effect failures aren't thrown)
• AVOID: Type assertions (as never/any/unknown)
• RECOMMENDED: return yield* pattern for errors (makes termination explicit)

Common Failure Modes

Quick links to patterns that frequently cause issues:

• SubscriptionRef version mismatch — unsafeMake is not a function → Quick Reference
• Cancellation vs Failure — Interrupts aren't errors → Error Taxonomy
• Option vs null — Use Option internally, null at boundaries → OPTION_NULL.md
• Stream backpressure — Infinite streams hang → STREAMS.md

Explaining Solutions

When providing solutions, explain the Effect-TS concepts being used and why they're appropriate for the specific use case. If encountering patterns not covered in the documentation, suggest improvements while maintaining consistency with existing codebase patterns (when they exist).

Quick Reference

Creating Effects

typescript
1Effect.succeed(value)           // Wrap success value
2Effect.fail(error)              // Create failed effect
3Effect.tryPromise(fn)           // Wrap promise-returning function
4Effect.try(fn)                  // Wrap synchronous throwing function
5Effect.sync(fn)                 // Wrap synchronous non-throwing function

Composing Effects

typescript
1Effect.flatMap(effect, fn)      // Chain effects
2Effect.map(effect, fn)          // Transform success value
3Effect.tap(effect, fn)          // Side effect without changing value
4Effect.all([...effects])        // Run effects (concurrency configurable)
5Effect.forEach(items, fn)       // Map over items with effects
6
7// Collect ALL errors (not just first)
8Effect.all([e1, e2, e3], { mode: "validate" })  // Returns all failures
9
10// Partial success handling
11Effect.partition([e1, e2, e3])  // Returns [failures, successes]

Error Handling

typescript
1// Define typed errors with Data.TaggedError (preferred)
2class UserNotFoundError extends Data.TaggedError("UserNotFoundError")<{
3  userId: string
4}> {}
5
6// Direct yield of errors (no Effect.fail wrapper needed)
7Effect.gen(function* () {
8  if (!user) {
9    return yield* new UserNotFoundError({ userId })
10  }
11})
12
13Effect.catchTag(effect, tag, fn) // Handle specific error tag
14Effect.catchAll(effect, fn)      // Handle all errors
15Effect.result(effect)            // Convert to Exit value
16Effect.orElse(effect, alt)       // Fallback effect

Error Taxonomy

Categorize errors for appropriate handling:

typescript
1// Pattern: Normalize unknown errors at boundary
2const safeBoundary = Effect.catchAllDefect(effect, (defect) =>
3  Effect.fail(new UnknownError({ cause: defect }))
4)
5
6// Pattern: Catch user-initiated cancellations separately
7Effect.catchTag(effect, "UserCancelledError", () => Effect.succeed(null))
8
9// Pattern: Handle interruptions differently from failures
10Effect.onInterrupt(effect, () => Effect.log("Operation cancelled"))

Pattern Matching (Match Module)

Default branching tool for tagged unions and complex conditionals.

typescript
1import { Match } from "effect"
2
3// Type-safe exhaustive matching on tagged errors
4const handleError = Match.type<AppError>().pipe(
5  Match.tag("UserCancelledError", () => null),          // Expected rejection
6  Match.tag("ValidationError", (e) => e.message),       // Domain error
7  Match.tag("NetworkError", () => "Connection failed"), // Retryable
8  Match.exhaustive  // Compile error if case missing
9)
10
11// Replace nested catchTag chains
12// BEFORE: effect.pipe(catchTag("A", ...), catchTag("B", ...), catchTag("C", ...))
13// AFTER:
14Effect.catchAll(effect, (error) =>
15  Match.value(error).pipe(
16    Match.tag("A", handleA),
17    Match.tag("B", handleB),
18    Match.tag("C", handleC),
19    Match.exhaustive
20  )
21)
22
23// Match on values (cleaner than if/else)
24const describe = Match.value(status).pipe(
25  Match.when("pending", () => "Loading..."),
26  Match.when("success", () => "Done!"),
27  Match.orElse(() => "Unknown")
28)

Services and Layers

typescript
1// Pattern 1: Context.Tag (implementation provided separately via Layer)
2class MyService extends Context.Tag("MyService")<MyService, { ... }>() {}
3const MyServiceLive = Layer.succeed(MyService, { ... })
4Effect.provide(effect, MyServiceLive)
5
6// Pattern 2: Effect.Service (default implementation bundled)
7class UserRepo extends Effect.Service<UserRepo>()("UserRepo", {
8  effect: Effect.gen(function* () {
9    const db = yield* Database
10    return { findAll: db.query("SELECT * FROM users") }
11  }),
12  dependencies: [Database.Default],  // Optional service dependencies
13  accessors: true                     // Auto-generate method accessors
14}) {}
15Effect.provide(effect, UserRepo.Default)  // .Default layer auto-generated
16// Use UserRepo.DefaultWithoutDependencies when deps provided separately
17
18// Effect.Service with parameters (3.16.0+)
19class ConfiguredApi extends Effect.Service<ConfiguredApi>()("ConfiguredApi", {
20  effect: (config: { baseUrl: string }) =>
21    Effect.succeed({ fetch: (path: string) => `${config.baseUrl}/${path}` })
22}) {}
23
24// Pattern 3: Context.Reference (defaultable tags - 3.11.0+)
25class SpecialNumber extends Context.Reference<SpecialNumber>()(
26  "SpecialNumber",
27  { defaultValue: () => 2048 }
28) {}
29// No Layer required if default value suffices
30
31// Pattern 4: Context.ReadonlyTag (covariant - 3.18.0+)
32// Use for functions that consume services without modifying the type
33function effectHandler<I, A, E, R>(service: Context.ReadonlyTag<I, Effect.Effect<A, E, R>>) {
34  // Handler can use service in a covariant position
35}

Generator Pattern

typescript
1Effect.gen(function* () {
2  const a = yield* effectA;
3  const b = yield* effectB;
4  if (error) {
5    return yield* Effect.fail(new MyError());
6  }
7  return result;
8});
9
10// Effect.fn - automatic tracing and telemetry (preferred for named functions)
11const fetchUser = Effect.fn("fetchUser")(function* (id: string) {
12  const db = yield* Database
13  return yield* db.query(id)
14})
15// Creates spans, captures call sites, provides better stack traces

Resource Management

typescript
1Effect.acquireUseRelease(acquire, use, release)  // Bracket pattern
2Effect.scoped(effect)                            // Scope lifetime to effect
3Effect.addFinalizer(cleanup)                     // Register cleanup action

Duration

Effect accepts human-readable duration strings anywhere a DurationInput is expected:

typescript
1// String syntax (preferred) - singular or plural forms work
2Duration.toMillis("5 minutes")    // 300000
3Duration.toMillis("1 minute")     // 60000
4Duration.toMillis("30 seconds")   // 30000
5Duration.toMillis("100 millis")   // 100
6
7// Verbose syntax (avoid)
8Duration.toMillis(Duration.minutes(5))  // Same result, more verbose
9
10// Common units: millis, seconds, minutes, hours, days, weeks
11// Also: nanos, micros

Scheduling

typescript
1Effect.retry(effect, Schedule.exponential("100 millis"))  // Retry with backoff
2Effect.repeat(effect, Schedule.fixed("1 second"))         // Repeat on schedule
3Schedule.compose(s1, s2)                                  // Combine schedules

State Management

typescript
1Ref.make(initialValue)       // Mutable reference
2Ref.get(ref)                 // Read value
3Ref.set(ref, value)          // Write value
4Deferred.make<E, A>()        // One-time async value

SubscriptionRef (Reactive References)

typescript
1// WARNING: Never use unsafeMake - it may not exist in your Effect version.
2// If you see "unsafeMake is not a function", use the safe API below.
3
4SubscriptionRef.make(initial)      // Create reactive reference (safe)
5SubscriptionRef.get(ref)           // Read current value
6SubscriptionRef.set(ref, value)    // Update value (notifies subscribers)
7SubscriptionRef.changes(ref)       // Stream of value changes
8
9// React integration (effect-atom pattern)
10const ref = yield* SubscriptionRef.make<User | null>(null)
11// Hook reads: useSubscriptionRef(ref) — returns current value or null
12// Handle null explicitly in components

Concurrency

typescript
1Effect.fork(effect)              // Run in background fiber
2Fiber.join(fiber)                // Wait for fiber result
3Effect.race(effect1, effect2)    // First to complete wins
4Effect.all([...effects], { concurrency: "unbounded" })

Configuration & Environment Variables

typescript
1import { Config, ConfigProvider, Effect, Layer, Redacted } from "effect"
2
3// Basic config values
4const port = Config.number("PORT")                    // Required number
5const host = Config.string("HOST").pipe(              // Optional with default
6  Config.withDefault("localhost")
7)
8
9// Sensitive values (masked in logs)
10const apiKey = Config.redacted("API_KEY")             // Returns Redacted<string>
11const secret = Redacted.value(yield* apiKey)          // Unwrap when needed
12
13// Nested configuration with prefix
14const dbConfig = Config.all({
15  host: Config.string("HOST"),
16  port: Config.number("PORT"),
17  name: Config.string("NAME"),
18}).pipe(Config.nested("DATABASE"))                    // DATABASE_HOST, DATABASE_PORT, etc.
19
20// Using config in effects
21const program = Effect.gen(function* () {
22  const p = yield* Config.number("PORT")
23  const key = yield* Config.redacted("API_KEY")
24  return { port: p, apiKey: Redacted.value(key) }
25})
26
27// Custom config provider (e.g., from object instead of env)
28const customProvider = ConfigProvider.fromMap(
29  new Map([["PORT", "3000"], ["API_KEY", "secret"]])
30)
31const withCustomConfig = Effect.provide(
32  program,
33  Layer.setConfigProvider(customProvider)
34)
35
36// Config validation and transformation
37const validPort = Config.number("PORT").pipe(
38  Config.validate({
39    message: "Port must be between 1 and 65535",
40    validation: (n) => n >= 1 && n <= 65535,
41  })
42)

Array Operations

typescript
1import { Array as Arr, Order } from "effect"
2
3// Sorting with built-in orderings (accepts any Iterable)
4Arr.sort([3, 1, 2], Order.number)              // [1, 2, 3]
5Arr.sort(["b", "a", "c"], Order.string)        // ["a", "b", "c"]
6Arr.sort(new Set([3n, 1n, 2n]), Order.bigint)  // [1n, 2n, 3n]
7
8// Sort by derived value
9Arr.sortWith(users, (u) => u.age, Order.number)
10
11// Sort by multiple criteria
12Arr.sortBy(
13  users,
14  Order.mapInput(Order.number, (u: User) => u.age),
15  Order.mapInput(Order.string, (u: User) => u.name)
16)
17
18// Built-in orderings: Order.string, Order.number, Order.bigint, Order.boolean, Order.Date
19// Reverse ordering: Order.reverse(Order.number)

Utility Functions

typescript
1import { constVoid as noop } from "effect/Function"
2
3// constVoid returns undefined, useful as a no-operation callback
4noop()  // undefined
5
6// Common use cases:
7Effect.tap(effect, noop)              // Ignore value, just run effect
8Promise.catch(noop)                   // Swallow errors
9eventEmitter.on("event", noop)        // Register empty handler

Deprecations

• BigDecimal.fromNumber — Use BigDecimal.unsafeFromNumber instead (3.11.0+)
• Schema.annotations() — Now removes previously set identifier annotations; identifiers are tied to the schema's ast reference only (3.17.10)

Additional Resources

Local Effect Resources

• ~/.effect/packages/effect/src/ — Core Effect modules and implementation

External Resources

• Effect-Atom — https://github.com/tim-smart/effect-atom (open in browser for reactive state management patterns)

Reference Files

• ./references/CRITICAL_RULES.md — Forbidden patterns and mandatory conventions
• ./references/EFFECT_ATOM.md — Effect-Atom reactive state management for React
• ./references/NEXT_JS.md — Effect + Next.js 15+ App Router integration patterns
• ./references/OPTION_NULL.md — Option vs null boundary patterns
• ./references/STREAMS.md — Stream patterns and backpressure gotchas
• ./references/TESTING.md — Vitest deterministic testing patterns