TypeScript 백엔드에서 에러 정보를 타입에 담는 법: Effect-TS 실전 가이드

Effect<A, E, R>
//     ↑  ↑  ↑
//     │  │  └── Requirements: 실행에 필요한 서비스(의존성) 목록
//     │  └───── Error: 발생 가능한 예상 에러 타입의 union
//     └──────── Success: 성공 시 반환값 타입

// 기존 방식 — 에러 정보가 타입에 없음
async function fetchUser(id: string): Promise<User> { ... }
 
// Effect 방식 — 에러와 의존성이 타입에 드러남
const fetchUser = (id: string): Effect.Effect<User, NotFoundError | DatabaseError, DatabaseService> => ...

// Expected Error — E 슬롯에 기록, catchTag로 처리 가능
const findUser = (id: string) =>
  id === "" ? Effect.fail(new NotFoundError({ id })) : Effect.succeed({ id, name: "Alice" })
// 타입: Effect<{ id: string; name: string }, NotFoundError, never>
 
// Defect — E 슬롯에 기록되지 않음
const badDivide = (a: number, b: number) =>
  b === 0
    ? Effect.die("0으로 나눌 수 없음")
    : Effect.succeed(a / b)
// 타입: Effect<number, never, never>  ← 에러가 E에 보이지 않음!
 
// 외부 라이브러리 throw를 Expected Error로 변환하려면 tryPromise 사용
const queryDb = (sql: string) =>
  Effect.tryPromise({
    try: () => pool.query(sql),
    catch: (err) => new DatabaseError({ message: String(err) }),  // E 슬롯에 기록됨
  })

import { Data, Effect } from "effect"
 
class NotFoundError extends Data.TaggedError("NotFoundError")<{
  id: string
}> {}
 
class DatabaseError extends Data.TaggedError("DatabaseError")<{
  message: string
  cause?: unknown
}> {}

const findUser = (id: string) =>
  Effect.gen(function* () {
    const db = yield* DatabaseService
    const row = yield* db.query(`SELECT * FROM users WHERE id = $1`, [id])
 
    if (!row) {
      return yield* Effect.fail(new NotFoundError({ id }))
    }
 
    return row as User
  })
// 반환 타입: Effect<User, NotFoundError | DatabaseError, DatabaseService>

const result = yield* findUser("123").pipe(
  Effect.catchTag("NotFoundError", (err) =>
    Effect.succeed({ id: err.id, name: "Unknown" })
  ),
  Effect.catchTag("DatabaseError", (err) => {
    console.error(`DB 에러: ${err.message}`)
    return Effect.fail(new ServiceUnavailableError())
  })
)

import { Effect, Layer } from "effect"
 
class DatabaseService extends Effect.Service<DatabaseService>()(
  "DatabaseService",
  {
    effect: Effect.gen(function* () {
      // 기본 스텁 — 실제 앱에서는 PgDatabaseLayer로 반드시 교체
      return {
        query: (_sql: string, _params: unknown[]): Effect.Effect<unknown[], DatabaseError> =>
          Effect.die("DatabaseService not provided"),
      }
    }),
  }
) {}

// PostgreSQL 구현 레이어
const PgDatabaseLayer = Layer.effect(
  DatabaseService,
  Effect.gen(function* () {
    const config = yield* AppConfig  // 이 Layer가 AppConfig에 의존함을 타입으로 선언
    const pool = new Pool({ connectionString: config.databaseUrl })
 
    return {
      query: (sql: string, params: unknown[]) =>
        Effect.tryPromise({
          try: () => pool.query(sql, params),
          catch: (err) => new DatabaseError({ message: String(err) }),
        }),
    }
  })
)
 
// 테스트용 인메모리 레이어
const InMemoryDatabaseLayer = Layer.succeed(DatabaseService, {
  query: (_sql, _params) => Effect.succeed([{ id: "1", name: "test" }]),
})

const AppLayer = Layer.mergeAll(
  PgDatabaseLayer,      // 내부에서 AppConfig를 yield*로 참조
  HttpClientLayer,
  LoggerLayer,
  AppConfigLayer        // PgDatabaseLayer가 필요로 하는 의존성
)
 
Effect.runPromise(
  mainProgram.pipe(Effect.provide(AppLayer))
)

// async/await 버전
async function createOrder(data: OrderData) {
  const user = await getUser(data.userId)
  const stock = await checkStock(data.itemId)
  if (stock < data.quantity) throw new InsufficientStockError()
  return await saveOrder({ user, ...data })
}
 
// Effect.gen 버전
const createOrder = (data: OrderData) =>
  Effect.gen(function* () {
    const user = yield* getUser(data.userId)
    const stock = yield* checkStock(data.itemId)
    if (stock < data.quantity) {
      return yield* Effect.fail(new InsufficientStockError({ available: stock }))
    }
    return yield* saveOrder({ user, ...data })
  })

import {
  HttpRouter, HttpServer, HttpServerRequest,
  HttpServerResponse, HttpMiddleware
} from "@effect/platform"
import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
import { Effect, Schema, Layer } from "effect"
import { createServer } from "node:http"
 
const CreateUserBody = Schema.Struct({
  email: Schema.String.pipe(Schema.pattern(/^[^@]+@[^@]+\.[^@]+$/)),
  name: Schema.String.pipe(Schema.minLength(1)),
})
 
const createUserHandler = Effect.gen(function* () {
  const req = yield* HttpServerRequest.HttpServerRequest
  const body = yield* req.json.pipe(
    Effect.flatMap(Schema.decodeUnknown(CreateUserBody)),
    // JSON 파싱 오류와 스키마 검증 오류를 함께 400으로 처리
    // 두 케이스의 로깅 전략을 달리해야 한다면 mapError 이전에 분리할 것
    Effect.mapError((err) => new ValidationError({ message: String(err) }))
  )
 
  const userService = yield* UserService
  const user = yield* userService.create(body)
 
  return HttpServerResponse.json(user, { status: 201 })
}).pipe(
  Effect.catchTag("ValidationError", (err) =>
    HttpServerResponse.json({ error: err.message }, { status: 400 })
  ),
  Effect.catchTag("DuplicateEmailError", (_err) =>
    HttpServerResponse.json({ error: "이미 사용 중인 이메일입니다." }, { status: 409 })
  ),
  Effect.catchTag("DatabaseError", (err) =>
    Effect.gen(function* () {
      const logger = yield* Logger
      yield* logger.error("DB 에러 발생", { cause: err.message })
      return HttpServerResponse.json({ error: "서버 오류" }, { status: 500 })
    })
  )
)
 
// 라우터에 등록하고 서버 실행
const router = HttpRouter.empty.pipe(
  HttpRouter.post("/users", createUserHandler)
)
 
const app = router.pipe(HttpServer.serve(HttpMiddleware.logger))
const ServerLayer = NodeHttpServer.layer(() => createServer(), { port: 3000 })
 
NodeRuntime.runMain(
  Layer.launch(Layer.provide(app, Layer.merge(ServerLayer, AppLayer)))
)

import { Effect, Layer, Schedule, Data } from "effect"
import { HttpClient } from "@effect/platform"
 
class PaymentGatewayError extends Data.TaggedError("PaymentGatewayError")<{
  statusCode: number
}> {}
 
class PaymentService extends Effect.Service<PaymentService>()(
  "PaymentService",
  {
    effect: Effect.gen(function* () {
      return {
        charge: (_amount: number, _currency: string): Effect.Effect<ChargeResult, PaymentGatewayError> =>
          Effect.die("PaymentService.Live가 제공되지 않았습니다"),
      }
    }),
  }
) {
  static readonly Live = Layer.effect(
    PaymentService,
    Effect.gen(function* () {
      const httpClient = yield* HttpClient.HttpClient  // Layer 레벨에서 주입
 
      return {
        charge: (amount: number, currency: string) =>
          httpClient.post("https://api.payment.example/charge").pipe(
            Effect.flatMap((res) =>
              res.status >= 400
                ? Effect.fail(new PaymentGatewayError({ statusCode: res.status }))
                : res.json  // res.json은 Effect이므로 flatMap 체인에서 자연스럽게 처리됨
            ),
            // 지수 백오프 재시도 — 선언적으로 표현
            Effect.retry(
              Schedule.exponential("100 millis").pipe(
                Schedule.intersect(Schedule.recurs(3))
              )
            )
          ),
      }
    })
  )
}

import { Either } from "effect"
 
const TestLayer = Layer.mergeAll(
  InMemoryDatabaseLayer,
  MockPaymentServiceLayer,
  ConsoleLoggerLayer
)
 
const ProductionLayer = Layer.mergeAll(
  PgDatabaseLayer,
  PaymentService.Live,
  StructuredLoggerLayer
)
 
// 테스트
describe("createOrder", () => {
  it("재고 부족 시 InsufficientStockError를 반환한다", async () => {
    const result = await Effect.runPromise(
      createOrder({ itemId: "item-1", quantity: 999 }).pipe(
        Effect.provide(TestLayer),
        Effect.either
      )
    )
 
    // Either.isLeft로 타입 좁히기 — as any 없이 타입 안전하게 검증
    expect(Either.isLeft(result)).toBe(true)
    if (Either.isLeft(result)) {
      expect(result.left._tag).toBe("InsufficientStockError")
    }
  })
})

const getDashboardData = (userId: string) =>
  Effect.gen(function* () {
    const [orders, notifications, profile] = yield* Effect.all(
      [
        orderService.getRecent(userId),
        notificationService.getUnread(userId),
        userService.getProfile(userId),
      ],
      { concurrency: 3 }
    )
 
    return { orders, notifications, profile }
  })