함수: useQueuedValue()

function useQueuedValue<TValue, TSelected>(
   initialValue, 
   options, 
   selector?): [TValue, ReactQueuer<TValue, TSelected>];

정의 위치: react-pacer/src/queuer/useQueuedValue.ts:103

선택적 지연을 두고 상태 변경을 순서대로 처리하는 큐 값을 생성하는 React 훅입니다. 내부적으로 useQueuer를 사용해 상태 변경 큐를 관리하고 순차적으로 적용합니다.

큐 값은 변경을 받은 순서대로 처리하며 각 변경 처리 사이에 선택적 지연을 둘 수 있습니다. 애니메이션이나 순차적 UI 업데이트처럼 특정 순서로 처리해야 하는 상태 업데이트에 유용합니다.

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

• 현재 큐 값
• 제어 메서드를 제공하는 큐어 인스턴스

상태 관리와 셀렉터

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

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

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

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

타입 매개변수

TValue

TValue

TSelected

TSelected extends Pick<QueuerState<TValue>, "items"> = Pick<QueuerState<TValue>, "items">

매개변수

initialValue

TValue

options

ReactQueuerOptions<TValue, TSelected> = {}

selector?

(state) => TSelected

반환값

[TValue, ReactQueuer<TValue, TSelected>]

예시

// Default behavior - no reactive state subscriptions
const [value, queuer] = useQueuedValue(initialValue, {
  wait: 500, // Wait 500ms between processing each change
  started: true // Start processing immediately
});

// Opt-in to re-render when queue processing state changes (optimized for loading indicators)
const [value, queuer] = useQueuedValue(
  initialValue,
  { wait: 500, started: true },
  (state) => ({
    isRunning: state.isRunning,
    isIdle: state.isIdle,
    status: state.status,
    pendingTick: state.pendingTick
  })
);

// Opt-in to re-render when queue contents change (optimized for displaying queue status)
const [value, queuer] = useQueuedValue(
  initialValue,
  { wait: 500, started: true },
  (state) => ({
    size: state.size,
    isEmpty: state.isEmpty,
    isFull: state.isFull
  })
);

// Opt-in to re-render when execution metrics change (optimized for stats display)
const [value, queuer] = useQueuedValue(
  initialValue,
  { wait: 500, started: true },
  (state) => ({
    executionCount: state.executionCount,
    expirationCount: state.expirationCount,
    rejectionCount: state.rejectionCount
  })
);

// Add changes to the queue
const handleChange = (newValue) => {
  queuer.addItem(newValue);
};

// Control the queue
const pauseProcessing = () => {
  queuer.stop();
};

const resumeProcessing = () => {
  queuer.start();
};

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