함수: useQueuer()

function useQueuer<TValue, TSelected>(
   fn, 
   options, 
selector): PreactQueuer<TValue, TSelected>;

정의 위치: preact-pacer/src/queuer/useQueuer.ts:194

Queuer 인스턴스를 생성하고 관리하는 Preact 훅입니다.

내장 상태 관리 없이 Queuer의 기능에 직접 접근할 수 있는 하위 수준 훅입니다. 따라서 onItemsChange 콜백을 활용하여 선호하는 어떤 상태 관리 솔루션 (useState, Redux, Zustand 등)과도 통합할 수 있습니다.

내장 상태 관리 기능이 있는 훅은 useQueuedState를 참고합니다.

Queuer는 기본 Queue를 확장해 처리 기능을 추가합니다. 항목은 순서대로 동기 처리되며 각 항목 처리 사이에 선택적 지연을 둘 수 있습니다. 큐어에는 시작하고 중지할 수 있는 내부 틱 메커니즘이 있어 스케줄러로 활용하기에 유용합니다. 시작하면 틱마다 항목 하나를 처리하며 틱 사이에 선택적 대기 시간을 둘 수 있습니다.

기본적으로 FIFO(First In First Out) 동작을 사용하지만, 항목 추가 시 'front' 위치를 지정하면 LIFO(Last In First Out)로 구성할 수 있습니다.

상태 관리와 셀렉터

훅은 반응형 상태 관리에 TanStack Store를 사용합니다. 다음 두 가지 방식으로 상태 변경을 구독할 수 있습니다.

1. queuer.Subscribe HOC 사용(컴포넌트 트리 구독에 권장)

Subscribe HOC를 사용하면 컴포넌트 트리 깊은 곳의 상태 변경을 구독할 때 훅에 셀렉터를 전달할 필요가 없습니다. 자식 컴포넌트에서 상태를 구독하려는 경우에 적합합니다.

2. selector 매개변수 사용(훅 수준 구독)

selector 매개변수를 사용하면 어떤 상태 변경이 재렌더링을 트리거할지 지정할 수 있으며 관련 없는 상태가 변경될 때 불필요한 재렌더링을 방지하여 훅 수준의 성능을 최적화합니다.

기본적으로 반응형 상태 구독은 없습니다. 상태 추적을 명시적으로 활성화하려면 셀렉터 함수를 제공하거나 Subscribe HOC를 사용해야 합니다. 이렇게 하면 불필요한 재렌더링을 방지하고 컴포넌트가 업데이트되는 시점을 완전히 제어할 수 있습니다.

사용 가능한 상태 속성:

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

언마운트 동작

기본적으로 컴포넌트가 언마운트되면 훅은 큐어를 중지합니다. 이를 사용자 지정하려면 onUnmount 옵션을 사용합니다. 예를 들어 대기 중인 항목을 대신 플러시하려면 다음과 같이 합니다.

const queue = useQueuer(fn, {
  started: true,
  wait: 1000,
  onUnmount: (q) => q.flush()
});

타입 매개변수

TValue

TValue

TSelected

TSelected = { }

매개변수

fn

(item) => void

options

PreactQueuerOptions<TValue, TSelected> = {}

selector

(state) => TSelected

반환값

PreactQueuer<TValue, TSelected>

예시

// Default behavior - no reactive state subscriptions
const queue = useQueuer(
  (item) => console.log('Processing:', item),
  { started: true, wait: 1000 }
);

// Subscribe to state changes deep in component tree using Subscribe HOC
<queue.Subscribe selector={(state) => ({ size: state.size })}>
  {({ size }) => (
    <div>Queue Size: {size}</div>
  )}
</queue.Subscribe>

// Opt-in to re-render when queue size changes at hook level (optimized for displaying queue length)
const queue = useQueuer(
  (item) => console.log('Processing:', item),
  { started: true, wait: 1000 },
  (state) => ({
    size: state.size,
    isEmpty: state.isEmpty,
    isFull: state.isFull
  })
);

// Opt-in to re-render when processing state changes (optimized for loading indicators)
const queue = useQueuer(
  (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 queue = useQueuer(
  (item) => console.log('Processing:', item),
  { started: true, wait: 1000 },
  (state) => ({
    executionCount: state.executionCount,
    expirationCount: state.expirationCount,
    rejectionCount: state.rejectionCount
  })
);

// Example with custom state management and scheduling
const [items, setItems] = useState([]);

const queue = useQueuer(
  (item) => console.log('Processing:', item),
  {
    started: true, // Start processing immediately
    wait: 1000,    // Process one item every second
    onItemsChange: (queue) => setItems(queue.peekAllItems()),
    getPriority: (item) => item.priority // Process higher priority items first
  }
);

// Add items to process - they'll be handled automatically
queue.addItem('task1');
queue.addItem('task2');

// Control the scheduler
queue.stop();  // Pause processing
queue.start(); // Resume processing

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