Effect란? 타입스크립트에서 비동기 작업과 오류를 다루는 방법

Effect란? 타입스크립트에서 비동기 작업과 오류를 다루는 방법

API 요청은 성공할 수도 있고, 네트워크 오류나 예상과 다른 응답 때문에 실패할 수도 있습니다. 일반적인 Promise<Product>는 성공 결과의 타입을 알려주지만, 어떤 예외가 발생할 수 있는지는 타입에 나타내지 않습니다. 작업이 많아질수록 오류 처리와 의존성 관리가 여러 곳에 흩어지기 쉽습니다.

Effect 공식 웹사이트에서 소개하는 Effect는 이런 작업을 조합할 수 있도록 설계된 TypeScript 라이브러리입니다.[1] 이 글에서는 Effect의 기본 개념을 알아보고, API에서 상품을 가져와 가격을 계산하는 예제를 직접 실행합니다.

Effect는 무엇을 표현하나요?

Effect의 핵심 타입은 Effect<Success, Error, Requirements>입니다. 성공하면 무엇을 반환하는지, 예상 가능한 오류가 무엇인지, 실행에 어떤 서비스가 필요한지를 표현합니다.[3]

  • Success: 성공 시 값의 타입입니다.
  • Error: 명시적으로 모델링한 예상 오류의 타입입니다. 모든 런타임 예외가 자동으로 여기에 들어가는 것은 아닙니다.
  • Requirements: 실행 전에 제공해야 하는 서비스 의존성입니다. never는 해당 타입 채널에 값이나 요구사항이 없다는 뜻입니다.

Effect 공식 문서에서 성공, 오류, 의존성 순서로 표시한 Effect 타입

Effect 공식 문서의 타입 설명. 세 매개변수의 순서를 확인할 수 있습니다. (출처: Effect, 2026-11-20 캡처)

Effect 값은 작업의 설명이며 생성하는 순간 자동 실행되지 않습니다. Effect.runPromise 같은 실행 함수를 호출할 때 작업이 수행됩니다.[3] 이 성질 덕분에 작업을 먼저 조합한 뒤 애플리케이션 경계에서 실행할 수 있습니다.

설치와 실행 준비

다음 예제는 Effect 4.1.4, TypeScript의 strict 검사, Node.js 26에서 실행했습니다. Effect v4 공식 문서는 TypeScript 5.9 이상을 요구합니다.[2] 다른 주요 버전의 문서나 예제는 API가 다를 수 있으므로 버전을 확인하세요.

mkdir effect-example && cd effect-example
npm init -y
npm pkg set type=module
npm install effect@4.1.4
npm install --save-dev typescript tsx

다음 코드를 main.ts에 저장합니다. 예제의 상품 데이터는 테스트용 공개 API인 DummyJSON에서 가져옵니다.[7] 네트워크 연결이 필요하며 실제 가격과 상품 데이터는 바뀔 수 있습니다.

import { Data, Effect } from "effect"

class InvalidPrice extends Data.TaggedError("InvalidPrice")<{ readonly price: number }> {}
class ApiError extends Data.TaggedError("ApiError")<{ readonly message: string }> {}

type Product = { id: number; title: string; price: number }

const parseProduct = (input: unknown): Effect.Effect<Product, ApiError> => {
  if (typeof input !== "object" || input === null) return Effect.fail(new ApiError({ message: "Invalid response" }))
  const item = input as Record<string, unknown>
  if (typeof item.id !== "number" || typeof item.title !== "string" || typeof item.price !== "number") {
    return Effect.fail(new ApiError({ message: "Invalid response" }))
  }
  return Effect.succeed({ id: item.id, title: item.title, price: item.price })
}

const loadProduct = (id: number) => Effect.tryPromise({
  try: async () => {
    const response = await fetch(`https://dummyjson.com/products/${id}`)
    if (!response.ok) throw new Error(`HTTP ${response.status}`)
    return response.json() as Promise<unknown>
  },
  catch: (error) => new ApiError({ message: String(error) })
}).pipe(Effect.flatMap(parseProduct))

const applyDiscount = (price: number): Effect.Effect<number, InvalidPrice> =>
  price < 0 ? Effect.fail(new InvalidPrice({ price })) : Effect.succeed(price * 0.9)

const productSummary = (id: number) => Effect.gen(function* () {
  const product = yield* loadProduct(id)
  const discounted = yield* applyDiscount(product.price)
  return `${product.title}: $${discounted.toFixed(2)}`
})

const program = productSummary(1).pipe(
  Effect.catch((error) => Effect.succeed(`Unable to calculate price: ${error._tag}`))
)

console.log(await Effect.runPromise(program))
console.log(await Effect.runPromise(applyDiscount(-1).pipe(Effect.catch((error) => Effect.succeed(error._tag)))))
console.log(await Effect.runPromise(parseProduct({ id: 1 }).pipe(Effect.catch((error) => Effect.succeed(error._tag)))))

타입을 검사한 뒤 실행합니다.

npx tsc --strict --noEmit --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext main.ts
npx tsx main.ts

검증 시 출력은 다음과 같았습니다. 첫 줄은 API 데이터나 네트워크 상태에 따라 달라집니다.

Essence Mascara Lash Princess: $8.99
InvalidPrice
ApiError

코드의 흐름 살펴보기

  1. Effect.tryPromise는 실패할 수 있는 비동기 요청을 감싸고, 네트워크·HTTP·JSON 처리 오류를 ApiError로 변환합니다.[6] fetch는 404 같은 HTTP 상태만으로는 일반적으로 reject하지 않으므로 response.ok를 별도로 검사합니다.
  2. parseProduct는 외부 응답을 unknown으로 받아 필요한 필드의 타입을 확인합니다. TypeScript 타입 선언만으로 서버 응답이 검증되지는 않습니다. 이 예제의 검사는 간단한 데모이며, 범위·정밀도 등 더 엄격한 비즈니스 검증은 별도로 필요합니다.
  3. applyDiscount는 음수 가격을 InvalidPrice로 표현합니다. 금액 계산은 이해를 돕기 위한 예시입니다. 실제 결제에서는 통화의 최소 단위나 적절한 십진 계산 및 반올림 정책이 필요합니다.
  4. Effect.gen 안에서 yield*로 각 작업을 순서대로 연결합니다. 앞 작업이 예상 오류로 실패하면 뒤 작업은 실행되지 않습니다.[4] productSummary의 오류 타입에는 ApiError | InvalidPrice가 추론됩니다.
  5. Effect.catch는 이 예제의 예상 오류를 복구하고 Effect.runPromise가 실행합니다. 예상 오류 외의 결함이나 중단까지 모두 안전하게 처리한다는 뜻은 아닙니다.[5] 마지막 두 줄은 각각 음수 가격과 잘못된 응답을 직접 확인합니다.

어디에 활용할 수 있나요?

  • API 연동: 네트워크 실패, 응답 검증 실패, 도메인 오류를 구분해 상위 작업으로 전달할 수 있습니다.
  • 여러 단계의 비즈니스 로직: 검증, 외부 호출, 결과 변환을 한 흐름으로 조합하고 각 단계의 실패를 추적할 수 있습니다.
  • 의존성 관리와 테스트: 외부 서비스 같은 요구사항을 타입으로 표현하고 실행 시 구현을 제공할 수 있습니다. 테스트에서는 같은 인터페이스의 대체 구현을 사용할 수 있습니다.[8]
  • 비동기 작업 운영: 재시도, 동시성 제어, 리소스 정리, 로깅 같은 기능을 하나의 생태계에서 살펴볼 수 있습니다.[1] 재시도는 중복 실행해도 안전한 작업인지 먼저 확인해야 합니다.

기존 프로젝트를 한 번에 다시 작성할 필요는 없습니다. 외부 API 호출 한 곳을 Effect.tryPromise로 감싸고, 경계에서 Effect.runPromise로 기존 Promise 기반 코드와 연결하는 작은 실험부터 시작할 수 있습니다.[1]

도입 전에 고려할 점

Effect가 모든 프로젝트에 필요한 것은 아닙니다. 단순한 스크립트라면 async/await와 명시적인 try/catch가 더 읽기 쉽고 의존성도 적을 수 있습니다. 반면 오류 종류와 비동기 흐름이 많고 여러 서비스의 의존성이 얽혀 있다면 일관된 모델을 검토할 가치가 있습니다.

Effect.gen, yield*, 오류 채널, 서비스와 런타임을 팀이 함께 배워야 하고, 기존 코드와의 경계도 설계해야 합니다. 타입이 오류를 표현하더라도 외부 데이터 검증이나 운영 중 관찰이 불필요해지는 것은 아닙니다. 우선 작은 기능에서 팀의 이해도와 유지보수 비용을 확인한 뒤 범위를 넓히는 편이 좋습니다.

Sources

[1] https://effect.website

[2] https://effect.website/docs/v4/getting-started/installation

[3] https://effect.website/docs/v4/getting-started/the-effect-type

[4] https://effect.website/docs/v4/getting-started/using-generators

[5] https://effect.website/docs/v4/error-management/expected-errors

[6] https://effect.website/docs/v4/getting-started/creating-effects

[7] https://dummyjson.com/docs/products

[8] https://effect.website/docs/v4/requirements-management/services