본문으로 건너뛰기

함수: asyncBatch()

function asyncBatch<TValue>(fn, options): (item) => Promise<any>;

정의 위치: async-batcher.ts:588

항목을 배치 단위로 처리하는 비동기 배처를 생성합니다.

비동기 버전과 동기 버전: 비동기 버전은 동기 배치 함수보다 다음과 같은 고급 기능을 제공합니다.

  • 배치 결과를 기다릴 수 있는 프로미스를 반환합니다.
  • AsyncRetryer 통합을 통한 내장 재시도 기능을 제공합니다.
  • 진행 중인 배치 실행을 취소하는 중단 기능을 제공합니다.
  • 대기 중인 배치의 시작을 막는 취소 기능을 제공합니다.
  • onError 콜백과 throwOnError 제어를 통한 포괄적인 오류 처리를 제공합니다.
  • 세부 실행 정보(성공/오류/완료 횟수)를 추적합니다.

비동기 기능, 반환값 또는 실행 제어가 필요하지 않다면 동기 배치 함수가 더 가볍고 간단합니다.

배칭이란? 배칭은 여러 작업을 하나의 단위로 묶어 함께 처리하는 기법입니다.

설정 옵션:

  • maxSize: 배치당 최대 항목 수(기본값: Infinity)
  • wait: 배치 처리 전 대기 시간(기본값: Infinity)
  • getShouldExecute: 배치 처리를 트리거하는 사용자 지정 로직
  • asyncRetryerOptions: 배치 실행의 재시도 동작 설정
  • started: 즉시 처리를 시작할지 여부(기본값: true)

오류 처리:

  • onError 핸들러를 제공하면 오류, 실패한 항목의 배치, 배처 인스턴스와 함께 호출됩니다.
  • throwOnError가 true이면(onError 핸들러가 없을 때의 기본값) 오류가 발생합니다.
  • throwOnError가 false이면(onError 핸들러가 있을 때의 기본값) 오류가 처리된 것으로 간주됩니다.
  • onError와 throwOnError를 함께 사용할 수 있으며 오류가 발생하기 전에 핸들러가 호출됩니다.
  • 내부 AsyncBatcher 인스턴스를 사용해 오류 상태를 확인할 수 있습니다.

상태 관리:

  • 반응형 상태 관리에 TanStack Store를 사용합니다.
  • 비동기 배처 생성 시 initialState로 초기 상태 값을 제공합니다.
  • onSuccess 콜백으로 성공한 배치 실행에 반응하고 사용자 지정 로직을 구현합니다.
  • onError 콜백으로 배치 실행 오류에 반응하고 사용자 지정 오류 처리를 구현합니다.
  • onSettled 콜백으로 배치 실행 완료(성공 또는 오류)에 반응하고 사용자 지정 로직을 구현합니다.
  • onItemsChange 콜백으로 배처에서 항목이 추가되거나 제거될 때 반응합니다.
  • 상태에는 처리한 전체 항목 수, 성공/오류 횟수, 실행 상태가 포함됩니다.
  • 내부 AsyncBatcher 인스턴스의 store.state 속성으로 상태에 접근할 수 있습니다.
  • 프레임워크 어댑터(React/Solid)를 사용할 때는 훅의 state 속성에서 상태에 접근합니다.

타입 매개변수​

TValue​

TValue

매개변수​

fn​

(items) => Promise&lt;any>

options​

AsyncBatcherOptions&lt;TValue>

반환값​

(item): Promise<any>;

비동기 배처에 항목을 추가합니다. 배치 크기에 도달하거나 타임아웃이 발생하거나 shouldProcess가 true를 반환하면 배치를 처리합니다.

매개변수​

item​

TValue

반환값​

Promise&lt;any>

배치 함수의 결과입니다. 오류가 발생했으며 onError로 처리된 경우에는 undefined입니다.

발생 오류​

onError 핸들러가 설정되지 않았거나 throwOnError가 true일 때 발생한 배치 함수의 오류입니다.

예시​

const batchItems = asyncBatch<number>(
  async (items) => {
    const result = await processApiCall(items);
    console.log('Processing:', items);
    return result;
  },
  {
    maxSize: 3,
    wait: 1000,
    onSuccess: (result) => console.log('Batch succeeded:', result),
    onError: (error) => console.error('Batch failed:', error)
  }
);

batchItems(1);
batchItems(2);
batchItems(3); // Triggers batch processing