@tanstack/preact-pacer 0.0.1 → 0.18.0

package/src/async-batcher/useAsyncBatchedCallback.ts

@@ -0,0 +1,54 @@
+import { useCallback } from 'preact/hooks'
+import { useAsyncBatcher } from './useAsyncBatcher'
+import type { AsyncBatcherOptions } from '@tanstack/pacer/async-batcher'
+import type { AnyAsyncFunction } from '@tanstack/pacer/types'
+
+/**
+ * A Preact hook that creates a batched version of an async callback function.
+ * This hook is a convenient wrapper around the `useAsyncBatcher` hook,
+ * providing a stable, batched async function reference for use in Preact components.
+ *
+ * The batched async function will collect individual calls into batches and execute them
+ * when batch conditions are met (max size reached, wait time elapsed, or custom logic).
+ * The returned function always returns a promise that resolves with undefined (since the
+ * batch function processes multiple items together).
+ *
+ * This hook provides a simpler API compared to `useAsyncBatcher`, making it ideal for basic
+ * async batching needs. However, it does not expose the underlying AsyncBatcher instance.
+ *
+ * For advanced usage requiring features like:
+ * - Manual batch execution
+ * - Access to batch results and state
+ * - Custom useCallback dependencies
+ *
+ * Consider using the `useAsyncBatcher` hook instead.
+ *
+ * @example
+ * ```tsx
+ * // Batch API requests
+ * const batchApiCall = useAsyncBatchedCallback(async (requests: ApiRequest[]) => {
+ *   const results = await Promise.all(requests.map(req => fetch(req.url)));
+ *   return results.map(res => res.json());
+ * }, {
+ *   maxSize: 10,   // Process when 10 requests collected
+ *   wait: 1000     // Or after 1 second
+ * });
+ *
+ * // Use in event handlers
+ * <button onClick={() => batchApiCall({ url: '/api/analytics', data: eventData })}>
+ *   Track Event
+ * </button>
+ * ```
+ */
+export function useAsyncBatchedCallback<TFn extends AnyAsyncFunction>(
+  fn: (items: Array<Parameters<TFn>[0]>) => Promise<any>,
+  options: AsyncBatcherOptions<Parameters<TFn>[0]>,
+): (...args: Parameters<TFn>) => Promise<void> {
+  const asyncBatchedFn = useAsyncBatcher(fn, options).addItem
+  return useCallback(
+    async (...args: Parameters<TFn>) => {
+      asyncBatchedFn(args[0])
+    },
+    [asyncBatchedFn],
+  )
+}

package/src/async-batcher/useAsyncBatcher.ts

@@ -0,0 +1,198 @@
+import { useMemo, useState } from 'preact/hooks'
+import { AsyncBatcher } from '@tanstack/pacer/async-batcher'
+import { useStore } from '@tanstack/preact-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
+import type { Store } from '@tanstack/preact-store'
+import type {
+  AsyncBatcherOptions,
+  AsyncBatcherState,
+} from '@tanstack/pacer/async-batcher'
+
+export interface ReactAsyncBatcher<TValue, TSelected = {}> extends Omit<
+  AsyncBatcher<TValue>,
+  'store'
+> {
+  /**
+   * Reactive state that will be updated and re-rendered when the batcher state changes
+   *
+   * Use this instead of `batcher.store.state`
+   */
+  readonly state: Readonly<TSelected>
+  /**
+   * @deprecated Use `batcher.state` instead of `batcher.store.state` if you want to read reactive state.
+   * The state on the store object is not reactive, as it has not been wrapped in a `useStore` hook internally.
+   * Although, you can make the state reactive by using the `useStore` in your own usage.
+   */
+  readonly store: Store<Readonly<AsyncBatcherState<TValue>>>
+}
+
+/**
+ * A Preact hook that creates an `AsyncBatcher` instance for managing asynchronous batches of items.
+ *
+ * This is the async version of the useBatcher hook. Unlike the sync version, this async batcher:
+ * - Handles promises and returns results from batch executions
+ * - Provides error handling with configurable error behavior
+ * - Tracks success, error, and settle counts separately
+ * - Has state tracking for when batches are executing
+ * - Returns the result of the batch function execution
+ *
+ * Features:
+ * - Configurable batch size and wait time
+ * - Custom batch processing logic via getShouldExecute
+ * - Event callbacks for monitoring batch operations
+ * - Error handling for failed batch operations
+ * - Automatic or manual batch processing
+ *
+ * The batcher collects items and processes them in batches based on:
+ * - Maximum batch size (number of items per batch)
+ * - Time-based batching (process after X milliseconds)
+ * - Custom batch processing logic via getShouldExecute
+ *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and batcher 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 AsyncBatcher 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:
+ * - `errorCount`: Number of batch executions that have resulted in errors
+ * - `failedItems`: Array of items that failed during batch processing
+ * - `isEmpty`: Whether the batcher has no items to process
+ * - `isExecuting`: Whether a batch is currently being processed asynchronously
+ * - `isPending`: Whether the batcher is waiting for the timeout to trigger batch processing
+ * - `isRunning`: Whether the batcher is active and will process items automatically
+ * - `items`: Array of items currently queued for batch processing
+ * - `lastResult`: The result from the most recent batch execution
+ * - `settleCount`: Number of batch executions that have completed (success or error)
+ * - `size`: Number of items currently in the batch queue
+ * - `status`: Current processing status ('idle' | 'pending' | 'executing' | 'populated')
+ * - `successCount`: Number of batch executions that have completed successfully
+ * - `totalItemsProcessed`: Total number of items processed across all batches
+ * - `totalItemsFailed`: Total number of items that have failed processing
+ *
+ * @example
+ * ```tsx
+ * // Basic async batcher for API requests - no reactive state subscriptions
+ * const asyncBatcher = useAsyncBatcher(
+ *   async (items) => {
+ *     const results = await Promise.all(items.map(item => processItem(item)));
+ *     return results;
+ *   },
+ *   { maxSize: 10, wait: 2000 }
+ * );
+ *
+ * // Opt-in to re-render when execution state changes (optimized for loading indicators)
+ * const asyncBatcher = useAsyncBatcher(
+ *   async (items) => {
+ *     const results = await Promise.all(items.map(item => processItem(item)));
+ *     return results;
+ *   },
+ *   { maxSize: 10, wait: 2000 },
+ *   (state) => ({
+ *     isExecuting: state.isExecuting,
+ *     isPending: state.isPending,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when results are available (optimized for data display)
+ * const asyncBatcher = useAsyncBatcher(
+ *   async (items) => {
+ *     const results = await Promise.all(items.map(item => processItem(item)));
+ *     return results;
+ *   },
+ *   { maxSize: 10, wait: 2000 },
+ *   (state) => ({
+ *     lastResult: state.lastResult,
+ *     successCount: state.successCount,
+ *     totalItemsProcessed: state.totalItemsProcessed
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when error state changes (optimized for error handling)
+ * const asyncBatcher = useAsyncBatcher(
+ *   async (items) => {
+ *     const results = await Promise.all(items.map(item => processItem(item)));
+ *     return results;
+ *   },
+ *   {
+ *     maxSize: 10,
+ *     wait: 2000,
+ *     onError: (error) => console.error('Batch processing failed:', error)
+ *   },
+ *   (state) => ({
+ *     errorCount: state.errorCount,
+ *     failedItems: state.failedItems,
+ *     totalItemsFailed: state.totalItemsFailed
+ *   })
+ * );
+ *
+ * // Complete example with all callbacks
+ * const asyncBatcher = useAsyncBatcher(
+ *   async (items) => {
+ *     const results = await Promise.all(items.map(item => processItem(item)));
+ *     return results;
+ *   },
+ *   {
+ *     maxSize: 10,
+ *     wait: 2000,
+ *     onSuccess: (result) => {
+ *       console.log('Batch processed successfully:', result);
+ *     },
+ *     onError: (error) => {
+ *       console.error('Batch processing failed:', error);
+ *     }
+ *   }
+ * );
+ *
+ * // Add items to batch
+ * asyncBatcher.addItem(newItem);
+ *
+ * // Manually execute batch
+ * const result = await asyncBatcher.execute();
+ *
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { isExecuting, lastResult, size } = asyncBatcher.state;
+ * ```
+ */
+export function useAsyncBatcher<TValue, TSelected = {}>(
+  fn: (items: Array<TValue>) => Promise<any>,
+  options: AsyncBatcherOptions<TValue> = {},
+  selector: (state: AsyncBatcherState<TValue>) => TSelected = () =>
+    ({}) as TSelected,
+): ReactAsyncBatcher<TValue, TSelected> {
+  const mergedOptions = {
+    ...useDefaultPacerOptions().asyncBatcher,
+    ...options,
+  } as AsyncBatcherOptions<TValue>
+
+  const [asyncBatcher] = useState(
+    () => new AsyncBatcher<TValue>(fn, mergedOptions),
+  )
+
+  asyncBatcher.fn = fn
+  asyncBatcher.setOptions(mergedOptions)
+
+  const state = useStore(asyncBatcher.store, selector)
+
+  return useMemo(
+    () =>
+      ({
+        ...asyncBatcher,
+        state,
+      }) as ReactAsyncBatcher<TValue, TSelected>, // omit `store` in favor of `state`
+    [asyncBatcher, state],
+  )
+}

package/src/async-debouncer/index.ts

@@ -0,0 +1,5 @@
+// re-export everything from the core pacer package, BUT ONLY from the async-debouncer module
+export * from '@tanstack/pacer/async-debouncer'
+
+export * from './useAsyncDebouncer'
+export * from './useAsyncDebouncedCallback'

package/src/async-debouncer/useAsyncDebouncedCallback.ts

@@ -0,0 +1,54 @@
+import { useCallback } from 'preact/hooks'
+import { useAsyncDebouncer } from './useAsyncDebouncer'
+import type { AsyncDebouncerOptions } from '@tanstack/pacer/async-debouncer'
+import type { AnyAsyncFunction } from '@tanstack/pacer/types'
+
+/**
+ * A Preact hook that creates a debounced version of an async callback function.
+ * This hook is a convenient wrapper around the `useAsyncDebouncer` hook,
+ * providing a stable, debounced async function reference for use in Preact components.
+ *
+ * The debounced async function will only execute after the specified wait time has elapsed
+ * since its last invocation. If called again before the wait time expires, the timer
+ * resets and starts waiting again. The returned function always returns a promise
+ * that resolves or rejects with the result of the original async function.
+ *
+ * This hook provides a simpler API compared to `useAsyncDebouncer`, making it ideal for basic
+ * async debouncing needs. However, it does not expose the underlying AsyncDebouncer instance.
+ *
+ * For advanced usage requiring features like:
+ * - Manual cancellation
+ * - Access to execution/error state
+ * - Custom useCallback dependencies
+ *
+ * Consider using the `useAsyncDebouncer` hook instead.
+ *
+ *
+ * @example
+ * ```tsx
+ * // Debounce an async search handler
+ * const handleSearch = useAsyncDebouncedCallback(async (query: string) => {
+ *   const results = await fetchSearchResults(query);
+ *   return results;
+ * }, {
+ *   wait: 500 // Wait 500ms between executions
+ * });
+ *
+ * // Use in an input
+ * <input
+ *   type="search"
+ *   onChange={e => handleSearch(e.target.value)}
+ * />
+ * ```
+ */
+export function useAsyncDebouncedCallback<TFn extends AnyAsyncFunction>(
+  fn: TFn,
+  options: AsyncDebouncerOptions<TFn>,
+): (...args: Parameters<TFn>) => Promise<ReturnType<TFn>> {
+  const asyncDebouncedFn = useAsyncDebouncer(fn, options).maybeExecute
+  return useCallback(
+    (...args: Parameters<TFn>) =>
+      asyncDebouncedFn(...args) as Promise<ReturnType<TFn>>,
+    [asyncDebouncedFn],
+  )
+}

package/src/async-debouncer/useAsyncDebouncer.ts

@@ -0,0 +1,184 @@
+import { useEffect, useMemo, useState } from 'preact/hooks'
+import { AsyncDebouncer } from '@tanstack/pacer/async-debouncer'
+import { useStore } from '@tanstack/preact-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
+import type { Store } from '@tanstack/preact-store'
+import type { AnyAsyncFunction } from '@tanstack/pacer/types'
+import type {
+  AsyncDebouncerOptions,
+  AsyncDebouncerState,
+} from '@tanstack/pacer/async-debouncer'
+
+export interface ReactAsyncDebouncer<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends Omit<AsyncDebouncer<TFn>, 'store'> {
+  /**
+   * Reactive state that will be updated and re-rendered when the debouncer state changes
+   *
+   * Use this instead of `debouncer.store.state`
+   */
+  readonly state: Readonly<TSelected>
+  /**
+   * @deprecated Use `debouncer.state` instead of `debouncer.store.state` if you want to read reactive state.
+   * The state on the store object is not reactive, as it has not been wrapped in a `useStore` hook internally.
+   * Although, you can make the state reactive by using the `useStore` in your own usage.
+   */
+  readonly store: Store<Readonly<AsyncDebouncerState<TFn>>>
+}
+
+/**
+ * A low-level Preact hook that creates an `AsyncDebouncer` instance to delay execution of an async function.
+ *
+ * This hook is designed to be flexible and state-management agnostic - it simply returns a debouncer instance that
+ * you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc).
+ *
+ * Async debouncing ensures that an async function only executes after a specified delay has passed since its last invocation.
+ * Each new invocation resets the delay timer. This is useful for handling frequent events like window resizing
+ * or input changes where you only want to execute the handler after the events have stopped occurring.
+ *
+ * Unlike throttling which allows execution at regular intervals, debouncing prevents any execution until
+ * the function stops being called for the specified delay period.
+ *
+ * Unlike the non-async Debouncer, this async version supports returning values from the debounced function,
+ * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
+ * instead of setting the result on a state variable from within the debounced function.
+ *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and debouncer 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 AsyncDebouncer 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:
+ * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge
+ * - `errorCount`: Number of function executions that have resulted in errors
+ * - `isExecuting`: Whether the debounced function is currently executing asynchronously
+ * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `lastResult`: The result from the most recent successful function execution
+ * - `settleCount`: Number of function executions that have completed (success or error)
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending' | 'executing' | 'settled')
+ * - `successCount`: Number of function executions that have completed successfully
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const searchDebouncer = useAsyncDebouncer(
+ *   async (query: string) => {
+ *     const results = await api.search(query);
+ *     return results;
+ *   },
+ *   { wait: 500 }
+ * );
+ *
+ * // Opt-in to re-render when execution state changes (optimized for loading indicators)
+ * const searchDebouncer = useAsyncDebouncer(
+ *   async (query: string) => {
+ *     const results = await api.search(query);
+ *     return results;
+ *   },
+ *   { wait: 500 },
+ *   (state) => ({
+ *     isExecuting: state.isExecuting,
+ *     isPending: state.isPending
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when results are available (optimized for data display)
+ * const searchDebouncer = useAsyncDebouncer(
+ *   async (query: string) => {
+ *     const results = await api.search(query);
+ *     return results;
+ *   },
+ *   { wait: 500 },
+ *   (state) => ({
+ *     lastResult: state.lastResult,
+ *     successCount: state.successCount
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when error state changes (optimized for error handling)
+ * const searchDebouncer = useAsyncDebouncer(
+ *   async (query: string) => {
+ *     const results = await api.search(query);
+ *     return results;
+ *   },
+ *   {
+ *     wait: 500,
+ *     onError: (error) => console.error('Search failed:', error)
+ *   },
+ *   (state) => ({
+ *     errorCount: state.errorCount,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // With state management
+ * const [results, setResults] = useState([]);
+ * const { maybeExecute, state } = useAsyncDebouncer(
+ *   async (searchTerm) => {
+ *     const data = await searchAPI(searchTerm);
+ *     setResults(data);
+ *   },
+ *   {
+ *     wait: 300,
+ *     leading: true,   // Execute immediately on first call
+ *     trailing: false, // Skip trailing edge updates
+ *     onError: (error) => {
+ *       console.error('API call failed:', error);
+ *     }
+ *   }
+ * );
+ *
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { isExecuting, lastResult } = state;
+ * ```
+ */
+export function useAsyncDebouncer<TFn extends AnyAsyncFunction, TSelected = {}>(
+  fn: TFn,
+  options: AsyncDebouncerOptions<TFn>,
+  selector: (state: AsyncDebouncerState<TFn>) => TSelected = () =>
+    ({}) as TSelected,
+): ReactAsyncDebouncer<TFn, TSelected> {
+  const mergedOptions = {
+    ...useDefaultPacerOptions().asyncDebouncer,
+    ...options,
+  } as AsyncDebouncerOptions<TFn>
+
+  const [asyncDebouncer] = useState(
+    () => new AsyncDebouncer<TFn>(fn, mergedOptions),
+  )
+
+  asyncDebouncer.fn = fn
+  asyncDebouncer.setOptions(mergedOptions)
+
+  const state = useStore(asyncDebouncer.store, selector)
+
+  useEffect(() => {
+    return () => {
+      asyncDebouncer.cancel()
+    }
+  }, [asyncDebouncer])
+
+  return useMemo(
+    () =>
+      ({
+        ...asyncDebouncer,
+        state,
+      }) as ReactAsyncDebouncer<TFn, TSelected>, // omit `store` in favor of `state`
+    [asyncDebouncer, state],
+  )
+}

package/src/async-queuer/index.ts

@@ -0,0 +1,4 @@
+export * from '@tanstack/pacer/async-queuer'
+
+export * from './useAsyncQueuer'
+export * from './useAsyncQueuedState'

package/src/async-queuer/useAsyncQueuedState.ts

@@ -0,0 +1,165 @@
+import { useAsyncQueuer } from './useAsyncQueuer'
+import type { ReactAsyncQueuer } from './useAsyncQueuer'
+import type {
+  AsyncQueuerOptions,
+  AsyncQueuerState,
+} from '@tanstack/pacer/async-queuer'
+
+/**
+ * A higher-level Preact hook that creates an `AsyncQueuer` instance with built-in state management.
+ *
+ * This hook combines an AsyncQueuer with Preact state to automatically track the queue items.
+ * It returns a tuple containing:
+ * - The current array of queued items as Preact 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
+ * - `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
+ *
+ * @example
+ * ```tsx
+ * // 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,
+ *     settledCount: state.settledCount,
+ *     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;
+ * ```
+ */
+export function useAsyncQueuedState<
+  TValue,
+  TSelected extends Pick<AsyncQueuerState<TValue>, 'items'> = Pick<
+    AsyncQueuerState<TValue>,
+    'items'
+  >,
+>(
+  fn: (value: TValue) => Promise<any>,
+  options: AsyncQueuerOptions<TValue> = {},
+  selector?: (state: AsyncQueuerState<TValue>) => TSelected,
+): [Array<TValue>, ReactAsyncQueuer<TValue, TSelected>] {
+  const asyncQueuer = useAsyncQueuer(fn, options, selector)
+
+  return [asyncQueuer.state.items, asyncQueuer]
+}