@tanstack/preact-pacer 0.0.1 → 0.18.0

package/src/async-throttler/useAsyncThrottler.ts

@@ -0,0 +1,193 @@
+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'
+
+export interface ReactAsyncThrottler<
+  TFn extends AnyAsyncFunction,
+  TSelected = {},
+> extends Omit<AsyncThrottler<TFn>, 'store'> {
+  /**
+   * 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. 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 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 }
+ * );
+ *
+ * // Opt-in to re-render when execution state changes (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,
+): ReactAsyncThrottler<TFn, TSelected> {
+  const mergedOptions = {
+    ...useDefaultPacerOptions().asyncThrottler,
+    ...options,
+  } as AsyncThrottlerOptions<TFn>
+
+  const [asyncThrottler] = useState(
+    () => new AsyncThrottler<TFn>(fn, mergedOptions),
+  )
+
+  asyncThrottler.fn = fn
+  asyncThrottler.setOptions(mergedOptions)
+
+  const state = useStore(asyncThrottler.store, selector)
+
+  useEffect(() => {
+    return () => asyncThrottler.cancel()
+  }, [asyncThrottler])
+
+  return useMemo(
+    () =>
+      ({
+        ...asyncThrottler,
+        state,
+      }) as ReactAsyncThrottler<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,150 @@
+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'
+
+export interface PreactBatcher<TValue, TSelected = {}> extends Omit<
+  Batcher<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<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. 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 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 }
+ * );
+ *
+ * // Opt-in to re-render when batch size changes (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(() => new Batcher<TValue>(fn, mergedOptions))
+
+  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,
+  ]
+}

package/src/debouncer/useDebouncedValue.ts

@@ -0,0 +1,112 @@
+import { useEffect } from 'preact/hooks'
+import { useDebouncedState } from './useDebouncedState'
+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 value that updates only after a specified delay.
+ * Unlike useDebouncedState, this hook automatically tracks changes to the input value
+ * and updates the debounced value accordingly.
+ *
+ * The debounced value will only update after the specified wait time has elapsed since
+ * the last change to the input value. If the input value changes again before the wait
+ * time expires, the timer resets and starts waiting again.
+ *
+ * This is useful for deriving debounced values from props or state that change frequently,
+ * like search queries or form inputs, where you want to limit how often downstream effects
+ * or calculations occur.
+ *
+ * The hook returns the current debounced value and the underlying debouncer instance.
+ * The debouncer instance can be used to access additional functionality like cancellation
+ * and execution counts.
+ *
+ * ## 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 [searchQuery, setSearchQuery] = useState('');
+ * const [debouncedQuery, debouncer] = useDebouncedValue(searchQuery, {
+ *   wait: 500 // Wait 500ms after last change
+ * });
+ *
+ * // Opt-in to re-render when pending state changes (optimized for loading indicators)
+ * const [debouncedQuery, debouncer] = useDebouncedValue(
+ *   searchQuery,
+ *   { wait: 500 },
+ *   (state) => ({ isPending: state.isPending })
+ * );
+ *
+ * // Opt-in to re-render when execution count changes (optimized for tracking executions)
+ * const [debouncedQuery, debouncer] = useDebouncedValue(
+ *   searchQuery,
+ *   { wait: 500 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
+ * // Opt-in to re-render when debouncing status changes (optimized for status display)
+ * const [debouncedQuery, debouncer] = useDebouncedValue(
+ *   searchQuery,
+ *   { wait: 500 },
+ *   (state) => ({
+ *     status: state.status,
+ *     canLeadingExecute: state.canLeadingExecute
+ *   })
+ * );
+ *
+ * // debouncedQuery will update 500ms after searchQuery stops changing
+ * useEffect(() => {
+ *   fetchSearchResults(debouncedQuery);
+ * }, [debouncedQuery]);
+ *
+ * // Handle input changes
+ * const handleChange = (e) => {
+ *   setSearchQuery(e.target.value);
+ * };
+ *
+ * // Access the selected debouncer state (will be empty object {} unless selector provided)
+ * const { isPending, executionCount } = debouncer.state;
+ * ```
+ */
+export function useDebouncedValue<
+  TValue,
+  TSelected = DebouncerState<Dispatch<StateUpdater<TValue>>>,
+>(
+  value: TValue,
+  options: DebouncerOptions<Dispatch<StateUpdater<TValue>>>,
+  selector?: (
+    state: DebouncerState<Dispatch<StateUpdater<TValue>>>,
+  ) => TSelected,
+): [TValue, PreactDebouncer<Dispatch<StateUpdater<TValue>>, TSelected>] {
+  const [debouncedValue, setDebouncedValue, debouncer] = useDebouncedState(
+    value,
+    options,
+    selector,
+  )
+
+  useEffect(() => {
+    ;(setDebouncedValue as (value: TValue) => void)(value)
+  }, [value, setDebouncedValue])
+
+  return [debouncedValue, debouncer]
+}