@tanstack/preact-pacer 0.0.1 → 0.19.0

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,235 @@
+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'
+import type { ComponentChildren } from 'preact'
+
+export interface PreactAsyncDebouncer<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends Omit<AsyncDebouncer<TFn>, 'store'> {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the async debouncer state.
+   *
+   * This is useful for opting into state re-renders for specific parts of the debouncer state
+   * deep in your component tree without needing to pass a selector to the hook.
+   *
+   * @example
+   * <debouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+   *   {({ isPending }) => (
+   *     <div>{isPending ? 'Loading...' : 'Ready'}</div>
+   *   )}
+   * </debouncer.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: AsyncDebouncerState<TFn>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
+  /**
+   * 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. You can subscribe to state changes
+ * in two ways:
+ *
+ * **1. Using `debouncer.Subscribe` HOC (Recommended for component tree subscriptions)**
+ *
+ * Use the `Subscribe` HOC to subscribe to state changes deep in your component tree without
+ * needing to pass a selector to the hook. This is ideal when you want to subscribe to state
+ * in child components.
+ *
+ * **2. Using the `selector` parameter (For hook-level subscriptions)**
+ *
+ * The `selector` parameter allows you to specify which state changes will trigger a re-render
+ * at the hook level, 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 or using the `Subscribe` HOC. This prevents unnecessary
+ * re-renders and gives you full control over when your component updates.
+ *
+ * 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 }
+ * );
+ *
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <searchDebouncer.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+ *   {({ isPending }) => (
+ *     <div>{isPending ? 'Searching...' : 'Ready'}</div>
+ *   )}
+ * </searchDebouncer.Subscribe>
+ *
+ * // Opt-in to re-render when execution state changes at hook level (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,
+): PreactAsyncDebouncer<TFn, TSelected> {
+  const mergedOptions = {
+    ...useDefaultPacerOptions().asyncDebouncer,
+    ...options,
+  } as AsyncDebouncerOptions<TFn>
+
+  const [asyncDebouncer] = useState(() => {
+    const debouncerInstance = new AsyncDebouncer<TFn>(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactAsyncDebouncer<TFn, TSelected>
+
+    debouncerInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: AsyncDebouncerState<TFn>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(debouncerInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return debouncerInstance
+  })
+
+  asyncDebouncer.fn = fn
+  asyncDebouncer.setOptions(mergedOptions)
+
+  const state = useStore(asyncDebouncer.store, selector)
+
+  useEffect(() => {
+    return () => {
+      asyncDebouncer.cancel()
+    }
+  }, [asyncDebouncer])
+
+  return useMemo(
+    () =>
+      ({
+        ...asyncDebouncer,
+        state,
+      }) as PreactAsyncDebouncer<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 { PreactAsyncQueuer } 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>, PreactAsyncQueuer<TValue, TSelected>] {
+  const asyncQueuer = useAsyncQueuer(fn, options, selector)
+
+  return [asyncQueuer.state.items, asyncQueuer]
+}