useAsyncQueuedState

function useAsyncQueuedState<TValue, TSelected>(
   fn,
   options?,
   selector?): [TValue[], ReactAsyncQueuer<TValue, TSelected>];

Defined in: async-queuer/useAsyncQueuedState.ts:151

A higher-level React hook that creates an AsyncQueuer instance with built-in state management.

This hook combines an AsyncQueuer with React state to automatically track the queue items. It returns a tuple containing:

• The current array of queued items as React state
• The queuer instance with methods to control the queue

The queue can be configured with:

• Maximum concurrent operations
• Maximum queue size
• Processing function for queue items
• Various lifecycle callbacks

The state will automatically update whenever items are:

• Added to the queue
• Removed from the queue
• Started processing
• Completed processing

State Management and Selector

The hook uses TanStack Store for reactive state management via the underlying async queuer instance. The selector parameter allows you to specify which async queuer 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 async queuer 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
• settleCount: 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

Type Parameters

TValue

TValue

TSelected

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

Parameters

fn

(value) => Promise<any>

options?

ReactAsyncQueuerOptions<TValue, TSelected> = {}

selector?

(state) => TSelected

Returns

[TValue[], ReactAsyncQueuer<TValue, TSelected>]

Example

// Default behavior - no reactive state subscriptions
const [queueItems, asyncQueuer] = useAsyncQueuedState(
  async (item) => {
    const result = await processItem(item);
    return result;
  },
  {
    concurrency: 2,
    maxSize: 100,
    started: true
  }
);

// Opt-in to re-render when queue contents change (optimized for displaying queue items)
const [queueItems, asyncQueuer] = useAsyncQueuedState(
  async (item) => {
    const result = await processItem(item);
    return result;
  },
  { concurrency: 2, maxSize: 100, started: true },
  (state) => ({
    items: state.items,
    size: state.size,
    isEmpty: state.isEmpty,
    isFull: state.isFull
  })
);

// Opt-in to re-render when processing state changes (optimized for loading indicators)
const [queueItems, asyncQueuer] = useAsyncQueuedState(
  async (item) => {
    const result = await processItem(item);
    return result;
  },
  { concurrency: 2, maxSize: 100, started: true },
  (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 [queueItems, asyncQueuer] = useAsyncQueuedState(
  async (item) => {
    const result = await processItem(item);
    return result;
  },
  { concurrency: 2, maxSize: 100, started: true },
  (state) => ({
    successCount: state.successCount,
    errorCount: state.errorCount,
    settleCount: state.settleCount,
    expirationCount: state.expirationCount,
    rejectionCount: state.rejectionCount
  })
);

// Opt-in to re-render when results are available (optimized for data display)
const [queueItems, asyncQueuer] = useAsyncQueuedState(
  async (item) => {
    const result = await processItem(item);
    return result;
  },
  { concurrency: 2, maxSize: 100, started: true },
  (state) => ({
    lastResult: state.lastResult,
    successCount: state.successCount
  })
);

// Add items to queue - state updates automatically
asyncQueuer.addItem(async () => {
  const result = await fetchData();
  return result;
});

// Start processing
asyncQueuer.start();

// Stop processing
asyncQueuer.stop();

// queueItems reflects current queue state
const pendingCount = asyncQueuer.peekPendingItems().length;

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