effect-patterns

Effect TypeScript Patterns

Type-safe error handling and composable services using Effect as the core type system for Node.js/Bun backends.

Core Stack

Context7 Library IDs

Query these libraries for current best practices:

• Effect: /effect-ts/effect
• Elysia: elysiajs
• Drizzle: /drizzle-team/drizzle-orm

Effect Documentation

Before implementing Effect code, consult:

• AI Documentation: https://effect.website/llms.txt
• Main Docs: https://effect.website/docs

Typed Errors

Define errors as classes extending Schema.TaggedError:

import { Schema } from "effect"

class UserNotFoundError extends Schema.TaggedError<UserNotFoundError>("UserNotFoundError")({
  userId: Schema.String,
}) {}

class ValidationError extends Schema.TaggedError<ValidationError>("ValidationError")({
  message: Schema.String,
  field: Schema.String,
}) {}

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

Services with Context.Tag

Define services with typed interfaces:

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

class UserRepository extends Context.Tag("UserRepository")<
  UserRepository,
  {
    findById: (id: string) => Effect.Effect<User, UserNotFoundError>
    create: (data: CreateUser) => Effect.Effect<User, ValidationError>
  }
>() {}

class DatabaseService extends Context.Tag("DatabaseService")<
  DatabaseService,
  { query: <T>(sql: string) => Effect.Effect<T[], DatabaseError> }
>() {}

Layer Implementation

Implement services with Layer:

const UserRepositoryLive = Layer.succeed(
  UserRepository,
  UserRepository.of({
    findById: (id) => Effect.tryPromise({
      try: () => db.findUser(id),
      catch: () => new UserNotFoundError({ userId: id })
    }),
    create: (data) => Effect.tryPromise({
      try: () => db.createUser(data),
      catch: (e) => new ValidationError({ message: String(e), field: "unknown" })
    })
  })
)

const DatabaseServiceLive = Layer.succeed(
  DatabaseService,
  DatabaseService.of({
    query: (sql) => Effect.tryPromise({
      try: () => db.query(sql),
      catch: (e) => new DatabaseError({ message: String(e) })
    })
  })
)

Effect.gen for Composition

Use generator syntax for composable logic:

const getUser = (id: string) =>
  Effect.gen(function* () {
    const repo = yield* UserRepository
    const user = yield* repo.findById(id)
    return user
  })

const createUserWithAudit = (data: CreateUser) =>
  Effect.gen(function* () {
    const repo = yield* UserRepository
    const user = yield* repo.create(data)
    yield* Effect.log(`Created user: ${user.id}`)
    return user
  })

Schema Validation

Use Effect Schema for validation:

import { Schema } from "effect"

const CreateUserSchema = Schema.Struct({
  name: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(100)),
  email: Schema.String.pipe(Schema.pattern(/^[^@]+@[^@]+\.[^@]+$/)),
  age: Schema.optional(Schema.Number.pipe(Schema.int(), Schema.positive())),
})
type CreateUser = Schema.Schema.Type<typeof CreateUserSchema>

// Validate unknown data
const validateUser = Schema.decodeUnknown(CreateUserSchema)

Error Handling with catchTags

Pattern match on typed errors:

const result = await Effect.runPromise(
  program.pipe(
    Effect.catchTags({
      UserNotFoundError: (e) => Effect.succeed({ error: `User ${e.userId} not found` }),
      ValidationError: (e) => Effect.succeed({ error: `Invalid ${e.field}: ${e.message}` }),
      DatabaseError: (e) => Effect.succeed({ error: `Database error: ${e.message}` }),
    })
  )
)

Retry with Schedule

import { Effect, Schedule } from "effect"

const fetchWithRetry = Effect.retry(
  fetchExternalApi,
  Schedule.exponential("1 second").pipe(Schedule.compose(Schedule.recurs(3)))
)

Elysia + Effect Integration

import { Elysia, t } from "elysia"
import { Effect } from "effect"

const app = new Elysia()
  .post("/api/users", async ({ body }) => {
    const program = Effect.gen(function* () {
      const validated = yield* Schema.decodeUnknown(CreateUserSchema)(body)
      const repo = yield* UserRepository
      return yield* repo.create(validated)
    })
    
    return Effect.runPromise(
      program.pipe(
        Effect.provide(UserRepositoryLive),
        Effect.catchAll((e) => Effect.succeed({ error: e.message }))
      )
    )
  }, {
    body: t.Object({
      name: t.String(),
      email: t.String({ format: "email" }),
    })
  })

Testing with Effect

import { Effect, Layer } from "effect"

const TestUserRepository = Layer.succeed(
  UserRepository,
  UserRepository.of({
    findById: (id) => 
      id === "123" 
        ? Effect.succeed({ id: "123", name: "Test User" })
        : Effect.fail(new UserNotFoundError({ userId: id })),
    create: (data) => Effect.succeed({ id: "new", ...data })
  })
)

// In tests
const result = await Effect.runPromise(
  getUser("123").pipe(Effect.provide(TestUserRepository))
)

Validation Commands

bun tsc --noEmit
bun eslint src/
bun test
bun build src/index.ts --outdir=dist

Guidelines

• Always define typed errors with Schema.TaggedError
• Use Context.Tag for all services
• Implement services with Layer.succeed
• Compose logic with Effect.gen
• Use Schema for all validation
• Pattern match errors with catchTags
• Provide layers at the edge of the application