@tanstack/preact-pacer 0.0.1 → 0.19.0

package/src/async-throttler/useAsyncThrottler.ts

@@ -0,0 +1,244 @@
+import { useEffect, useMemo, useState } from 'preact/hooks'
+import { AsyncThrottler } from '@tanstack/pacer/async-throttler'
+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 {
+  AsyncThrottlerOptions,
+  AsyncThrottlerState,
+} from '@tanstack/pacer/async-throttler'
+import type { ComponentChildren } from 'preact'
+
+export interface PreactAsyncThrottler<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends Omit<AsyncThrottler<TFn>, 'store'> {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the async throttler state.
+   *
+   * This is useful for opting into state re-renders for specific parts of the throttler state
+   * deep in your component tree without needing to pass a selector to the hook.
+   *
+   * @example
+   * <throttler.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+   *   {({ isPending }) => (
+   *     <div>{isPending ? 'Loading...' : 'Ready'}</div>
+   *   )}
+   * </throttler.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: AsyncThrottlerState<TFn>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
+  /**
+   * Reactive state that will be updated and re-rendered when the throttler state changes
+   *
+   * Use this instead of `throttler.store.state`
+   */
+  readonly state: Readonly<TSelected>
+  /**
+   * @deprecated Use `throttler.state` instead of `throttler.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<AsyncThrottlerState<TFn>>>
+}
+
+/**
+ * A low-level Preact hook that creates an `AsyncThrottler` instance to limit how often an async function can execute.
+ *
+ * This hook is designed to be flexible and state-management agnostic - it simply returns a throttler instance that
+ * you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc).
+ *
+ * Async throttling ensures an async function executes at most once within a specified time window,
+ * regardless of how many times it is called. This is useful for rate-limiting expensive API calls,
+ * database operations, or other async tasks.
+ *
+ * Unlike the non-async Throttler, this async version supports returning values from the throttled 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 throttled function.
+ *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler 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 AsyncThrottler 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 `throttler.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:
+ * - `errorCount`: Number of function executions that have resulted in errors
+ * - `isExecuting`: Whether the throttled function is currently executing asynchronously
+ * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `lastExecutionTime`: Timestamp of the last function execution in milliseconds
+ * - `lastResult`: The result from the most recent successful function execution
+ * - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
+ * - `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 asyncThrottler = useAsyncThrottler(
+ *   async (id: string) => {
+ *     const data = await api.fetchData(id);
+ *     return data; // Return value is preserved
+ *   },
+ *   { wait: 1000 }
+ * );
+ *
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <asyncThrottler.Subscribe selector={(state) => ({ isPending: state.isPending })}>
+ *   {({ isPending }) => (
+ *     <div>{isPending ? 'Processing...' : 'Ready'}</div>
+ *   )}
+ * </asyncThrottler.Subscribe>
+ *
+ * // Opt-in to re-render when execution state changes at hook level (optimized for loading indicators)
+ * const asyncThrottler = useAsyncThrottler(
+ *   async (id: string) => {
+ *     const data = await api.fetchData(id);
+ *     return data;
+ *   },
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     isExecuting: state.isExecuting,
+ *     isPending: state.isPending,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when results are available (optimized for data display)
+ * const asyncThrottler = useAsyncThrottler(
+ *   async (id: string) => {
+ *     const data = await api.fetchData(id);
+ *     return data;
+ *   },
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     lastResult: state.lastResult,
+ *     successCount: state.successCount,
+ *     settleCount: state.settleCount
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when error state changes (optimized for error handling)
+ * const asyncThrottler = useAsyncThrottler(
+ *   async (id: string) => {
+ *     const data = await api.fetchData(id);
+ *     return data;
+ *   },
+ *   {
+ *     wait: 1000,
+ *     onError: (error) => console.error('API call failed:', error)
+ *   },
+ *   (state) => ({
+ *     errorCount: state.errorCount,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when timing information changes (optimized for timing displays)
+ * const asyncThrottler = useAsyncThrottler(
+ *   async (id: string) => {
+ *     const data = await api.fetchData(id);
+ *     return data;
+ *   },
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     lastExecutionTime: state.lastExecutionTime,
+ *     nextExecutionTime: state.nextExecutionTime
+ *   })
+ * );
+ *
+ * // With state management and return value
+ * const [data, setData] = useState(null);
+ * const { maybeExecute, state } = useAsyncThrottler(
+ *   async (query) => {
+ *     const result = await searchAPI(query);
+ *     setData(result);
+ *     return result; // Return value can be used by the caller
+ *   },
+ *   {
+ *     wait: 2000,
+ *     leading: true,   // Execute immediately on first call
+ *     trailing: false  // Skip trailing edge updates
+ *   }
+ * );
+ *
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { isExecuting, lastResult } = state;
+ * ```
+ */
+export function useAsyncThrottler<TFn extends AnyAsyncFunction, TSelected = {}>(
+  fn: TFn,
+  options: AsyncThrottlerOptions<TFn>,
+  selector: (state: AsyncThrottlerState<TFn>) => TSelected = () =>
+    ({}) as TSelected,
+): PreactAsyncThrottler<TFn, TSelected> {
+  const mergedOptions = {
+    ...useDefaultPacerOptions().asyncThrottler,
+    ...options,
+  } as AsyncThrottlerOptions<TFn>
+
+  const [asyncThrottler] = useState(() => {
+    const throttlerInstance = new AsyncThrottler<TFn>(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactAsyncThrottler<TFn, TSelected>
+
+    throttlerInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: AsyncThrottlerState<TFn>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(throttlerInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return throttlerInstance
+  })
+
+  asyncThrottler.fn = fn
+  asyncThrottler.setOptions(mergedOptions)
+
+  const state = useStore(asyncThrottler.store, selector)
+
+  useEffect(() => {
+    return () => asyncThrottler.cancel()
+  }, [asyncThrottler])
+
+  return useMemo(
+    () =>
+      ({
+        ...asyncThrottler,
+        state,
+      }) as PreactAsyncThrottler<TFn, TSelected>, // omit `store` in favor of `state`
+    [asyncThrottler, state],
+  )
+}

package/src/batcher/index.ts

@@ -0,0 +1,4 @@
+export * from '@tanstack/pacer/batcher'
+
+export * from './useBatcher'
+export * from './useBatchedCallback'

package/src/batcher/useBatchedCallback.ts

@@ -0,0 +1,50 @@
+import { useCallback } from 'preact/hooks'
+import { useBatcher } from './useBatcher'
+import type { BatcherOptions } from '@tanstack/pacer/batcher'
+import type { AnyFunction } from '@tanstack/pacer/types'
+
+/**
+ * A Preact hook that creates a batched version of a callback function.
+ * This hook is essentially a wrapper around the basic `batch` function
+ * that is exported from `@tanstack/pacer`,
+ * but optimized for Preact with reactive options and a stable function reference.
+ *
+ * The batched function will collect individual calls into batches and execute them
+ * when batch conditions are met (max size reached, wait time elapsed, or custom logic).
+ *
+ * This hook provides a simpler API compared to `useBatcher`, making it ideal for basic
+ * batching needs. However, it does not expose the underlying Batcher instance.
+ *
+ * For advanced usage requiring features like:
+ * - Manual batch execution
+ * - Access to batch state and metrics
+ * - Custom useCallback dependencies
+ *
+ * Consider using the `useBatcher` hook instead.
+ *
+ * @example
+ * ```tsx
+ * // Batch analytics events
+ * const trackEvents = useBatchedCallback((events: AnalyticsEvent[]) => {
+ *   sendAnalytics(events);
+ * }, {
+ *   maxSize: 5,    // Process when 5 events collected
+ *   wait: 2000     // Or after 2 seconds
+ * });
+ *
+ * // Use in event handlers
+ * <button onClick={() => trackEvents({ type: 'click', target: 'button' })}>
+ *   Click me
+ * </button>
+ * ```
+ */
+export function useBatchedCallback<TFn extends AnyFunction>(
+  fn: (items: Array<Parameters<TFn>[0]>) => void,
+  options: BatcherOptions<Parameters<TFn>[0]>,
+): (...args: Parameters<TFn>) => void {
+  const batchedFn = useBatcher(fn, options).addItem
+  return useCallback(
+    (...args: Parameters<TFn>) => batchedFn(args[0]),
+    [batchedFn],
+  )
+}

package/src/batcher/useBatcher.ts

@@ -0,0 +1,203 @@
+import { useMemo, useState } from 'preact/hooks'
+import { Batcher } from '@tanstack/pacer/batcher'
+import { useStore } from '@tanstack/preact-store'
+import { useDefaultPacerOptions } from '../provider/PacerProvider'
+import type { Store } from '@tanstack/preact-store'
+import type { BatcherOptions, BatcherState } from '@tanstack/pacer/batcher'
+import type { ComponentChildren } from 'preact'
+
+export interface PreactBatcher<TValue, TSelected = {}> extends Omit<
+  Batcher<TValue>,
+  'store'
+> {
+  /**
+   * A Preact HOC (Higher Order Component) that allows you to subscribe to the batcher state.
+   *
+   * This is useful for opting into state re-renders for specific parts of the batcher state
+   * deep in your component tree without needing to pass a selector to the hook.
+   *
+   * @example
+   * <batcher.Subscribe selector={(state) => ({ size: state.size })}>
+   *   {({ size }) => (
+   *     <div>Batch Size: {size}</div>
+   *   )}
+   * </batcher.Subscribe>
+   */
+  Subscribe: <TSelected>(props: {
+    selector: (state: BatcherState<TValue>) => TSelected
+    children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+  }) => ComponentChildren
+  /**
+   * 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<BatcherState<TValue>>>
+}
+
+/**
+ * A Preact hook that creates and manages a Batcher instance.
+ *
+ * This is a lower-level hook that provides direct access to the Batcher'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.
+ *
+ * The Batcher collects items and processes them in batches based on configurable conditions:
+ * - Maximum batch size
+ * - Time-based batching (process after X milliseconds)
+ * - Custom batch processing logic via getShouldExecute
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management. You can subscribe to state changes
+ * in two ways:
+ *
+ * **1. Using `batcher.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:
+ * - `executionCount`: Number of batch executions that have been completed
+ * - `isEmpty`: Whether the batcher has no items to process
+ * - `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
+ * - `size`: Number of items currently in the batch queue
+ * - `status`: Current processing status ('idle' | 'pending')
+ * - `totalItemsProcessed`: Total number of items processed across all batches
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const batcher = useBatcher<number>(
+ *   (items) => console.log('Processing batch:', items),
+ *   { maxSize: 5, wait: 2000 }
+ * );
+ *
+ * // Subscribe to state changes deep in component tree using Subscribe HOC
+ * <batcher.Subscribe selector={(state) => ({ size: state.size })}>
+ *   {({ size }) => (
+ *     <div>Batch Size: {size}</div>
+ *   )}
+ * </batcher.Subscribe>
+ *
+ * // Opt-in to re-render when batch size changes at hook level (optimized for displaying queue size)
+ * const batcher = useBatcher<number>(
+ *   (items) => console.log('Processing batch:', items),
+ *   { maxSize: 5, wait: 2000 },
+ *   (state) => ({
+ *     size: state.size,
+ *     isEmpty: state.isEmpty
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when execution metrics change (optimized for stats display)
+ * const batcher = useBatcher<number>(
+ *   (items) => console.log('Processing batch:', items),
+ *   { maxSize: 5, wait: 2000 },
+ *   (state) => ({
+ *     executionCount: state.executionCount,
+ *     totalItemsProcessed: state.totalItemsProcessed
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when processing state changes (optimized for loading indicators)
+ * const batcher = useBatcher<number>(
+ *   (items) => console.log('Processing batch:', items),
+ *   { maxSize: 5, wait: 2000 },
+ *   (state) => ({
+ *     isPending: state.isPending,
+ *     isRunning: state.isRunning,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // Example with custom state management and batching
+ * const [items, setItems] = useState([]);
+ *
+ * const batcher = useBatcher<number>(
+ *   (items) => console.log('Processing batch:', items),
+ *   {
+ *     maxSize: 5,
+ *     wait: 2000,
+ *     onItemsChange: (batcher) => setItems(batcher.peekAllItems()),
+ *     getShouldExecute: (items) => items.length >= 3
+ *   }
+ * );
+ *
+ * // Add items to batch - they'll be processed when conditions are met
+ * batcher.addItem(1);
+ * batcher.addItem(2);
+ * batcher.addItem(3); // Triggers batch processing
+ *
+ * // Control the batcher
+ * batcher.stop();  // Pause batching
+ * batcher.start(); // Resume batching
+ *
+ * // Access the selected state (will be empty object {} unless selector provided)
+ * const { size, isPending } = batcher.state;
+ * ```
+ */
+export function useBatcher<TValue, TSelected = {}>(
+  fn: (items: Array<TValue>) => void,
+  options: BatcherOptions<TValue> = {},
+  selector: (state: BatcherState<TValue>) => TSelected = () =>
+    ({}) as TSelected,
+): PreactBatcher<TValue, TSelected> {
+  const mergedOptions = {
+    ...useDefaultPacerOptions().batcher,
+    ...options,
+  } as BatcherOptions<TValue>
+
+  const [batcher] = useState(() => {
+    const batcherInstance = new Batcher<TValue>(
+      fn,
+      mergedOptions,
+    ) as unknown as PreactBatcher<TValue, TSelected>
+
+    batcherInstance.Subscribe = function Subscribe<TSelected>(props: {
+      selector: (state: BatcherState<TValue>) => TSelected
+      children: ((state: TSelected) => ComponentChildren) | ComponentChildren
+    }) {
+      const selected = useStore(batcherInstance.store, props.selector)
+
+      return typeof props.children === 'function'
+        ? props.children(selected)
+        : props.children
+    }
+
+    return batcherInstance
+  })
+
+  batcher.fn = fn
+  batcher.setOptions(mergedOptions)
+
+  const state = useStore(batcher.store, selector)
+
+  return useMemo(
+    () =>
+      ({
+        ...batcher,
+        state,
+      }) as PreactBatcher<TValue, TSelected>, // omit `store` in favor of `state`
+    [batcher, state],
+  )
+}

package/src/debouncer/index.ts

@@ -0,0 +1,7 @@
+// re-export everything from the core pacer package, BUT ONLY from the debouncer module
+export * from '@tanstack/pacer/debouncer'
+
+export * from './useDebouncedCallback'
+export * from './useDebouncedState'
+export * from './useDebouncedValue'
+export * from './useDebouncer'

package/src/debouncer/useDebouncedCallback.ts

@@ -0,0 +1,51 @@
+import { useCallback } from 'preact/hooks'
+import { useDebouncer } from './useDebouncer'
+import type { DebouncerOptions } from '@tanstack/pacer/debouncer'
+import type { AnyFunction } from '@tanstack/pacer/types'
+
+/**
+ * A Preact hook that creates a debounced version of a callback function.
+ * This hook is essentially a wrapper around the basic `debounce` function
+ * that is exported from `@tanstack/pacer`,
+ * but optimized for Preact with reactive options and a stable function reference.
+ *
+ * The debounced 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.
+ *
+ * This hook provides a simpler API compared to `useDebouncer`, making it ideal for basic
+ * debouncing needs. However, it does not expose the underlying Debouncer instance.
+ *
+ * For advanced usage requiring features like:
+ * - Manual cancellation
+ * - Access to execution counts
+ * - Custom useCallback dependencies
+ *
+ * Consider using the `useDebouncer` hook instead.
+ *
+ * @example
+ * ```tsx
+ * // Debounce a search handler
+ * const handleSearch = useDebouncedCallback((query: string) => {
+ *   fetchSearchResults(query);
+ * }, {
+ *   wait: 500 // Wait 500ms between executions
+ * });
+ *
+ * // Use in an input
+ * <input
+ *   type="search"
+ *   onChange={(e) => handleSearch(e.target.value)}
+ * />
+ * ```
+ */
+export function useDebouncedCallback<TFn extends AnyFunction>(
+  fn: TFn,
+  options: DebouncerOptions<TFn>,
+): (...args: Parameters<TFn>) => void {
+  const debouncedFn = useDebouncer(fn, options).maybeExecute
+  return useCallback(
+    (...args: Parameters<TFn>) => debouncedFn(...args),
+    [debouncedFn],
+  )
+}

package/src/debouncer/useDebouncedState.ts

@@ -0,0 +1,109 @@
+import { useState } from 'preact/hooks'
+import { useDebouncer } from './useDebouncer'
+import type { Dispatch, StateUpdater } from 'preact/hooks'
+import type { PreactDebouncer } from './useDebouncer'
+import type {
+  DebouncerOptions,
+  DebouncerState,
+} from '@tanstack/pacer/debouncer'
+
+/**
+ * A Preact hook that creates a debounced state value, combining Preact's useState with debouncing functionality.
+ * This hook provides both the current debounced value and methods to update it.
+ *
+ * The state value is only updated after the specified wait time has elapsed since the last update attempt.
+ * If another update is attempted before the wait time expires, the timer resets and starts waiting again.
+ * This is useful for handling frequent state updates that should be throttled, like search input values
+ * or window resize dimensions.
+ *
+ * The hook returns a tuple containing:
+ * - The current debounced value
+ * - A function to update the debounced value
+ * - The debouncer instance with additional control methods
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying debouncer instance.
+ * The `selector` parameter allows you to specify which debouncer 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 debouncer 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 [searchTerm, setSearchTerm, debouncer] = useDebouncedState('', {
+ *   wait: 500 // Wait 500ms after last keystroke
+ * });
+ *
+ * // Opt-in to re-render when pending state changes (optimized for loading indicators)
+ * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(
+ *   '',
+ *   { wait: 500 },
+ *   (state) => ({ isPending: state.isPending })
+ * );
+ *
+ * // Opt-in to re-render when execution count changes (optimized for tracking executions)
+ * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(
+ *   '',
+ *   { wait: 500 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
+ * // Opt-in to re-render when debouncing status changes (optimized for status display)
+ * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(
+ *   '',
+ *   { wait: 500 },
+ *   (state) => ({
+ *     status: state.status,
+ *     canLeadingExecute: state.canLeadingExecute
+ *   })
+ * );
+ *
+ * // Update value - will be debounced
+ * const handleChange = (e) => {
+ *   setSearchTerm(e.target.value);
+ * };
+ *
+ * // Access the selected debouncer state (will be empty object {} unless selector provided)
+ * const { isPending, executionCount } = debouncer.state;
+ * ```
+ */
+export function useDebouncedState<
+  TValue,
+  TSelected = DebouncerState<Dispatch<StateUpdater<TValue>>>,
+>(
+  value: TValue,
+  options: DebouncerOptions<Dispatch<StateUpdater<TValue>>>,
+  selector?: (
+    state: DebouncerState<Dispatch<StateUpdater<TValue>>>,
+  ) => TSelected,
+): [
+  TValue,
+  Dispatch<StateUpdater<TValue>>,
+  PreactDebouncer<Dispatch<StateUpdater<TValue>>, TSelected>,
+] {
+  const [debouncedValue, setDebouncedValue] = useState(value)
+  const debouncer = useDebouncer(
+    setDebouncedValue,
+    options,
+    selector as (
+      state: DebouncerState<Dispatch<StateUpdater<TValue>>>,
+    ) => TSelected,
+  )
+  return [
+    debouncedValue,
+    debouncer.maybeExecute as Dispatch<StateUpdater<TValue>>,
+    debouncer,
+  ]
+}