본문으로 건너뛰기

함수: asyncQueue()

function asyncQueue<TValue>(fn, initialOptions): (item, position, runOnItemsChange) => boolean;

정의 위치: async-queuer.ts:982

새 AsyncQueuer 인스턴스를 생성하고 작업을 추가하는 바인딩된 addItem 함수를 반환합니다. 큐어는 자동으로 시작되어 항목을 처리할 준비가 됩니다.

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

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

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

큐잉이란? 큐잉은 항목을 순차적으로 또는 제어된 동시 실행 수로 관리하고 처리하는 기법입니다. 작업은 설정된 동시 실행 한도까지 처리됩니다. 작업이 완료되면 동시 실행 한도가 허용하는 경우 다음 대기 작업을 처리합니다.

설정 옵션:

  • concurrency: 최대 동시 작업 수(기본값: 1)
  • wait: 항목 처리 사이의 대기 시간(기본값: 0)
  • maxSize: 큐에 허용되는 최대 항목 수(기본값: Infinity)
  • getPriority: 항목 우선순위를 결정하는 함수
  • addItemsTo: 항목을 추가할 기본 위치('back' 또는 'front', 기본값: 'back')
  • getItemsFrom: 항목을 가져올 기본 위치('front' 또는 'back', 기본값: 'front')
  • expirationDuration: 항목이 큐에 머물 수 있는 최대 시간
  • started: 즉시 처리를 시작할지 여부(기본값: true)
  • asyncRetryerOptions: 작업 실행의 재시도 동작 설정

오류 처리:

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

상태 관리:

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

타입 매개변수​

TValue​

TValue

매개변수​

fn​

(value) => Promise&lt;any>

initialOptions​

AsyncQueuerOptions&lt;TValue>

반환값​

(
   item, 
   position, 
   runOnItemsChange): boolean;

큐에 항목을 추가합니다. 큐가 가득 차면 항목이 거부되고 onReject가 호출됩니다. 설정에 따라 우선순위 기준 또는 앞/뒤 위치에 항목을 삽입할 수 있습니다. undefined는 내부에서 "항목 없음"을 나타내는 센티널이므로 큐에 추가할 수 없고 항상 거부됩니다.

매개변수​

item​

TValue

position​

QueuePosition = ...

runOnItemsChange​

boolean = true

반환값​

boolean

예시​

queuer.addItem({ value: 'task', priority: 10 });
queuer.addItem('task2', 'front');

예시​

const enqueue = asyncQueue<string>(async (item) => {
  return item.toUpperCase();
}, {
  concurrency: 2,
  wait: 100,
  onSuccess: (result) => console.log('Processed:', result)
});

enqueue('hello');