Function: useAsyncQueuer()

function useAsyncQueuer<TValue, TSelected>( fn, options, selector): ReactAsyncQueuer<TValue, TSelected>

function useAsyncQueuer<TValue, TSelected>( fn, options, selector): ReactAsyncQueuer<TValue, TSelected>

Defined in: react-pacer/src/async-queuer/useAsyncQueuer.ts:167

A lower-level React hook that creates an AsyncQueuer instance for managing an async queue of items.

Features:

Priority queue support via getPriority option
Configurable concurrency limit
Task success/error/completion callbacks
FIFO (First In First Out) or LIFO (Last In First Out) queue behavior
Pause/resume task processing
Task cancellation
Item expiration to clear stale items from the queue

Tasks are processed concurrently up to the configured concurrency limit. When a task completes, the next pending task is processed if below the concurrency limit.

Error Handling:

If an onError handler is provided, it will be called with the error and queuer instance
If throwOnError is true (default when no onError handler is provided), the error will be thrown
If throwOnError is false (default when onError handler is provided), the error will be swallowed
Both onError and throwOnError can be used together - the handler will be called before any error is thrown
The error state can be checked using the underlying AsyncQueuer instance

State Management and Selector

The hook uses TanStack Store for reactive state management. The selector parameter allows you to specify which state changes will trigger a re-render, optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.

By default, there will be no reactive state subscriptions and you must opt-in to state tracking by providing a selector function. This prevents unnecessary re-renders and gives you full control over when your component updates. Only when you provide a selector will the component re-render when the selected state values change.

Available state properties:

activeItems: Items currently being processed by the queuer
errorCount: Number of task executions that have resulted in errors
expirationCount: Number of items that have been removed due to expiration
isEmpty: Whether the queuer has no items to process
isFull: Whether the queuer has reached its maximum capacity
isIdle: Whether the queuer is not currently processing any items
isRunning: Whether the queuer is active and will process items automatically
items: Array of items currently waiting to be processed
itemTimestamps: Timestamps when items were added for expiration tracking
lastResult: The result from the most recent task execution
pendingTick: Whether the queuer has a pending timeout for processing the next item
rejectionCount: Number of items that have been rejected from being added
settledCount: Number of task executions that have completed (success or error)
size: Number of items currently in the queue
status: Current processing status ('idle' | 'running' | 'stopped')
successCount: Number of task executions that have completed successfully

// Default behavior - no reactive state subscriptions const asyncQueuer = useAsyncQueuer( async (item) => { const result = await processItem(item); return result; }, { concurrency: 2, maxSize: 100, started: false } ); // Opt-in to re-render when queue size changes (optimized for displaying queue length) const asyncQueuer = useAsyncQueuer( async (item) => { const result = await processItem(item); return result; }, { concurrency: 2, maxSize: 100, started: false }, (state) => ({ size: state.size, isEmpty: state.isEmpty, isFull: state.isFull }) ); // Opt-in to re-render when processing state changes (optimized for loading indicators) const asyncQueuer = useAsyncQueuer( async (item) => { const result = await processItem(item); return result; }, { concurrency: 2, maxSize: 100, started: false }, (state) => ({ isRunning: state.isRunning, isIdle: state.isIdle, status: state.status, activeItems: state.activeItems, pendingTick: state.pendingTick }) ); // Opt-in to re-render when execution metrics change (optimized for stats display) const asyncQueuer = useAsyncQueuer( async (item) => { const result = await processItem(item); return result; }, { concurrency: 2, maxSize: 100, started: false }, (state) => ({ successCount: state.successCount, errorCount: state.errorCount, settledCount: state.settledCount, expirationCount: state.expirationCount, rejectionCount: state.rejectionCount }) ); // Opt-in to re-render when results are available (optimized for data display) const asyncQueuer = useAsyncQueuer( async (item) => { const result = await processItem(item); return result; }, { concurrency: 2, maxSize: 100, started: false, onSuccess: (result) => { console.log('Item processed:', result); }, onError: (error) => { console.error('Processing failed:', error); } }, (state) => ({ lastResult: state.lastResult, successCount: state.successCount }) ); // Add items to queue asyncQueuer.addItem(newItem); // Start processing asyncQueuer.start(); // Access the selected state (will be empty object {} unless selector provided) const { size, isRunning, activeItems } = asyncQueuer.state;

// Default behavior - no reactive state subscriptions const asyncQueuer = useAsyncQueuer( async (item) => { const result = await processItem(item); return result; }, { concurrency: 2, maxSize: 100, started: false } ); // Opt-in to re-render when queue size changes (optimized for displaying queue length) const asyncQueuer = useAsyncQueuer( async (item) => { const result = await processItem(item); return result; }, { concurrency: 2, maxSize: 100, started: false }, (state) => ({ size: state.size, isEmpty: state.isEmpty, isFull: state.isFull }) ); // Opt-in to re-render when processing state changes (optimized for loading indicators) const asyncQueuer = useAsyncQueuer( async (item) => { const result = await processItem(item); return result; }, { concurrency: 2, maxSize: 100, started: false }, (state) => ({ isRunning: state.isRunning, isIdle: state.isIdle, status: state.status, activeItems: state.activeItems, pendingTick: state.pendingTick }) ); // Opt-in to re-render when execution metrics change (optimized for stats display) const asyncQueuer = useAsyncQueuer( async (item) => { const result = await processItem(item); return result; }, { concurrency: 2, maxSize: 100, started: false }, (state) => ({ successCount: state.successCount, errorCount: state.errorCount, settledCount: state.settledCount, expirationCount: state.expirationCount, rejectionCount: state.rejectionCount }) ); // Opt-in to re-render when results are available (optimized for data display) const asyncQueuer = useAsyncQueuer( async (item) => { const result = await processItem(item); return result; }, { concurrency: 2, maxSize: 100, started: false, onSuccess: (result) => { console.log('Item processed:', result); }, onError: (error) => { console.error('Processing failed:', error); } }, (state) => ({ lastResult: state.lastResult, successCount: state.successCount }) ); // Add items to queue asyncQueuer.addItem(newItem); // Start processing asyncQueuer.start(); // Access the selected state (will be empty object {} unless selector provided) const { size, isRunning, activeItems } = asyncQueuer.state;

useAsyncQueuer

Function: useAsyncQueuer()

State Management and Selector

Type Parameters

Parameters

fn

options

selector

Returns

Example

Subscribe to Bytes

Subscribe to Bytes