본문으로 건너뛰기

함수: useQueuedState()

function useQueuedState<TValue, TSelected>(
   fn, 
   options, 
   selector?): [TValue[], (item, position?, runOnItemsChange?) => boolean, PreactQueuer<TValue, TSelected>];

정의 위치: preact-pacer/src/queuer/useQueuedState.ts:119

Preact의 useState와 큐 기능을 결합해 관리형 상태를 갖는 큐어를 생성하는 Preact 훅입니다. 현재 큐 상태와 큐 제어 메서드를 모두 제공합니다.

큐에서 항목이 추가, 제거 또는 재정렬될 때마다 큐 상태가 자동으로 업데이트됩니다. 모든 큐 작업은 훅이 반환하는 상태 배열에 반영됩니다.

큐를 시작하고 중지해 지정된 간격으로 항목을 자동 처리할 수 있으므로 스케줄러로 활용하기에 유용합니다. 시작하면 틱마다 항목 하나를 처리하며 틱 사이에 선택적 대기 시간을 둘 수 있습니다.

훅은 다음 요소를 담은 튜플을 반환합니다.

  • 배열 형태의 현재 큐 상태
  • 큐 조작 메서드를 제공하는 큐 인스턴스

상태 관리와 셀렉터​

훅은 내부 큐어 인스턴스를 통해 반응형 상태 관리에 TanStack Store를 사용합니다. selector 매개변수를 사용하면 큐어 상태의 어떤 변경이 재렌더링을 트리거할지 지정할 수 있으며, 관련 없는 상태가 변경될 때 불필요한 재렌더링을 방지하여 성능을 최적화합니다.

기본적으로 반응형 상태 구독은 없습니다. 상태 추적을 명시적으로 활성화하려면 셀렉터 함수를 제공해야 합니다. 이렇게 하면 불필요한 재렌더링을 방지하고 컴포넌트 업데이트 시점을 완전히 제어할 수 있습니다. 셀렉터를 제공한 경우에만 선택한 상태 값이 변경될 때 컴포넌트가 다시 렌더링됩니다.

사용 가능한 큐어 상태 속성:

  • executionCount: 큐어가 처리한 항목 수
  • expirationCount: 만료로 제거된 항목 수
  • isEmpty: 큐어에 처리할 항목이 없는지 여부
  • isFull: 큐어가 최대 용량에 도달했는지 여부
  • isIdle: 큐어가 현재 어떤 항목도 처리하지 않는지 여부
  • isRunning: 큐어가 활성 상태이며 항목을 자동으로 처리할지 여부
  • items: 현재 처리 대기 중인 항목 배열
  • itemTimestamps: 만료 추적을 위해 항목이 추가된 시점의 타임스탬프
  • pendingTick: 큐어에 다음 항목 처리를 위한 대기 중 타임아웃이 있는지 여부
  • rejectionCount: 추가가 거부된 항목 수
  • size: 현재 큐에 있는 항목 수
  • status: 현재 처리 상태('idle' | 'running' | 'stopped')

타입 매개변수​

TValue​

TValue

TSelected​

TSelected extends Pick&lt;QueuerState&lt;TValue>, "items"> = Pick&lt;QueuerState&lt;TValue>, "items">

매개변수​

fn​

(item) => void

options​

PreactQueuerOptions&lt;TValue, TSelected> = {}

selector?​

(state) => TSelected

반환값​

[TValue[], (item, position?, runOnItemsChange?) => boolean, PreactQueuer&lt;TValue, TSelected>]

예시​

// Default behavior - no reactive state subscriptions
const [items, addItem, queue] = useQueuedState(
  (item) => console.log('Processing:', item),
  {
    initialItems: ['item1', 'item2'],
    started: true,
    wait: 1000,
    getPriority: (item) => item.priority
  }
);

// Opt-in to re-render when queue contents change (optimized for displaying queue items)
const [items, addItem, queue] = useQueuedState(
  (item) => console.log('Processing:', item),
  { started: true, wait: 1000 },
  (state) => ({
    items: state.items,
    size: state.size,
    isEmpty: state.isEmpty
  })
);

// Opt-in to re-render when processing state changes (optimized for loading indicators)
const [items, addItem, queue] = useQueuedState(
  (item) => console.log('Processing:', item),
  { started: true, wait: 1000 },
  (state) => ({
    isRunning: state.isRunning,
    isIdle: state.isIdle,
    status: state.status,
    pendingTick: state.pendingTick
  })
);

// Opt-in to re-render when execution metrics change (optimized for stats display)
const [items, addItem, queue] = useQueuedState(
  (item) => console.log('Processing:', item),
  { started: true, wait: 1000 },
  (state) => ({
    executionCount: state.executionCount,
    expirationCount: state.expirationCount,
    rejectionCount: state.rejectionCount
  })
);

// Add items to queue
const handleAdd = (item) => {
  addItem(item);
};

// Start automatic processing
const startProcessing = () => {
  queue.start();
};

// Stop automatic processing
const stopProcessing = () => {
  queue.stop();
};

// Manual processing still available
const handleProcess = () => {
  const nextItem = queue.getNextItem();
  if (nextItem) {
    processItem(nextItem);
  }
};

// Access the selected queuer state (will be empty object {} unless selector provided)
const { size, isRunning, executionCount } = queue.state;