본문으로 건너뛰기

클래스: AsyncQueuer<TValue>

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

구성 가능한 동시 실행 수, 우선순위, 만료 기능으로 작업을 처리하는 유연한 비동기 큐입니다.

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

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

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

큐 처리란 무엇인가요? 큐 처리는 항목을 순차적으로 또는 제어된 동시 실행 방식으로 관리하고 처리하는 기법입니다. 작업은 구성된 동시 실행 제한까지 처리됩니다. 작업이 완료되면 동시 실행 제한이 허용하는 경우 다음 대기 중인 작업을 처리합니다.

주요 기능:

  • getPriority 옵션을 통한 우선순위 큐 지원
  • 구성 가능한 동시 실행 제한
  • 작업 성공, 오류, 완료 및 큐 상태 변경을 위한 콜백
  • FIFO(선입선출) 또는 LIFO(후입선출) 큐 동작
  • 처리 일시 중지 및 재개
  • 오래된 항목을 큐에서 제거하는 항목 만료 기능

오류 처리:

  • onError 핸들러가 제공되면 오류와 큐 처리기 인스턴스를 인수로 이 핸들러를 호출합니다.
  • throwOnError가 true이면 오류를 발생시킵니다. 이는 onError 핸들러가 제공되지 않았을 때의 기본값입니다.
  • throwOnError가 false이면 오류를 무시합니다. 이는 onError 핸들러가 제공되었을 때의 기본값입니다.
  • onError와 throwOnError를 함께 사용할 수 있으며, 오류를 발생시키기 전에 핸들러를 호출합니다.
  • AsyncQueuer 인스턴스를 사용하여 오류 상태를 확인할 수 있습니다.

상태 관리:

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

사용 예시:

const asyncQueuer = new AsyncQueuer<string>(async (item) => {
  // process item
  return item.toUpperCase();
}, {
  concurrency: 2,
  onSuccess: (result) => {
    console.log(result);
  }
});

asyncQueuer.addItem('hello');
asyncQueuer.start();

타입 매개변수​

TValue​

TValue

생성자​

생성자​

new AsyncQueuer<TValue>(fn, initialOptions): AsyncQueuer<TValue>;

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

매개변수​

fn​

(item) => Promise&lt;any>

initialOptions​

AsyncQueuerOptions&lt;TValue> = {}

반환값​

AsyncQueuer&lt;TValue>

속성​

asyncRetryers​

asyncRetryers: Map<number, AsyncRetryer<(item) => Promise<any>>>;

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

fn()​

fn: (item) => Promise<any>;

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

매개변수​

item​

TValue

반환값​

Promise&lt;any>

key​

key: string | undefined;

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

options​

options: AsyncQueuerOptions<TValue>;

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

store​

readonly store: Store<Readonly<AsyncQueuerState<TValue>>>;

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

메서드​

abort()​

abort(): void;

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

내부 중단 컨트롤러를 사용하여 진행 중인 모든 실행을 중단합니다. 항목은 제거하지 않습니다.

반환값​

void

addItem()​

addItem(
   item, 
   position, 
   runOnItemsChange): boolean;

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

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

매개변수​

item​

TValue

position​

QueuePosition = ...

runOnItemsChange​

boolean = true

반환값​

boolean

예시​

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

clear()​

clear(): void;

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

큐에서 대기 중인 모든 항목을 제거합니다. 활성 작업에는 영향을 주지 않습니다.

반환값​

void

execute()​

execute(position?): Promise<any>;

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

큐에서 다음 항목을 제거하여 반환하고, 해당 항목으로 작업 함수를 실행합니다.

매개변수​

position?​

QueuePosition

반환값​

Promise&lt;any>

예시​

queuer.execute();
// LIFO
queuer.execute('back');

flush()​

flush(numberOfItems, position?): Promise<void>;

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

지정된 수의 항목을 대기 시간 없이 즉시 실행하도록 처리합니다. numberOfItems를 제공하지 않으면 모든 항목을 처리합니다.

매개변수​

numberOfItems​

number = ...

position?​

QueuePosition

반환값​

Promise&lt;void>

flushAsBatch()​

flushAsBatch(batchFunction): Promise<void>;

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

제공된 함수를 인수로 사용하여 큐의 모든 항목을 배칭 방식으로 처리합니다. 처리 후 큐를 비웁니다.

매개변수​

batchFunction​

(items) => Promise&lt;any>

반환값​

Promise&lt;void>

getAbortSignal()​

getAbortSignal(executeCount?): AbortSignal | null;

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

특정 실행의 AbortSignal을 반환합니다. executeCount를 제공하지 않으면 가장 최근 실행의 신호를 반환합니다. 실행을 찾을 수 없거나 현재 실행 중이 아니면 null을 반환합니다.

매개변수​

executeCount?​

number

신호를 가져올 특정 실행을 선택적으로 지정합니다.

반환값​

AbortSignal | null

예시​

const queuer = new AsyncQueuer(
  async (item: string) => {
    const signal = queuer.getAbortSignal()
    if (signal) {
      const response = await fetch(`/api/process/${item}`, { signal })
      return response.json()
    }
  },
  { concurrency: 2 }
)

getNextItem()​

getNextItem(position): TValue | undefined;

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

작업 함수를 실행하지 않고 큐에서 다음 항목을 제거하여 반환합니다. 큐를 수동으로 관리할 때 사용합니다. 일반적으로 항목을 처리하려면 execute()를 사용합니다.

매개변수​

position​

QueuePosition = ...

반환값​

TValue | undefined

예시​

// FIFO
queuer.getNextItem();
// LIFO
queuer.getNextItem('back');

peekActiveItems()​

peekActiveItems(): TValue[];

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

현재 처리 중인 항목(활성 작업)을 반환합니다.

반환값​

TValue[]

peekAllItems()​

peekAllItems(): TValue[];

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

활성 항목과 대기 중인 항목을 포함하여 큐에 있는 모든 항목의 복사본을 반환합니다.

반환값​

TValue[]

peekNextItem()​

peekNextItem(position): TValue | undefined;

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

큐에서 다음 항목을 제거하지 않고 반환합니다.

매개변수​

position​

QueuePosition = 'front'

반환값​

TValue | undefined

예시​

queuer.peekNextItem(); // front
queuer.peekNextItem('back'); // back

peekPendingItems()​

peekPendingItems(): TValue[];

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

처리를 기다리는 항목(대기 중인 작업)을 반환합니다.

반환값​

TValue[]

reset()​

reset(): void;

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

큐 처리기 상태를 기본값으로 재설정합니다.

반환값​

void

setOptions()​

setOptions(newOptions): void;

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

큐 처리기 옵션을 업데이트합니다. 새 옵션은 기존 옵션과 병합됩니다.

매개변수​

newOptions​

Partial&lt;AsyncQueuerOptions&lt;TValue>>

반환값​

void

start()​

start(): void;

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

큐에 있는 항목의 처리를 시작합니다. 이미 실행 중이면 아무 작업도 하지 않습니다.

반환값​

void

stop()​

stop(): void;

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

큐에 있는 항목의 처리를 중지합니다. 큐는 비우지 않습니다.

반환값​

void