@tanstack/preact-pacer 0.0.1 → 0.19.0

package/dist/debouncer/useDebouncedCallback.js

@@ -0,0 +1,48 @@
+import { useDebouncer } from "./useDebouncer.js";
+import { useCallback } from "preact/hooks";
+
+//#region src/debouncer/useDebouncedCallback.ts
+/**
+* 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)}
+* />
+* ```
+*/
+function useDebouncedCallback(fn, options) {
+	const debouncedFn = useDebouncer(fn, options).maybeExecute;
+	return useCallback((...args) => debouncedFn(...args), [debouncedFn]);
+}
+
+//#endregion
+export { useDebouncedCallback };
+//# sourceMappingURL=useDebouncedCallback.js.map

package/dist/debouncer/useDebouncedCallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedCallback.js","names":[],"sources":["../../src/debouncer/useDebouncedCallback.ts"],"sourcesContent":["import { useCallback } from 'preact/hooks'\nimport { useDebouncer } from './useDebouncer'\nimport type { DebouncerOptions } from '@tanstack/pacer/debouncer'\nimport type { AnyFunction } from '@tanstack/pacer/types'\n\n/**\n * A Preact hook that creates a debounced version of a callback function.\n * This hook is essentially a wrapper around the basic `debounce` function\n * that is exported from `@tanstack/pacer`,\n * but optimized for Preact with reactive options and a stable function reference.\n *\n * The debounced function will only execute after the specified wait time has elapsed\n * since its last invocation. If called again before the wait time expires, the timer\n * resets and starts waiting again.\n *\n * This hook provides a simpler API compared to `useDebouncer`, making it ideal for basic\n * debouncing needs. However, it does not expose the underlying Debouncer instance.\n *\n * For advanced usage requiring features like:\n * - Manual cancellation\n * - Access to execution counts\n * - Custom useCallback dependencies\n *\n * Consider using the `useDebouncer` hook instead.\n *\n * @example\n * ```tsx\n * // Debounce a search handler\n * const handleSearch = useDebouncedCallback((query: string) => {\n *   fetchSearchResults(query);\n * }, {\n *   wait: 500 // Wait 500ms between executions\n * });\n *\n * // Use in an input\n * <input\n *   type=\"search\"\n *   onChange={(e) => handleSearch(e.target.value)}\n * />\n * ```\n */\nexport function useDebouncedCallback<TFn extends AnyFunction>(\n  fn: TFn,\n  options: DebouncerOptions<TFn>,\n): (...args: Parameters<TFn>) => void {\n  const debouncedFn = useDebouncer(fn, options).maybeExecute\n  return useCallback(\n    (...args: Parameters<TFn>) => debouncedFn(...args),\n    [debouncedFn],\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,qBACd,IACA,SACoC;CACpC,MAAM,cAAc,aAAa,IAAI,QAAQ,CAAC;AAC9C,QAAO,aACJ,GAAG,SAA0B,YAAY,GAAG,KAAK,EAClD,CAAC,YAAY,CACd"}

package/dist/debouncer/useDebouncedState.cjs

@@ -0,0 +1,89 @@
+const require_useDebouncer = require('./useDebouncer.cjs');
+let preact_hooks = require("preact/hooks");
+
+//#region src/debouncer/useDebouncedState.ts
+/**
+* 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;
+* ```
+*/
+function useDebouncedState(value, options, selector) {
+	const [debouncedValue, setDebouncedValue] = (0, preact_hooks.useState)(value);
+	const debouncer = require_useDebouncer.useDebouncer(setDebouncedValue, options, selector);
+	return [
+		debouncedValue,
+		debouncer.maybeExecute,
+		debouncer
+	];
+}
+
+//#endregion
+exports.useDebouncedState = useDebouncedState;
+//# sourceMappingURL=useDebouncedState.cjs.map

package/dist/debouncer/useDebouncedState.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedState.cjs","names":["useDebouncer"],"sources":["../../src/debouncer/useDebouncedState.ts"],"sourcesContent":["import { useState } from 'preact/hooks'\nimport { useDebouncer } from './useDebouncer'\nimport type { Dispatch, StateUpdater } from 'preact/hooks'\nimport type { PreactDebouncer } from './useDebouncer'\nimport type {\n  DebouncerOptions,\n  DebouncerState,\n} from '@tanstack/pacer/debouncer'\n\n/**\n * A Preact hook that creates a debounced state value, combining Preact's useState with debouncing functionality.\n * This hook provides both the current debounced value and methods to update it.\n *\n * The state value is only updated after the specified wait time has elapsed since the last update attempt.\n * If another update is attempted before the wait time expires, the timer resets and starts waiting again.\n * This is useful for handling frequent state updates that should be throttled, like search input values\n * or window resize dimensions.\n *\n * The hook returns a tuple containing:\n * - The current debounced value\n * - A function to update the debounced value\n * - The debouncer instance with additional control methods\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying debouncer instance.\n * The `selector` parameter allows you to specify which debouncer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available debouncer state properties:\n * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge\n * - `executionCount`: Number of function executions that have been completed\n * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution\n * - `lastArgs`: The arguments from the most recent call to maybeExecute\n * - `status`: Current execution status ('disabled' | 'idle' | 'pending')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState('', {\n *   wait: 500 // Wait 500ms after last keystroke\n * });\n *\n * // Opt-in to re-render when pending state changes (optimized for loading indicators)\n * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(\n *   '',\n *   { wait: 500 },\n *   (state) => ({ isPending: state.isPending })\n * );\n *\n * // Opt-in to re-render when execution count changes (optimized for tracking executions)\n * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(\n *   '',\n *   { wait: 500 },\n *   (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Opt-in to re-render when debouncing status changes (optimized for status display)\n * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(\n *   '',\n *   { wait: 500 },\n *   (state) => ({\n *     status: state.status,\n *     canLeadingExecute: state.canLeadingExecute\n *   })\n * );\n *\n * // Update value - will be debounced\n * const handleChange = (e) => {\n *   setSearchTerm(e.target.value);\n * };\n *\n * // Access the selected debouncer state (will be empty object {} unless selector provided)\n * const { isPending, executionCount } = debouncer.state;\n * ```\n */\nexport function useDebouncedState<\n  TValue,\n  TSelected = DebouncerState<Dispatch<StateUpdater<TValue>>>,\n>(\n  value: TValue,\n  options: DebouncerOptions<Dispatch<StateUpdater<TValue>>>,\n  selector?: (\n    state: DebouncerState<Dispatch<StateUpdater<TValue>>>,\n  ) => TSelected,\n): [\n  TValue,\n  Dispatch<StateUpdater<TValue>>,\n  PreactDebouncer<Dispatch<StateUpdater<TValue>>, TSelected>,\n] {\n  const [debouncedValue, setDebouncedValue] = useState(value)\n  const debouncer = useDebouncer(\n    setDebouncedValue,\n    options,\n    selector as (\n      state: DebouncerState<Dispatch<StateUpdater<TValue>>>,\n    ) => TSelected,\n  )\n  return [\n    debouncedValue,\n    debouncer.maybeExecute as Dispatch<StateUpdater<TValue>>,\n    debouncer,\n  ]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiFA,SAAgB,kBAId,OACA,SACA,UAOA;CACA,MAAM,CAAC,gBAAgB,gDAA8B,MAAM;CAC3D,MAAM,YAAYA,kCAChB,mBACA,SACA,SAGD;AACD,QAAO;EACL;EACA,UAAU;EACV;EACD"}

package/dist/debouncer/useDebouncedState.d.cts

@@ -0,0 +1,82 @@
+import { PreactDebouncer } from "./useDebouncer.cjs";
+import { DebouncerOptions, DebouncerState } from "@tanstack/pacer/debouncer";
+import { Dispatch, StateUpdater } from "preact/hooks";
+
+//#region src/debouncer/useDebouncedState.d.ts
+
+/**
+ * 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;
+ * ```
+ */
+declare 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>];
+//#endregion
+export { useDebouncedState };
+//# sourceMappingURL=useDebouncedState.d.cts.map

package/dist/debouncer/useDebouncedState.d.ts

@@ -0,0 +1,82 @@
+import { PreactDebouncer } from "./useDebouncer.js";
+import { Dispatch, StateUpdater } from "preact/hooks";
+import { DebouncerOptions, DebouncerState } from "@tanstack/pacer/debouncer";
+
+//#region src/debouncer/useDebouncedState.d.ts
+
+/**
+ * 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;
+ * ```
+ */
+declare 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>];
+//#endregion
+export { useDebouncedState };
+//# sourceMappingURL=useDebouncedState.d.ts.map

package/dist/debouncer/useDebouncedState.js

@@ -0,0 +1,89 @@
+import { useDebouncer } from "./useDebouncer.js";
+import { useState } from "preact/hooks";
+
+//#region src/debouncer/useDebouncedState.ts
+/**
+* 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;
+* ```
+*/
+function useDebouncedState(value, options, selector) {
+	const [debouncedValue, setDebouncedValue] = useState(value);
+	const debouncer = useDebouncer(setDebouncedValue, options, selector);
+	return [
+		debouncedValue,
+		debouncer.maybeExecute,
+		debouncer
+	];
+}
+
+//#endregion
+export { useDebouncedState };
+//# sourceMappingURL=useDebouncedState.js.map

package/dist/debouncer/useDebouncedState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedState.js","names":[],"sources":["../../src/debouncer/useDebouncedState.ts"],"sourcesContent":["import { useState } from 'preact/hooks'\nimport { useDebouncer } from './useDebouncer'\nimport type { Dispatch, StateUpdater } from 'preact/hooks'\nimport type { PreactDebouncer } from './useDebouncer'\nimport type {\n  DebouncerOptions,\n  DebouncerState,\n} from '@tanstack/pacer/debouncer'\n\n/**\n * A Preact hook that creates a debounced state value, combining Preact's useState with debouncing functionality.\n * This hook provides both the current debounced value and methods to update it.\n *\n * The state value is only updated after the specified wait time has elapsed since the last update attempt.\n * If another update is attempted before the wait time expires, the timer resets and starts waiting again.\n * This is useful for handling frequent state updates that should be throttled, like search input values\n * or window resize dimensions.\n *\n * The hook returns a tuple containing:\n * - The current debounced value\n * - A function to update the debounced value\n * - The debouncer instance with additional control methods\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying debouncer instance.\n * The `selector` parameter allows you to specify which debouncer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available debouncer state properties:\n * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge\n * - `executionCount`: Number of function executions that have been completed\n * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution\n * - `lastArgs`: The arguments from the most recent call to maybeExecute\n * - `status`: Current execution status ('disabled' | 'idle' | 'pending')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState('', {\n *   wait: 500 // Wait 500ms after last keystroke\n * });\n *\n * // Opt-in to re-render when pending state changes (optimized for loading indicators)\n * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(\n *   '',\n *   { wait: 500 },\n *   (state) => ({ isPending: state.isPending })\n * );\n *\n * // Opt-in to re-render when execution count changes (optimized for tracking executions)\n * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(\n *   '',\n *   { wait: 500 },\n *   (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Opt-in to re-render when debouncing status changes (optimized for status display)\n * const [searchTerm, setSearchTerm, debouncer] = useDebouncedState(\n *   '',\n *   { wait: 500 },\n *   (state) => ({\n *     status: state.status,\n *     canLeadingExecute: state.canLeadingExecute\n *   })\n * );\n *\n * // Update value - will be debounced\n * const handleChange = (e) => {\n *   setSearchTerm(e.target.value);\n * };\n *\n * // Access the selected debouncer state (will be empty object {} unless selector provided)\n * const { isPending, executionCount } = debouncer.state;\n * ```\n */\nexport function useDebouncedState<\n  TValue,\n  TSelected = DebouncerState<Dispatch<StateUpdater<TValue>>>,\n>(\n  value: TValue,\n  options: DebouncerOptions<Dispatch<StateUpdater<TValue>>>,\n  selector?: (\n    state: DebouncerState<Dispatch<StateUpdater<TValue>>>,\n  ) => TSelected,\n): [\n  TValue,\n  Dispatch<StateUpdater<TValue>>,\n  PreactDebouncer<Dispatch<StateUpdater<TValue>>, TSelected>,\n] {\n  const [debouncedValue, setDebouncedValue] = useState(value)\n  const debouncer = useDebouncer(\n    setDebouncedValue,\n    options,\n    selector as (\n      state: DebouncerState<Dispatch<StateUpdater<TValue>>>,\n    ) => TSelected,\n  )\n  return [\n    debouncedValue,\n    debouncer.maybeExecute as Dispatch<StateUpdater<TValue>>,\n    debouncer,\n  ]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiFA,SAAgB,kBAId,OACA,SACA,UAOA;CACA,MAAM,CAAC,gBAAgB,qBAAqB,SAAS,MAAM;CAC3D,MAAM,YAAY,aAChB,mBACA,SACA,SAGD;AACD,QAAO;EACL;EACA,UAAU;EACV;EACD"}

package/dist/debouncer/useDebouncedValue.cjs

@@ -0,0 +1,96 @@
+const require_useDebouncedState = require('./useDebouncedState.cjs');
+let preact_hooks = require("preact/hooks");
+
+//#region src/debouncer/useDebouncedValue.ts
+/**
+* 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;
+* ```
+*/
+function useDebouncedValue(value, options, selector) {
+	const [debouncedValue, setDebouncedValue, debouncer] = require_useDebouncedState.useDebouncedState(value, options, selector);
+	(0, preact_hooks.useEffect)(() => {
+		setDebouncedValue(value);
+	}, [value, setDebouncedValue]);
+	return [debouncedValue, debouncer];
+}
+
+//#endregion
+exports.useDebouncedValue = useDebouncedValue;
+//# sourceMappingURL=useDebouncedValue.cjs.map

package/dist/debouncer/useDebouncedValue.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedValue.cjs","names":["useDebouncedState"],"sources":["../../src/debouncer/useDebouncedValue.ts"],"sourcesContent":["import { useEffect } from 'preact/hooks'\nimport { useDebouncedState } from './useDebouncedState'\nimport type { Dispatch, StateUpdater } from 'preact/hooks'\nimport type { PreactDebouncer } from './useDebouncer'\nimport type {\n  DebouncerOptions,\n  DebouncerState,\n} from '@tanstack/pacer/debouncer'\n\n/**\n * A Preact hook that creates a debounced value that updates only after a specified delay.\n * Unlike useDebouncedState, this hook automatically tracks changes to the input value\n * and updates the debounced value accordingly.\n *\n * The debounced value will only update after the specified wait time has elapsed since\n * the last change to the input value. If the input value changes again before the wait\n * time expires, the timer resets and starts waiting again.\n *\n * This is useful for deriving debounced values from props or state that change frequently,\n * like search queries or form inputs, where you want to limit how often downstream effects\n * or calculations occur.\n *\n * The hook returns the current debounced value and the underlying debouncer instance.\n * The debouncer instance can be used to access additional functionality like cancellation\n * and execution counts.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying debouncer instance.\n * The `selector` parameter allows you to specify which debouncer state changes will trigger a re-render,\n * optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.\n *\n * **By default, there will be no reactive state subscriptions** and you must opt-in to state\n * tracking by providing a selector function. This prevents unnecessary re-renders and gives you\n * full control over when your component updates. Only when you provide a selector will the\n * component re-render when the selected state values change.\n *\n * Available debouncer state properties:\n * - `canLeadingExecute`: Whether the debouncer can execute on the leading edge\n * - `executionCount`: Number of function executions that have been completed\n * - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution\n * - `lastArgs`: The arguments from the most recent call to maybeExecute\n * - `status`: Current execution status ('disabled' | 'idle' | 'pending')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [searchQuery, setSearchQuery] = useState('');\n * const [debouncedQuery, debouncer] = useDebouncedValue(searchQuery, {\n *   wait: 500 // Wait 500ms after last change\n * });\n *\n * // Opt-in to re-render when pending state changes (optimized for loading indicators)\n * const [debouncedQuery, debouncer] = useDebouncedValue(\n *   searchQuery,\n *   { wait: 500 },\n *   (state) => ({ isPending: state.isPending })\n * );\n *\n * // Opt-in to re-render when execution count changes (optimized for tracking executions)\n * const [debouncedQuery, debouncer] = useDebouncedValue(\n *   searchQuery,\n *   { wait: 500 },\n *   (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Opt-in to re-render when debouncing status changes (optimized for status display)\n * const [debouncedQuery, debouncer] = useDebouncedValue(\n *   searchQuery,\n *   { wait: 500 },\n *   (state) => ({\n *     status: state.status,\n *     canLeadingExecute: state.canLeadingExecute\n *   })\n * );\n *\n * // debouncedQuery will update 500ms after searchQuery stops changing\n * useEffect(() => {\n *   fetchSearchResults(debouncedQuery);\n * }, [debouncedQuery]);\n *\n * // Handle input changes\n * const handleChange = (e) => {\n *   setSearchQuery(e.target.value);\n * };\n *\n * // Access the selected debouncer state (will be empty object {} unless selector provided)\n * const { isPending, executionCount } = debouncer.state;\n * ```\n */\nexport function useDebouncedValue<\n  TValue,\n  TSelected = DebouncerState<Dispatch<StateUpdater<TValue>>>,\n>(\n  value: TValue,\n  options: DebouncerOptions<Dispatch<StateUpdater<TValue>>>,\n  selector?: (\n    state: DebouncerState<Dispatch<StateUpdater<TValue>>>,\n  ) => TSelected,\n): [TValue, PreactDebouncer<Dispatch<StateUpdater<TValue>>, TSelected>] {\n  const [debouncedValue, setDebouncedValue, debouncer] = useDebouncedState(\n    value,\n    options,\n    selector,\n  )\n\n  useEffect(() => {\n    ;(setDebouncedValue as (value: TValue) => void)(value)\n  }, [value, setDebouncedValue])\n\n  return [debouncedValue, debouncer]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0FA,SAAgB,kBAId,OACA,SACA,UAGsE;CACtE,MAAM,CAAC,gBAAgB,mBAAmB,aAAaA,4CACrD,OACA,SACA,SACD;AAED,mCAAgB;AACb,EAAC,kBAA8C,MAAM;IACrD,CAAC,OAAO,kBAAkB,CAAC;AAE9B,QAAO,CAAC,gBAAgB,UAAU"}

package/dist/debouncer/useDebouncedValue.d.cts

@@ -0,0 +1,91 @@
+import { PreactDebouncer } from "./useDebouncer.cjs";
+import { DebouncerOptions, DebouncerState } from "@tanstack/pacer/debouncer";
+import { Dispatch, StateUpdater } from "preact/hooks";
+
+//#region src/debouncer/useDebouncedValue.d.ts
+
+/**
+ * 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;
+ * ```
+ */
+declare 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>];
+//#endregion
+export { useDebouncedValue };
+//# sourceMappingURL=useDebouncedValue.d.cts.map