클래스: AsyncRetryer<TFn>

정의 위치: async-retryer.ts:298

비동기 함수를 위한 강력한 재시도 기능을 제공하며, 구성 가능한 백오프 전략, 시도 횟수 제한, 타임아웃 제어 및 상세한 상태 관리를 지원합니다. AsyncRetryer 클래스는 네트워크 요청이나 데이터베이스 작업처럼 간헐적으로 실패할 수 있는 비동기 작업을 선택한 정책에 따라 자동으로 재시도하여 안정적으로 실행할 수 있도록 설계되었습니다.

재시도 개념

• 재시도: 실패한 비동기 함수를 지정된 최대 시도 횟수까지 자동으로 다시 실행합니다. 일시적인 오류(예: 불안정한 네트워크, 요청률 제한, 일시적인 서버 문제)를 처리하는 데 유용합니다.
• 백오프 전략: 재시도 사이의 지연 시간을 제어합니다(기본값: 'exponential').
  • 'exponential': 시도할 때마다 대기 시간이 두 배로 증가합니다(1초, 2초, 4초, ...) - 기본값
  • 'linear': 대기 시간이 선형으로 증가합니다(1초, 2초, 3초, ...).
  • 'fixed': 각 시도 사이에 일정한 시간(baseWait) 동안 대기합니다.
• 지터: 동시 요청 폭주 문제를 방지하기 위해 재시도 지연에 무작위성을 추가합니다(기본값: 0). 0~1 사이의 값으로 설정하면 각 지연 시간에 해당 비율만큼 무작위 변동을 적용합니다.
• 최대 대기 시간: 재시도 사이의 최대 대기 시간을 제한합니다(기본값: Infinity). 지수 백오프가 지나치게 증가하는 것을 방지하는 데 유용합니다(예: 지수 백오프 결과가 64초여도 30초로 제한).
• 타임아웃 제어: 작업이 끝나지 않고 멈추는 것을 방지하도록 실행 시간 제한을 설정합니다.
  • maxExecutionTime: 단일 함수 호출의 최대 시간입니다(기본값: Infinity).
  • maxTotalExecutionTime: 전체 재시도 작업의 최대 시간입니다(기본값: Infinity).
• 중단 및 취소: 내부 AbortController를 통한 취소를 지원합니다. 재시도를 중지하려면 abort()를 호출합니다. 비동기 함수를 실제로 취소할 수 있게 하려면 getAbortSignal()을 사용합니다(예: fetch 요청).

상태 관리

세분화된 반응성을 위해 TanStack Store를 사용합니다. store.state 속성을 통해 상태에 접근할 수 있습니다.

사용 가능한 상태 속성:

• currentAttempt: 현재 재시도 회차입니다(실행 중이 아닐 때는 0).
• executionCount: 완료된 전체 실행 횟수입니다(성공 또는 실패).
• isExecuting: 재시도 처리기가 현재 함수를 실행 중인지 나타냅니다.
• lastError: 실행 중 발생한 가장 최근 오류입니다.
• lastExecutionTime: 가장 최근 실행이 완료된 시점의 타임스탬프이며 단위는 밀리초입니다.
• lastResult: 가장 최근에 성공한 실행의 결과입니다.
• status: 현재 실행 상태입니다('disabled' | 'idle' | 'executing' | 'retrying').
• totalExecutionTime: 재시도를 포함하여 실행에 소요된 총시간이며 단위는 밀리초입니다.

오류 처리

throwOnError 옵션은 오류를 발생시키는 시점을 제어합니다(기본값: 'last').

• 'last': 모든 재시도를 소진한 후 최종 오류만 발생시킵니다. - 기본값
• true: 모든 오류를 즉시 발생시킵니다(재시도 비활성화).
• false: 오류를 발생시키지 않고 대신 undefined를 반환합니다.

수명 주기 관리를 위한 콜백:

• onAbort: 수동으로 또는 타임아웃으로 인해 실행이 중단되었을 때 호출합니다.
• onError: 재시도 중 발생한 오류를 포함하여 모든 오류마다 호출합니다.
• onLastError: 모든 재시도가 실패한 후 최종 오류에 대해서만 호출합니다.
• onRetry: 각 재시도 전에 호출합니다.
• onSettled: 각 시도의 실행이 완료(성공 또는 실패)된 후 호출합니다.
• onSuccess: 실행이 성공했을 때 호출합니다.
• onExecutionTimeout: 단일 실행 시도에서 타임아웃이 발생했을 때 호출합니다.
• onTotalExecutionTimeout: 전체 실행 시간에서 타임아웃이 발생했을 때 호출합니다.

사용법

• 일시적으로 실패할 수 있고 재시도가 유용한 비동기 작업에 사용합니다.
• 재시도 동작을 제어하려면 maxAttempts, backoff, baseWait, maxWait 및 jitter를 구성합니다.
• 작업이 끝나지 않고 멈추는 것을 방지하려면 maxExecutionTime과 maxTotalExecutionTime을 설정합니다.
• 사용자 정의 부수 효과를 구현하려면 onAbort, onError, onLastError, onRetry, onSettled, onSuccess, onExecutionTimeout 및 onTotalExecutionTimeout을 사용합니다.
• 진행 중인 실행과 대기 중인 재시도를 취소하려면 abort()를 호출합니다.
• 상태를 재설정하고 실행을 취소하려면 reset()을 호출합니다.
• 비동기 함수를 취소할 수 있게 하려면 getAbortSignal()을 사용합니다.
• 재시도 처리기 상태를 기준으로 maxAttempts, baseWait 및 enabled에 동적 옵션(함수)을 사용합니다.

중요: 이 클래스는 단일 실행 용도로 설계되었습니다. 동일한 인스턴스에서 execute()를 여러 번 호출하면 이전 실행이 중단됩니다. 여러 번 호출하려면 매번 새 인스턴스를 생성합니다.

예시

// Retry a fetch operation up to 5 times with exponential backoff, jitter, and timeouts
const retryer = new AsyncRetryer(async (url: string) => {
  const signal = retryer.getAbortSignal()
  return await fetch(url, { signal })
}, {
  maxAttempts: 5,
  backoff: 'exponential',
  baseWait: 1000,
  jitter: 0.1, // Add 10% random variation to prevent thundering herd
  maxExecutionTime: 5000, // Abort individual calls after 5 seconds
  maxTotalExecutionTime: 30000, // Abort entire operation after 30 seconds
  onRetry: (attempt, error) => console.log(`Retry attempt ${attempt} after error:`, error),
  onSuccess: (result) => console.log('Success:', result),
  onError: (error) => console.error('Error:', error),
  onLastError: (error) => console.error('All retries failed:', error),
})

const result = await retryer.execute('/api/data')

타입 매개변수

TFn

TFn 확장 AnyAsyncFunction

재시도할 비동기 함수 타입입니다.

생성자

생성자

new AsyncRetryer<TFn>(fn, initialOptions): AsyncRetryer<TFn>;

정의 위치: async-retryer.ts:311

새 AsyncRetryer 인스턴스를 생성합니다.

매개변수

fn

TFn

재시도할 비동기 함수입니다.

initialOptions

AsyncRetryerOptions<TFn> = {}

재시도 처리기의 구성 옵션입니다.

반환값

AsyncRetryer<TFn>

속성

fn

fn: TFn;

정의 위치: async-retryer.ts:312

재시도할 비동기 함수입니다.

---

key

key: string | undefined;

정의 위치: async-retryer.ts:302

---

options

options: AsyncRetryerOptions<TFn> & Omit<Required<AsyncRetryerOptions<any>>, 
  | "initialState"
  | "key"
  | "onAbort"
  | "onError"
  | "onLastError"
  | "onRetry"
  | "onSettled"
  | "onSuccess"
  | "onExecutionTimeout"
| "onTotalExecutionTimeout">;

정의 위치: async-retryer.ts:303

---

store

readonly store: Store<Readonly<AsyncRetryerState<TFn>>>;

정의 위치: async-retryer.ts:299

메서드

abort()

abort(reason): void;

정의 위치: async-retryer.ts:612

현재 실행과 대기 중인 모든 재시도를 취소합니다.

매개변수

reason

중단 사유입니다(기본값은 'manual').

"manual" | "execution-timeout" | "total-timeout" | "new-execution"

반환값

void

---

execute()

execute(...args): Promise<Awaited<ReturnType<TFn>> | undefined>;

정의 위치: async-retryer.ts:419

재시도 로직을 적용하여 함수를 실행합니다.

매개변수

args

...Parameters<TFn>

함수에 전달할 인수입니다.

반환값

Promise<Awaited<ReturnType<TFn>> | undefined>

함수 결과를 반환합니다. 비활성화된 경우 또는 throwOnError가 false이고 모든 재시도가 실패한 경우에는 undefined를 반환합니다.

발생 오류

throwOnError가 true이고 모든 재시도가 실패하면 마지막 오류가 발생합니다.

---

getAbortSignal()

getAbortSignal(): AbortSignal | null;

정의 위치: async-retryer.ts:604

실행 중인 작업의 현재 AbortSignal을 반환합니다. 비동기 함수를 취소할 수 있게 하려면 해당 함수에서 이 신호를 사용합니다. 현재 실행 중이 아니면 null을 반환합니다.

반환값

AbortSignal | null

예시

const retryer = new AsyncRetryer(async (userId: string) => {
  const signal = retryer.getAbortSignal()
  if (signal) {
    return fetch(`/api/users/${userId}`, { signal })
  }
  return fetch(`/api/users/${userId}`)
})

// Abort will now actually cancel the fetch
retryer.abort()

---

reset()

reset(): void;

정의 위치: async-retryer.ts:632

재시도 처리기를 초기 상태로 재설정합니다.

반환값

void

---

setOptions()

setOptions(newOptions): void;

정의 위치: async-retryer.ts:330

재시도 처리기 옵션을 업데이트합니다.

매개변수

newOptions

Partial<AsyncRetryerOptions<TFn>>

기존 옵션과 병합할 부분 옵션입니다.

반환값

void