Effect-TS Best Practices

Opinionated patterns for Effect-TS codebases. Effect provides typed functional programming with composable errors, dependency injection, and observability.

Critical Rules

1. NEVER use any or type casts (as Type) – Use Schema.make() for branded types, Schema.decodeUnknown() for parsing
2. Don’t use catchAll when error type is never – No errors to catch
3. Never use global Error in Effect channels – Use Schema.TaggedError for domain errors
4. Ban { disableValidation: true } – Lint against this
5. Don’t wrap safe operations in Effect – Only use Effect.try() for throwing operations
6. Use mapError not catchAllCause – Distinguish expected errors from bugs
7. Never silently swallow errors – Failures MUST be visible in the Effect’s error channel E

Quick Reference

Service Pattern

class UserService extends Effect.Service<UserService>()("UserService", {
  dependencies: [DatabaseService.Default],
  effect: Effect.gen(function* () {
    const db = yield* DatabaseService

    return {
      findById: Effect.fn("UserService.findById")(
        (id: UserId) => db.query(/* ... */)
      ),
    }
  }),
}) {}

// Usage - dependencies auto-provided
UserService.findById(userId)

Error Handling

// Define domain-specific errors
class UserNotFoundError extends Schema.TaggedError<UserNotFoundError>()(
  "UserNotFoundError",
  { userId: UserId, message: Schema.String }
) {}

// Handle with catchTag (preserves type info)
effect.pipe(
  Effect.catchTag("UserNotFoundError", (e) => /* handle */),
  Effect.catchTag("AuthExpiredError", (e) => /* handle */)
)

Schema Pattern

// Branded ID
const UserId = Schema.String.pipe(Schema.brand("@App/UserId"))

// Domain entity with Schema.Class
class User extends Schema.Class<User>("User")({
  id: UserId,
  email: Schema.String,
  createdAt: Schema.DateFromSelf,
}) {
  get displayName() { return this.email.split("@")[0] }
}

Layer Composition

// Declare dependencies in service, not at usage
const MainLayer = Layer.mergeAll(
  UserServiceLive,
  AuthServiceLive,
  DatabaseLive
)

// Run program
Effect.runPromise(program.pipe(Effect.provide(MainLayer)))

Detailed Guides

• Anti-Patterns – Forbidden patterns with fixes
• Error Patterns – Domain errors, rich context, HTTP mapping
• Schema Patterns – Branded types, transforms, validation
• Service Patterns – Effect.Service, dependency injection
• Layer Patterns – Composition, memoization, testing
• Observability Patterns – Logging, tracing, metrics
• SQL Patterns – Database integration, transactions
• Testing Patterns – effect-vitest, property testing, Testcontainers
• Atom Patterns – React state management with Effect
• RPC & Cluster Patterns – Distributed systems