@tanstack/preact-pacer 0.0.1 → 0.18.0

package/src/debouncer/useDebouncer.ts

@@ -0,0 +1,136 @@
+import { useEffect, useMemo, useState } from 'preact/hooks'
+import { Debouncer } from '@tanstack/pacer/debouncer'
+import { useStore } from '@tanstack/preact-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
+import type { Store } from '@tanstack/preact-store'
+import type {
+  DebouncerOptions,
+  DebouncerState,
+} from '@tanstack/pacer/debouncer'
+import type { AnyFunction } from '@tanstack/pacer/types'
+
+export interface PreactDebouncer<
+  TFn extends AnyFunction,
+  TSelected = {},
+> extends Omit<Debouncer<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<DebouncerState<TFn>>>
+}
+
+/**
+ * A Preact hook that creates and manages a Debouncer instance.
+ *
+ * This is a lower-level hook that provides direct access to the Debouncer's functionality without
+ * any built-in state management. This allows you to integrate it with any state management solution
+ * you prefer (useState, Redux, Zustand, etc.).
+ *
+ * This hook provides debouncing functionality to limit how often a function can be called,
+ * waiting for a specified delay before executing the latest call. This is useful for handling
+ * frequent events like window resizing, scroll events, or real-time search inputs.
+ *
+ * The debouncer will only execute the function after the specified wait time has elapsed
+ * since the last call. If the function is called again before the wait time expires, the
+ * timer resets and starts waiting again.
+ *
+ * ## 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
+ * - `executionCount`: Number of function executions that have been completed
+ * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const searchDebouncer = useDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 }
+ * );
+ *
+ * // Opt-in to re-render when isPending changes (optimized for loading states)
+ * const searchDebouncer = useDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 },
+ *   (state) => ({ isPending: state.isPending })
+ * );
+ *
+ * // Opt-in to re-render when executionCount changes (optimized for tracking execution)
+ * const searchDebouncer = useDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
+ * // Multiple state properties - re-render when any of these change
+ * const searchDebouncer = useDebouncer(
+ *   (query: string) => fetchSearchResults(query),
+ *   { wait: 500 },
+ *   (state) => ({
+ *     isPending: state.isPending,
+ *     executionCount: state.executionCount,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // In an event handler
+ * const handleChange = (e) => {
+ *   searchDebouncer.maybeExecute(e.target.value);
+ * };
+ *
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { isPending } = searchDebouncer.state;
+ * ```
+ */
+export function useDebouncer<TFn extends AnyFunction, TSelected = {}>(
+  fn: TFn,
+  options: DebouncerOptions<TFn>,
+  selector: (state: DebouncerState<TFn>) => TSelected = () => ({}) as TSelected,
+): PreactDebouncer<TFn, TSelected> {
+  const mergedOptions = {
+    ...useDefaultPacerOptions().debouncer,
+    ...options,
+  } as DebouncerOptions<TFn>
+
+  const [debouncer] = useState(() => new Debouncer(fn, mergedOptions))
+
+  debouncer.fn = fn
+  debouncer.setOptions(mergedOptions)
+
+  useEffect(() => {
+    return () => {
+      debouncer.cancel()
+    }
+  }, [debouncer])
+
+  const state = useStore(debouncer.store, selector)
+
+  return useMemo(
+    () =>
+      ({
+        ...debouncer,
+        state,
+      }) as PreactDebouncer<TFn, TSelected>, // omit `store` in favor of `state`
+    [debouncer, state],
+  )
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+// re-export everything from the core pacer package
+export * from '@tanstack/pacer'
+
+// provider
+export * from './provider/PacerProvider'
+
+/**
+ * Export every hook individually - DON'T export from barrel files
+ */
+
+// async-batcher
+export * from './async-batcher/useAsyncBatcher'
+export * from './async-batcher/useAsyncBatchedCallback'
+
+// async-debouncer
+export * from './async-debouncer/useAsyncDebouncer'
+export * from './async-debouncer/useAsyncDebouncedCallback'
+
+// async-queuer
+export * from './async-queuer/useAsyncQueuer'
+export * from './async-queuer/useAsyncQueuedState'
+
+// async-rate-limiter
+export * from './async-rate-limiter/useAsyncRateLimiter'
+export * from './async-rate-limiter/useAsyncRateLimitedCallback'
+
+// async-throttler
+export * from './async-throttler/useAsyncThrottler'
+export * from './async-throttler/useAsyncThrottledCallback'
+
+// batcher
+export * from './batcher/useBatcher'
+export * from './batcher/useBatchedCallback'
+
+// debouncer
+export * from './debouncer/useDebouncedCallback'
+export * from './debouncer/useDebouncedState'
+export * from './debouncer/useDebouncedValue'
+export * from './debouncer/useDebouncer'
+
+// queuer
+export * from './queuer/useQueuer'
+export * from './queuer/useQueuedState'
+export * from './queuer/useQueuedValue'
+
+// rate-limiter
+export * from './rate-limiter/useRateLimitedCallback'
+export * from './rate-limiter/useRateLimiter'
+export * from './rate-limiter/useRateLimitedState'
+export * from './rate-limiter/useRateLimitedValue'
+
+// throttler
+export * from './throttler/useThrottledCallback'
+export * from './throttler/useThrottledState'
+export * from './throttler/useThrottledValue'
+export * from './throttler/useThrottler'

package/src/provider/PacerProvider.tsx

@@ -0,0 +1,70 @@
+import { useContext, useMemo } from 'preact/hooks'
+import { createContext } from 'preact'
+import type { ComponentChildren } from 'preact'
+import type {
+  AnyAsyncFunction,
+  AnyFunction,
+  AsyncBatcherOptions,
+  AsyncDebouncerOptions,
+  AsyncQueuerOptions,
+  AsyncRateLimiterOptions,
+  AsyncThrottlerOptions,
+  BatcherOptions,
+  DebouncerOptions,
+  QueuerOptions,
+  RateLimiterOptions,
+  ThrottlerOptions,
+} from '@tanstack/pacer'
+
+export interface PacerProviderOptions {
+  asyncBatcher?: Partial<AsyncBatcherOptions<any>>
+  asyncDebouncer?: Partial<AsyncDebouncerOptions<AnyAsyncFunction>>
+  asyncQueuer?: Partial<AsyncQueuerOptions<any>>
+  asyncRateLimiter?: Partial<AsyncRateLimiterOptions<AnyAsyncFunction>>
+  asyncThrottler?: Partial<AsyncThrottlerOptions<AnyAsyncFunction>>
+  batcher?: Partial<BatcherOptions<any>>
+  debouncer?: Partial<DebouncerOptions<AnyFunction>>
+  queuer?: Partial<QueuerOptions<any>>
+  rateLimiter?: Partial<RateLimiterOptions<AnyFunction>>
+  throttler?: Partial<ThrottlerOptions<AnyFunction>>
+}
+
+interface PacerContextValue {
+  defaultOptions: PacerProviderOptions
+}
+
+const PacerContext = createContext<PacerContextValue | null>(null)
+
+export interface PacerProviderProps {
+  children: ComponentChildren
+  defaultOptions?: PacerProviderOptions
+}
+
+const DEFAULT_OPTIONS: PacerProviderOptions = {}
+
+export function PacerProvider({
+  children,
+  defaultOptions = DEFAULT_OPTIONS,
+}: PacerProviderProps) {
+  const contextValue: PacerContextValue = useMemo(
+    () => ({
+      defaultOptions,
+    }),
+    [defaultOptions],
+  )
+
+  return (
+    <PacerContext.Provider value={contextValue}>
+      {children}
+    </PacerContext.Provider>
+  )
+}
+
+export function usePacerContext() {
+  return useContext(PacerContext)
+}
+
+export function useDefaultPacerOptions() {
+  const context = useContext(PacerContext)
+  return context?.defaultOptions ?? {}
+}

package/src/provider/index.ts

@@ -0,0 +1 @@
+export * from './PacerProvider'

package/src/queuer/index.ts

@@ -0,0 +1,5 @@
+export * from '@tanstack/pacer/queuer'
+
+export * from './useQueuer'
+export * from './useQueuedState'
+export * from './useQueuedValue'

package/src/queuer/useQueuedState.ts

@@ -0,0 +1,133 @@
+import { useQueuer } from './useQueuer'
+import type { PreactQueuer } from './useQueuer'
+import type { Queuer, QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
+
+/**
+ * A Preact hook that creates a queuer with managed state, combining Preact's useState with queuing functionality.
+ * This hook provides both the current queue state and queue control methods.
+ *
+ * The queue state is automatically updated whenever items are added, removed, or reordered in the queue.
+ * All queue operations are reflected in the state array returned by the hook.
+ *
+ * The queue can be started and stopped to automatically process items at a specified interval,
+ * making it useful as a scheduler. When started, it will process one item per tick, with an
+ * optional wait time between ticks.
+ *
+ * The hook returns a tuple containing:
+ * - The current queue state as an array
+ * - The queue instance with methods for queue manipulation
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying queuer instance.
+ * The `selector` parameter allows you to specify which 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 queuer state properties:
+ * - `executionCount`: Number of items that have been processed by the queuer
+ * - `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
+ * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item
+ * - `rejectionCount`: Number of items that have been rejected from being added
+ * - `size`: Number of items currently in the queue
+ * - `status`: Current processing status ('idle' | 'running' | 'stopped')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   {
+ *     initialItems: ['item1', 'item2'],
+ *     started: true,
+ *     wait: 1000,
+ *     getPriority: (item) => item.priority
+ *   }
+ * );
+ *
+ * // Opt-in to re-render when queue contents change (optimized for displaying queue items)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     items: state.items,
+ *     size: state.size,
+ *     isEmpty: state.isEmpty
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when processing state changes (optimized for loading indicators)
+ * const [items, addItem, queue] = useQueuedState(
+ *   (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 [items, addItem, queue] = useQueuedState(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 },
+ *   (state) => ({
+ *     executionCount: state.executionCount,
+ *     expirationCount: state.expirationCount,
+ *     rejectionCount: state.rejectionCount
+ *   })
+ * );
+ *
+ * // Add items to queue
+ * const handleAdd = (item) => {
+ *   addItem(item);
+ * };
+ *
+ * // Start automatic processing
+ * const startProcessing = () => {
+ *   queue.start();
+ * };
+ *
+ * // Stop automatic processing
+ * const stopProcessing = () => {
+ *   queue.stop();
+ * };
+ *
+ * // Manual processing still available
+ * const handleProcess = () => {
+ *   const nextItem = queue.getNextItem();
+ *   if (nextItem) {
+ *     processItem(nextItem);
+ *   }
+ * };
+ *
+ * // Access the selected queuer state (will be empty object {} unless selector provided)
+ * const { size, isRunning, executionCount } = queue.state;
+ * ```
+ */
+export function useQueuedState<
+  TValue,
+  TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<
+    QueuerState<TValue>,
+    'items'
+  >,
+>(
+  fn: (item: TValue) => void,
+  options: QueuerOptions<TValue> = {},
+  selector?: (state: QueuerState<TValue>) => TSelected,
+): [Array<TValue>, Queuer<TValue>['addItem'], PreactQueuer<TValue, TSelected>] {
+  const queue = useQueuer(fn, options, selector)
+
+  return [queue.state.items, queue.addItem, queue]
+}

package/src/queuer/useQueuedValue.ts

@@ -0,0 +1,129 @@
+import { useEffect, useState } from 'preact/hooks'
+import { useQueuedState } from './useQueuedState'
+import type { PreactQueuer } from './useQueuer'
+import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
+
+/**
+ * A Preact hook that creates a queued value that processes state changes in order with an optional delay.
+ * This hook uses useQueuer internally to manage a queue of state changes and apply them sequentially.
+ *
+ * The queued value will process changes in the order they are received, with optional delays between
+ * processing each change. This is useful for handling state updates that need to be processed
+ * in a specific order, like animations or sequential UI updates.
+ *
+ * The hook returns a tuple containing:
+ * - The current queued value
+ * - The queuer instance with control methods
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying queuer instance.
+ * The `selector` parameter allows you to specify which 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 queuer state properties:
+ * - `executionCount`: Number of items that have been processed by the queuer
+ * - `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
+ * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item
+ * - `rejectionCount`: Number of items that have been rejected from being added
+ * - `size`: Number of items currently in the queue
+ * - `status`: Current processing status ('idle' | 'running' | 'stopped')
+ *
+ * @example
+ * ```tsx
+ * // 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;
+ * ```
+ */
+export function useQueuedValue<
+  TValue,
+  TSelected extends Pick<QueuerState<TValue>, 'items'> = Pick<
+    QueuerState<TValue>,
+    'items'
+  >,
+>(
+  initialValue: TValue,
+  options: QueuerOptions<TValue> = {},
+  selector?: (state: QueuerState<TValue>) => TSelected,
+): [TValue, PreactQueuer<TValue, TSelected>] {
+  const [value, setValue] = useState<TValue>(initialValue)
+
+  const [, addItem, queuer] = useQueuedState(
+    (item) => {
+      setValue(item)
+    },
+    options,
+    selector,
+  )
+
+  useEffect(() => {
+    addItem(initialValue)
+  }, [initialValue, addItem])
+
+  return [value, queuer]
+}

package/src/queuer/useQueuer.ts

@@ -0,0 +1,160 @@
+import { useMemo, useState } from 'preact/hooks'
+import { Queuer } from '@tanstack/pacer/queuer'
+import { useStore } from '@tanstack/preact-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
+import type { Store } from '@tanstack/preact-store'
+import type { QueuerOptions, QueuerState } from '@tanstack/pacer/queuer'
+
+export interface PreactQueuer<TValue, TSelected = {}> extends Omit<
+  Queuer<TValue>,
+  'store'
+> {
+  /**
+   * Reactive state that will be updated and re-rendered when the queuer state changes
+   *
+   * Use this instead of `queuer.store.state`
+   */
+  readonly state: Readonly<TSelected>
+  /**
+   * @deprecated Use `queuer.state` instead of `queuer.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<QueuerState<TValue>>>
+}
+
+/**
+ * A Preact hook that creates and manages a Queuer instance.
+ *
+ * This is a lower-level hook that provides direct access to the Queuer's functionality without
+ * any built-in state management. This allows you to integrate it with any state management solution
+ * you prefer (useState, Redux, Zustand, etc.) by utilizing the onItemsChange callback.
+ *
+ * For a hook with built-in state management, see useQueuedState.
+ *
+ * The Queuer extends the base Queue to add processing capabilities. Items are processed
+ * synchronously in order, with optional delays between processing each item. The queuer includes
+ * an internal tick mechanism that can be started and stopped, making it useful as a scheduler.
+ * When started, it will process one item per tick, with an optional wait time between ticks.
+ *
+ * By default uses FIFO (First In First Out) behavior, but can be configured for LIFO
+ * (Last In First Out) by specifying 'front' position when adding items.
+ *
+ * ## 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:
+ * - `executionCount`: Number of items that have been processed by the queuer
+ * - `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
+ * - `pendingTick`: Whether the queuer has a pending timeout for processing the next item
+ * - `rejectionCount`: Number of items that have been rejected from being added
+ * - `size`: Number of items currently in the queue
+ * - `status`: Current processing status ('idle' | 'running' | 'stopped')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const queue = useQueuer(
+ *   (item) => console.log('Processing:', item),
+ *   { started: true, wait: 1000 }
+ * );
+ *
+ * // Opt-in to re-render when queue size changes (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;
+ * ```
+ */
+export function useQueuer<TValue, TSelected = {}>(
+  fn: (item: TValue) => void,
+  options: QueuerOptions<TValue> = {},
+  selector: (state: QueuerState<TValue>) => TSelected = () => ({}) as TSelected,
+): PreactQueuer<TValue, TSelected> {
+  const mergedOptions = {
+    ...useDefaultPacerOptions().queuer,
+    ...options,
+  } as QueuerOptions<TValue>
+
+  const [queuer] = useState(() => new Queuer<TValue>(fn, mergedOptions))
+
+  queuer.fn = fn
+  queuer.setOptions(mergedOptions)
+
+  const state = useStore(queuer.store, selector)
+
+  return useMemo(
+    () =>
+      ({
+        ...queuer,
+        state,
+      }) as PreactQueuer<TValue, TSelected>, // omit `store` in favor of `state`
+    [queuer, state],
+  )
+}