Designing an Effect-TS backend that tracks errors as types instead of throws, and injects dependencies via Layer

// Old approach: error information disappears entirely from the type
async function fetchUser(id: string): Promise<User> {
  // DB error? Network error? User not found? You can't tell anything.
}
 
// Effect: all possible errors and required dependencies are visible in the signature
const fetchUser = (id: string): Effect.Effect<User, NotFoundError | DbError, Database> => ...

import { Data, Effect } from "effect"
 
class UserNotFoundError extends Data.TaggedError("UserNotFoundError")<{
  userId: string
}> {}
 
class DatabaseConnectionError extends Data.TaggedError("DatabaseConnectionError")<{
  cause: unknown
}> {}
 
// Just reading the signature tells you every error this function can produce
const getUser = (id: string): Effect.Effect<
  User,
  UserNotFoundError | DatabaseConnectionError,
  Database
> =>
  Effect.flatMap(Database, (db) =>
    db.findUser(id).pipe(
      Effect.catchTag("DatabaseConnectionError", () =>
        Effect.fail(new UserNotFoundError({ userId: id }))
      )
    )
  )

import { Context, Effect, Layer } from "effect"
import { Pool } from "pg"
 
// DatabaseConnectionError reuses the class defined in the section above
class Database extends Context.Service<Database>()("Database", {
  effect: Effect.succeed({
    query: (_sql: string) => Effect.succeed([] as unknown[])
  })
}) {}
 
// Production implementation layer — creates and reuses a connection pool at layer initialization
const DatabaseLive = Layer.effect(
  Database,
  Effect.sync(() => {
    const pool = new Pool({ connectionString: process.env.DATABASE_URL })
    return {
      query: (sql: string) =>
        Effect.tryPromise({
          try: () => pool.query(sql).then(r => r.rows as unknown[]),
          catch: (cause) => new DatabaseConnectionError({ cause })
        })
    }
  })
)
 
// Test implementation layer — swapped in without a real DB
const DatabaseTest = Layer.succeed(Database, {
  query: (_sql: string) => Effect.succeed([{ id: "1", name: "Test" }])
})

import { Context, Effect, Layer, Data } from "effect"
 
// Domain error definitions
// DatabaseConnectionError uses the class defined in the "Type-Safe Error Design" section
class UserNotFoundError extends Data.TaggedError("UserNotFoundError")<{
  userId: string
}> {}
 
interface User {
  id: string
  name: string
  email: string
}
 
// Repository service contract — the default implementation is a placeholder for the interface spec
class UserRepository extends Context.Service<UserRepository>()(
  "UserRepository",
  {
    effect: Effect.succeed({
      findById: (_id: string): Effect.Effect<User | null, DatabaseConnectionError> =>
        Effect.succeed(null)
    })
  }
) {}
 
// Production implementation — depends on the Database Layer
const UserRepositoryLive = Layer.effect(
  UserRepository,
  Effect.map(Database, (db) => ({
    findById: (id: string) =>
      db.query(`SELECT * FROM users WHERE id = $1`).pipe(
        Effect.map((rows) => (rows.length > 0 ? (rows[0] as User) : null))
      )
  }))
)
 
// Business logic — signature explicitly declares both errors and dependencies
const getUserOrFail = (
  id: string
): Effect.Effect<User, UserNotFoundError | DatabaseConnectionError, UserRepository> =>
  Effect.flatMap(UserRepository, (repo) =>
    repo.findById(id).pipe(
      Effect.flatMap((user) =>
        user
          ? Effect.succeed(user)
          : Effect.fail(new UserNotFoundError({ userId: id }))
      )
    )
  )

import { Effect, Layer } from "effect"
import { describe, it, expect } from "vitest"
 
// Test layer — returns fixed data
const UserRepositoryTest = Layer.succeed(UserRepository, {
  findById: (id: string) =>
    id === "existing-user"
      ? Effect.succeed({ id, name: "Test User", email: "test@example.com" } as User)
      : Effect.succeed(null)
})
 
describe("getUserOrFail", () => {
  it("returns an existing user", async () => {
    const result = await Effect.runPromise(
      getUserOrFail("existing-user").pipe(
        Effect.provide(UserRepositoryTest)
      )
    )
    expect(result.name).toBe("Test User")
  })
 
  it("returns UserNotFoundError for a missing user", async () => {
    const result = await Effect.runPromise(
      getUserOrFail("ghost").pipe(
        Effect.provide(UserRepositoryTest),
        Effect.flip // flips the error channel to the success channel for assertion
      )
    )
    expect(result._tag).toBe("UserNotFoundError")
    expect(result.userId).toBe("ghost")
  })
})

import { Effect, Layer } from "effect"
 
// UserRepositoryLive depends on DatabaseLive → connect with Layer.provide
const AppLayer = Layer.provide(UserRepositoryLive, DatabaseLive)
 
const getUserProgram = (id: string) =>
  Effect.gen(function* () {
    const user = yield* getUserOrFail(id)
    yield* Effect.log(`User fetched successfully: ${user.name}`)
    return user
  })
 
// At the entry point, handle errors by type and then run
const main = getUserProgram("some-id").pipe(
  Effect.catchTag("UserNotFoundError", (err) =>
    Effect.logWarning(`User does not exist: ${err.userId}`)
  ),
  Effect.catchTag("DatabaseConnectionError", () =>
    Effect.logError("Database connection failed")
  ),
  Effect.provide(AppLayer)
)
 
Effect.runPromise(main)

// Caution: returning Effect.void via catchAll makes user's type User | void
const bad = Effect.gen(function* () {
  const user = yield* getUserOrFail("123").pipe(
    Effect.catchAll(() => Effect.void) // user becomes void
  )
  console.log(user.name) // Type error: void has no property 'name'
})
 
// Handle errors by type, or do a single catch-all at the entry point
const good = getUserOrFail("123").pipe(
  Effect.catchTag("UserNotFoundError", (err) =>
    Effect.logWarning(`User not found: ${err.userId}`).pipe(
      Effect.andThen(Effect.fail(err)) // re-propagate the error
    )
  )
)

import { Effect, Schedule } from "effect"
 
// Assumes ServiceUnavailableError is also defined as a Data.TaggedError
const resilientFetch = getUserOrFail("123").pipe(
  // Retry up to 3 times with 100ms exponential backoff
  Effect.retry(Schedule.exponential("100 millis").pipe(Schedule.take(3))),
  // 5-second timeout
  Effect.timeout("5 seconds"),
  // Convert timeout to a custom error
  Effect.catchTag("TimeoutException", () => Effect.fail(new ServiceUnavailableError()))
)

import { Effect } from "effect"
 
const getUserWithTracing = (id: string) =>
  getUserOrFail(id).pipe(
    Effect.withSpan("user.getById", {
      attributes: { "user.id": id }
    })
  )
 
// Nested spans naturally form a parent-child hierarchy
// getOrder and fulfillOrder are assumed to be other domain Effect functions with the same pattern
const processOrder = (orderId: string) =>
  Effect.gen(function* () {
    const order = yield* getOrder(orderId)           // example: order-fetching Effect
    const user = yield* getUserWithTracing(order.userId)
    return yield* fulfillOrder(order, user)          // example: order-processing Effect
  }).pipe(Effect.withSpan("order.process"))

// Bad pattern — breaks out of the Effect runtime mid-computation
const bad = async () => {
  const user = await Effect.runPromise(getUser("123"))
  const order = await Effect.runPromise(getOrder(user.id))
}
 
// Good pattern — keep the Effect chain connected to the end, run once at the entry point
const good = Effect.gen(function* () {
  const user = yield* getUser("123")
  const order = yield* getOrder(user.id)
  return order
})

// Bad pattern — catchAll turns every error into null
const bad = getUser("123").pipe(
  Effect.catchAll(() => Effect.succeed(null))
)
 
// Good pattern — handle errors appropriately by type
const good = getUser("123").pipe(
  Effect.catchTag("UserNotFoundError", () => Effect.succeed(defaultUser)),
  Effect.catchTag("DatabaseConnectionError", (err) =>
    Effect.logError("DB connection failed").pipe(
      Effect.andThen(Effect.fail(new ServiceUnavailableError()))
    )
  )
)