@tanstack/preact-pacer 0.0.1 → 0.18.0

package/dist/throttler/useThrottledState.d.ts

@@ -0,0 +1,93 @@
+import { PreactThrottler } from "./useThrottler.js";
+import { Dispatch, StateUpdater } from "preact/hooks";
+import { ThrottlerOptions, ThrottlerState } from "@tanstack/pacer/throttler";
+
+//#region src/throttler/useThrottledState.d.ts
+
+/**
+ * A Preact hook that creates a throttled state value that updates at most once within a specified time window.
+ * This hook combines Preact's useState with throttling functionality to provide controlled state updates.
+ *
+ * Throttling ensures state updates occur at a controlled rate regardless of how frequently the setter is called.
+ * This is useful for rate-limiting expensive re-renders or operations that depend on rapidly changing state.
+ *
+ * The hook returns a tuple containing:
+ * - The throttled state value
+ * - A throttled setter function that respects the configured wait time
+ * - The throttler instance for additional control
+ *
+ * For more direct control over throttling without state management,
+ * consider using the lower-level useThrottler hook instead.
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying throttler instance.
+ * The `selector` parameter allows you to specify which throttler 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 throttler state properties:
+ * - `executionCount`: Number of function executions that have been completed
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `lastExecutionTime`: Timestamp of the last function execution in milliseconds
+ * - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
+ * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const [value, setValue, throttler] = useThrottledState(0, { wait: 1000 });
+ *
+ * // Opt-in to re-render when execution count changes (optimized for tracking executions)
+ * const [value, setValue, throttler] = useThrottledState(
+ *   0,
+ *   { wait: 1000 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
+ * // Opt-in to re-render when throttling state changes (optimized for loading indicators)
+ * const [value, setValue, throttler] = useThrottledState(
+ *   0,
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     isPending: state.isPending,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when timing information changes (optimized for timing displays)
+ * const [value, setValue, throttler] = useThrottledState(
+ *   0,
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     lastExecutionTime: state.lastExecutionTime,
+ *     nextExecutionTime: state.nextExecutionTime
+ *   })
+ * );
+ *
+ * // With custom leading/trailing behavior
+ * const [value, setValue] = useThrottledState(0, {
+ *   wait: 1000,
+ *   leading: true,   // Update immediately on first change
+ *   trailing: false  // Skip trailing edge updates
+ * });
+ *
+ * // Access throttler methods if needed
+ * const handleReset = () => {
+ *   setValue(0);
+ *   throttler.cancel(); // Cancel any pending updates
+ * };
+ *
+ * // Access the selected throttler state (will be empty object {} unless selector provided)
+ * const { executionCount, isPending } = throttler.state;
+ * ```
+ */
+declare function useThrottledState<TValue, TSelected = ThrottlerState<Dispatch<StateUpdater<TValue>>>>(value: TValue, options: ThrottlerOptions<Dispatch<StateUpdater<TValue>>>, selector?: (state: ThrottlerState<Dispatch<StateUpdater<TValue>>>) => TSelected): [TValue, Dispatch<StateUpdater<TValue>>, PreactThrottler<Dispatch<StateUpdater<TValue>>, TSelected>];
+//#endregion
+export { useThrottledState };
+//# sourceMappingURL=useThrottledState.d.ts.map

package/dist/throttler/useThrottledState.js

@@ -0,0 +1,100 @@
+import { useThrottler } from "./useThrottler.js";
+import { useState } from "preact/hooks";
+
+//#region src/throttler/useThrottledState.ts
+/**
+* A Preact hook that creates a throttled state value that updates at most once within a specified time window.
+* This hook combines Preact's useState with throttling functionality to provide controlled state updates.
+*
+* Throttling ensures state updates occur at a controlled rate regardless of how frequently the setter is called.
+* This is useful for rate-limiting expensive re-renders or operations that depend on rapidly changing state.
+*
+* The hook returns a tuple containing:
+* - The throttled state value
+* - A throttled setter function that respects the configured wait time
+* - The throttler instance for additional control
+*
+* For more direct control over throttling without state management,
+* consider using the lower-level useThrottler hook instead.
+*
+* ## State Management and Selector
+*
+* The hook uses TanStack Store for reactive state management via the underlying throttler instance.
+* The `selector` parameter allows you to specify which throttler 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 throttler state properties:
+* - `executionCount`: Number of function executions that have been completed
+* - `lastArgs`: The arguments from the most recent call to maybeExecute
+* - `lastExecutionTime`: Timestamp of the last function execution in milliseconds
+* - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
+* - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
+* - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+*
+* @example
+* ```tsx
+* // Default behavior - no reactive state subscriptions
+* const [value, setValue, throttler] = useThrottledState(0, { wait: 1000 });
+*
+* // Opt-in to re-render when execution count changes (optimized for tracking executions)
+* const [value, setValue, throttler] = useThrottledState(
+*   0,
+*   { wait: 1000 },
+*   (state) => ({ executionCount: state.executionCount })
+* );
+*
+* // Opt-in to re-render when throttling state changes (optimized for loading indicators)
+* const [value, setValue, throttler] = useThrottledState(
+*   0,
+*   { wait: 1000 },
+*   (state) => ({
+*     isPending: state.isPending,
+*     status: state.status
+*   })
+* );
+*
+* // Opt-in to re-render when timing information changes (optimized for timing displays)
+* const [value, setValue, throttler] = useThrottledState(
+*   0,
+*   { wait: 1000 },
+*   (state) => ({
+*     lastExecutionTime: state.lastExecutionTime,
+*     nextExecutionTime: state.nextExecutionTime
+*   })
+* );
+*
+* // With custom leading/trailing behavior
+* const [value, setValue] = useThrottledState(0, {
+*   wait: 1000,
+*   leading: true,   // Update immediately on first change
+*   trailing: false  // Skip trailing edge updates
+* });
+*
+* // Access throttler methods if needed
+* const handleReset = () => {
+*   setValue(0);
+*   throttler.cancel(); // Cancel any pending updates
+* };
+*
+* // Access the selected throttler state (will be empty object {} unless selector provided)
+* const { executionCount, isPending } = throttler.state;
+* ```
+*/
+function useThrottledState(value, options, selector) {
+	const [throttledValue, setThrottledValue] = useState(value);
+	const throttler = useThrottler(setThrottledValue, options, selector);
+	return [
+		throttledValue,
+		throttler.maybeExecute,
+		throttler
+	];
+}
+
+//#endregion
+export { useThrottledState };
+//# sourceMappingURL=useThrottledState.js.map

package/dist/throttler/useThrottledState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThrottledState.js","names":[],"sources":["../../src/throttler/useThrottledState.ts"],"sourcesContent":["import { useState } from 'preact/hooks'\nimport { useThrottler } from './useThrottler'\nimport type { Dispatch, StateUpdater } from 'preact/hooks'\nimport type { PreactThrottler } from './useThrottler'\nimport type {\n  ThrottlerOptions,\n  ThrottlerState,\n} from '@tanstack/pacer/throttler'\n\n/**\n * A Preact hook that creates a throttled state value that updates at most once within a specified time window.\n * This hook combines Preact's useState with throttling functionality to provide controlled state updates.\n *\n * Throttling ensures state updates occur at a controlled rate regardless of how frequently the setter is called.\n * This is useful for rate-limiting expensive re-renders or operations that depend on rapidly changing state.\n *\n * The hook returns a tuple containing:\n * - The throttled state value\n * - A throttled setter function that respects the configured wait time\n * - The throttler instance for additional control\n *\n * For more direct control over throttling without state management,\n * consider using the lower-level useThrottler hook instead.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying throttler instance.\n * The `selector` parameter allows you to specify which throttler 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 throttler state properties:\n * - `executionCount`: Number of function executions that have been completed\n * - `lastArgs`: The arguments from the most recent call to maybeExecute\n * - `lastExecutionTime`: Timestamp of the last function execution in milliseconds\n * - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds\n * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution\n * - `status`: Current execution status ('disabled' | 'idle' | 'pending')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [value, setValue, throttler] = useThrottledState(0, { wait: 1000 });\n *\n * // Opt-in to re-render when execution count changes (optimized for tracking executions)\n * const [value, setValue, throttler] = useThrottledState(\n *   0,\n *   { wait: 1000 },\n *   (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Opt-in to re-render when throttling state changes (optimized for loading indicators)\n * const [value, setValue, throttler] = useThrottledState(\n *   0,\n *   { wait: 1000 },\n *   (state) => ({\n *     isPending: state.isPending,\n *     status: state.status\n *   })\n * );\n *\n * // Opt-in to re-render when timing information changes (optimized for timing displays)\n * const [value, setValue, throttler] = useThrottledState(\n *   0,\n *   { wait: 1000 },\n *   (state) => ({\n *     lastExecutionTime: state.lastExecutionTime,\n *     nextExecutionTime: state.nextExecutionTime\n *   })\n * );\n *\n * // With custom leading/trailing behavior\n * const [value, setValue] = useThrottledState(0, {\n *   wait: 1000,\n *   leading: true,   // Update immediately on first change\n *   trailing: false  // Skip trailing edge updates\n * });\n *\n * // Access throttler methods if needed\n * const handleReset = () => {\n *   setValue(0);\n *   throttler.cancel(); // Cancel any pending updates\n * };\n *\n * // Access the selected throttler state (will be empty object {} unless selector provided)\n * const { executionCount, isPending } = throttler.state;\n * ```\n */\n\nexport function useThrottledState<\n  TValue,\n  TSelected = ThrottlerState<Dispatch<StateUpdater<TValue>>>,\n>(\n  value: TValue,\n  options: ThrottlerOptions<Dispatch<StateUpdater<TValue>>>,\n  selector?: (\n    state: ThrottlerState<Dispatch<StateUpdater<TValue>>>,\n  ) => TSelected,\n): [\n  TValue,\n  Dispatch<StateUpdater<TValue>>,\n  PreactThrottler<Dispatch<StateUpdater<TValue>>, TSelected>,\n] {\n  const [throttledValue, setThrottledValue] = useState<TValue>(value)\n  const throttler = useThrottler(\n    setThrottledValue,\n    options,\n    selector as (\n      state: ThrottlerState<Dispatch<StateUpdater<TValue>>>,\n    ) => TSelected,\n  )\n  return [\n    throttledValue,\n    throttler.maybeExecute as Dispatch<StateUpdater<TValue>>,\n    throttler,\n  ]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6FA,SAAgB,kBAId,OACA,SACA,UAOA;CACA,MAAM,CAAC,gBAAgB,qBAAqB,SAAiB,MAAM;CACnE,MAAM,YAAY,aAChB,mBACA,SACA,SAGD;AACD,QAAO;EACL;EACA,UAAU;EACV;EACD"}

package/dist/throttler/useThrottledValue.cjs

@@ -0,0 +1,91 @@
+const require_useThrottledState = require('./useThrottledState.cjs');
+let preact_hooks = require("preact/hooks");
+
+//#region src/throttler/useThrottledValue.ts
+/**
+* A high-level Preact hook that creates a throttled version of a value that updates at most once within a specified time window.
+* This hook uses Preact's useState internally to manage the throttled state.
+*
+* Throttling ensures the value updates occur at a controlled rate regardless of how frequently the input value changes.
+* This is useful for rate-limiting expensive re-renders or API calls that depend on rapidly changing values.
+*
+* The hook returns a tuple containing:
+* - The throttled value that updates according to the leading/trailing edge behavior specified in the options
+* - The throttler instance with control methods
+*
+* For more direct control over throttling behavior without Preact state management,
+* consider using the lower-level useThrottler hook instead.
+*
+* ## State Management and Selector
+*
+* The hook uses TanStack Store for reactive state management via the underlying throttler instance.
+* The `selector` parameter allows you to specify which throttler 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 throttler state properties:
+* - `executionCount`: Number of function executions that have been completed
+* - `lastArgs`: The arguments from the most recent call to maybeExecute
+* - `lastExecutionTime`: Timestamp of the last function execution in milliseconds
+* - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
+* - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
+* - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+*
+* @example
+* ```tsx
+* // Default behavior - no reactive state subscriptions
+* const [throttledValue, throttler] = useThrottledValue(rawValue, { wait: 1000 });
+*
+* // Opt-in to re-render when execution count changes (optimized for tracking executions)
+* const [throttledValue, throttler] = useThrottledValue(
+*   rawValue,
+*   { wait: 1000 },
+*   (state) => ({ executionCount: state.executionCount })
+* );
+*
+* // Opt-in to re-render when throttling state changes (optimized for loading indicators)
+* const [throttledValue, throttler] = useThrottledValue(
+*   rawValue,
+*   { wait: 1000 },
+*   (state) => ({
+*     isPending: state.isPending,
+*     status: state.status
+*   })
+* );
+*
+* // Opt-in to re-render when timing information changes (optimized for timing displays)
+* const [throttledValue, throttler] = useThrottledValue(
+*   rawValue,
+*   { wait: 1000 },
+*   (state) => ({
+*     lastExecutionTime: state.lastExecutionTime,
+*     nextExecutionTime: state.nextExecutionTime
+*   })
+* );
+*
+* // With custom leading/trailing behavior
+* const [throttledValue, throttler] = useThrottledValue(rawValue, {
+*   wait: 1000,
+*   leading: true,   // Update immediately on first change
+*   trailing: false  // Skip trailing edge updates
+* });
+*
+* // Access the selected throttler state (will be empty object {} unless selector provided)
+* const { executionCount, isPending } = throttler.state;
+* ```
+*/
+function useThrottledValue(value, options, selector) {
+	const [throttledValue, setThrottledValue, throttler] = require_useThrottledState.useThrottledState(value, options, selector);
+	(0, preact_hooks.useEffect)(() => {
+		setThrottledValue(value);
+	}, [value, setThrottledValue]);
+	return [throttledValue, throttler];
+}
+
+//#endregion
+exports.useThrottledValue = useThrottledValue;
+//# sourceMappingURL=useThrottledValue.cjs.map

package/dist/throttler/useThrottledValue.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThrottledValue.cjs","names":["useThrottledState"],"sources":["../../src/throttler/useThrottledValue.ts"],"sourcesContent":["import { useEffect } from 'preact/hooks'\nimport { useThrottledState } from './useThrottledState'\nimport type { Dispatch, StateUpdater } from 'preact/hooks'\nimport type { PreactThrottler } from './useThrottler'\nimport type {\n  ThrottlerOptions,\n  ThrottlerState,\n} from '@tanstack/pacer/throttler'\n\n/**\n * A high-level Preact hook that creates a throttled version of a value that updates at most once within a specified time window.\n * This hook uses Preact's useState internally to manage the throttled state.\n *\n * Throttling ensures the value updates occur at a controlled rate regardless of how frequently the input value changes.\n * This is useful for rate-limiting expensive re-renders or API calls that depend on rapidly changing values.\n *\n * The hook returns a tuple containing:\n * - The throttled value that updates according to the leading/trailing edge behavior specified in the options\n * - The throttler instance with control methods\n *\n * For more direct control over throttling behavior without Preact state management,\n * consider using the lower-level useThrottler hook instead.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying throttler instance.\n * The `selector` parameter allows you to specify which throttler 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 throttler state properties:\n * - `executionCount`: Number of function executions that have been completed\n * - `lastArgs`: The arguments from the most recent call to maybeExecute\n * - `lastExecutionTime`: Timestamp of the last function execution in milliseconds\n * - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds\n * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution\n * - `status`: Current execution status ('disabled' | 'idle' | 'pending')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [throttledValue, throttler] = useThrottledValue(rawValue, { wait: 1000 });\n *\n * // Opt-in to re-render when execution count changes (optimized for tracking executions)\n * const [throttledValue, throttler] = useThrottledValue(\n *   rawValue,\n *   { wait: 1000 },\n *   (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Opt-in to re-render when throttling state changes (optimized for loading indicators)\n * const [throttledValue, throttler] = useThrottledValue(\n *   rawValue,\n *   { wait: 1000 },\n *   (state) => ({\n *     isPending: state.isPending,\n *     status: state.status\n *   })\n * );\n *\n * // Opt-in to re-render when timing information changes (optimized for timing displays)\n * const [throttledValue, throttler] = useThrottledValue(\n *   rawValue,\n *   { wait: 1000 },\n *   (state) => ({\n *     lastExecutionTime: state.lastExecutionTime,\n *     nextExecutionTime: state.nextExecutionTime\n *   })\n * );\n *\n * // With custom leading/trailing behavior\n * const [throttledValue, throttler] = useThrottledValue(rawValue, {\n *   wait: 1000,\n *   leading: true,   // Update immediately on first change\n *   trailing: false  // Skip trailing edge updates\n * });\n *\n * // Access the selected throttler state (will be empty object {} unless selector provided)\n * const { executionCount, isPending } = throttler.state;\n * ```\n */\nexport function useThrottledValue<\n  TValue,\n  TSelected = ThrottlerState<Dispatch<StateUpdater<TValue>>>,\n>(\n  value: TValue,\n  options: ThrottlerOptions<Dispatch<StateUpdater<TValue>>>,\n  selector?: (\n    state: ThrottlerState<Dispatch<StateUpdater<TValue>>>,\n  ) => TSelected,\n): [TValue, PreactThrottler<Dispatch<StateUpdater<TValue>>, TSelected>] {\n  const [throttledValue, setThrottledValue, throttler] = useThrottledState(\n    value,\n    options,\n    selector,\n  )\n\n  useEffect(() => {\n    ;(setThrottledValue as (value: TValue) => void)(value)\n  }, [value, setThrottledValue])\n\n  return [throttledValue, throttler]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqFA,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/throttler/useThrottledValue.d.cts

@@ -0,0 +1,86 @@
+import { PreactThrottler } from "./useThrottler.cjs";
+import { Dispatch, StateUpdater } from "preact/hooks";
+import { ThrottlerOptions, ThrottlerState } from "@tanstack/pacer/throttler";
+
+//#region src/throttler/useThrottledValue.d.ts
+
+/**
+ * A high-level Preact hook that creates a throttled version of a value that updates at most once within a specified time window.
+ * This hook uses Preact's useState internally to manage the throttled state.
+ *
+ * Throttling ensures the value updates occur at a controlled rate regardless of how frequently the input value changes.
+ * This is useful for rate-limiting expensive re-renders or API calls that depend on rapidly changing values.
+ *
+ * The hook returns a tuple containing:
+ * - The throttled value that updates according to the leading/trailing edge behavior specified in the options
+ * - The throttler instance with control methods
+ *
+ * For more direct control over throttling behavior without Preact state management,
+ * consider using the lower-level useThrottler hook instead.
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying throttler instance.
+ * The `selector` parameter allows you to specify which throttler 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 throttler state properties:
+ * - `executionCount`: Number of function executions that have been completed
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `lastExecutionTime`: Timestamp of the last function execution in milliseconds
+ * - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
+ * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const [throttledValue, throttler] = useThrottledValue(rawValue, { wait: 1000 });
+ *
+ * // Opt-in to re-render when execution count changes (optimized for tracking executions)
+ * const [throttledValue, throttler] = useThrottledValue(
+ *   rawValue,
+ *   { wait: 1000 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
+ * // Opt-in to re-render when throttling state changes (optimized for loading indicators)
+ * const [throttledValue, throttler] = useThrottledValue(
+ *   rawValue,
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     isPending: state.isPending,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when timing information changes (optimized for timing displays)
+ * const [throttledValue, throttler] = useThrottledValue(
+ *   rawValue,
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     lastExecutionTime: state.lastExecutionTime,
+ *     nextExecutionTime: state.nextExecutionTime
+ *   })
+ * );
+ *
+ * // With custom leading/trailing behavior
+ * const [throttledValue, throttler] = useThrottledValue(rawValue, {
+ *   wait: 1000,
+ *   leading: true,   // Update immediately on first change
+ *   trailing: false  // Skip trailing edge updates
+ * });
+ *
+ * // Access the selected throttler state (will be empty object {} unless selector provided)
+ * const { executionCount, isPending } = throttler.state;
+ * ```
+ */
+declare function useThrottledValue<TValue, TSelected = ThrottlerState<Dispatch<StateUpdater<TValue>>>>(value: TValue, options: ThrottlerOptions<Dispatch<StateUpdater<TValue>>>, selector?: (state: ThrottlerState<Dispatch<StateUpdater<TValue>>>) => TSelected): [TValue, PreactThrottler<Dispatch<StateUpdater<TValue>>, TSelected>];
+//#endregion
+export { useThrottledValue };
+//# sourceMappingURL=useThrottledValue.d.cts.map

package/dist/throttler/useThrottledValue.d.ts

@@ -0,0 +1,86 @@
+import { PreactThrottler } from "./useThrottler.js";
+import { Dispatch, StateUpdater } from "preact/hooks";
+import { ThrottlerOptions, ThrottlerState } from "@tanstack/pacer/throttler";
+
+//#region src/throttler/useThrottledValue.d.ts
+
+/**
+ * A high-level Preact hook that creates a throttled version of a value that updates at most once within a specified time window.
+ * This hook uses Preact's useState internally to manage the throttled state.
+ *
+ * Throttling ensures the value updates occur at a controlled rate regardless of how frequently the input value changes.
+ * This is useful for rate-limiting expensive re-renders or API calls that depend on rapidly changing values.
+ *
+ * The hook returns a tuple containing:
+ * - The throttled value that updates according to the leading/trailing edge behavior specified in the options
+ * - The throttler instance with control methods
+ *
+ * For more direct control over throttling behavior without Preact state management,
+ * consider using the lower-level useThrottler hook instead.
+ *
+ * ## State Management and Selector
+ *
+ * The hook uses TanStack Store for reactive state management via the underlying throttler instance.
+ * The `selector` parameter allows you to specify which throttler 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 throttler state properties:
+ * - `executionCount`: Number of function executions that have been completed
+ * - `lastArgs`: The arguments from the most recent call to maybeExecute
+ * - `lastExecutionTime`: Timestamp of the last function execution in milliseconds
+ * - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
+ * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
+ * - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+ *
+ * @example
+ * ```tsx
+ * // Default behavior - no reactive state subscriptions
+ * const [throttledValue, throttler] = useThrottledValue(rawValue, { wait: 1000 });
+ *
+ * // Opt-in to re-render when execution count changes (optimized for tracking executions)
+ * const [throttledValue, throttler] = useThrottledValue(
+ *   rawValue,
+ *   { wait: 1000 },
+ *   (state) => ({ executionCount: state.executionCount })
+ * );
+ *
+ * // Opt-in to re-render when throttling state changes (optimized for loading indicators)
+ * const [throttledValue, throttler] = useThrottledValue(
+ *   rawValue,
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     isPending: state.isPending,
+ *     status: state.status
+ *   })
+ * );
+ *
+ * // Opt-in to re-render when timing information changes (optimized for timing displays)
+ * const [throttledValue, throttler] = useThrottledValue(
+ *   rawValue,
+ *   { wait: 1000 },
+ *   (state) => ({
+ *     lastExecutionTime: state.lastExecutionTime,
+ *     nextExecutionTime: state.nextExecutionTime
+ *   })
+ * );
+ *
+ * // With custom leading/trailing behavior
+ * const [throttledValue, throttler] = useThrottledValue(rawValue, {
+ *   wait: 1000,
+ *   leading: true,   // Update immediately on first change
+ *   trailing: false  // Skip trailing edge updates
+ * });
+ *
+ * // Access the selected throttler state (will be empty object {} unless selector provided)
+ * const { executionCount, isPending } = throttler.state;
+ * ```
+ */
+declare function useThrottledValue<TValue, TSelected = ThrottlerState<Dispatch<StateUpdater<TValue>>>>(value: TValue, options: ThrottlerOptions<Dispatch<StateUpdater<TValue>>>, selector?: (state: ThrottlerState<Dispatch<StateUpdater<TValue>>>) => TSelected): [TValue, PreactThrottler<Dispatch<StateUpdater<TValue>>, TSelected>];
+//#endregion
+export { useThrottledValue };
+//# sourceMappingURL=useThrottledValue.d.ts.map

package/dist/throttler/useThrottledValue.js

@@ -0,0 +1,91 @@
+import { useThrottledState } from "./useThrottledState.js";
+import { useEffect } from "preact/hooks";
+
+//#region src/throttler/useThrottledValue.ts
+/**
+* A high-level Preact hook that creates a throttled version of a value that updates at most once within a specified time window.
+* This hook uses Preact's useState internally to manage the throttled state.
+*
+* Throttling ensures the value updates occur at a controlled rate regardless of how frequently the input value changes.
+* This is useful for rate-limiting expensive re-renders or API calls that depend on rapidly changing values.
+*
+* The hook returns a tuple containing:
+* - The throttled value that updates according to the leading/trailing edge behavior specified in the options
+* - The throttler instance with control methods
+*
+* For more direct control over throttling behavior without Preact state management,
+* consider using the lower-level useThrottler hook instead.
+*
+* ## State Management and Selector
+*
+* The hook uses TanStack Store for reactive state management via the underlying throttler instance.
+* The `selector` parameter allows you to specify which throttler 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 throttler state properties:
+* - `executionCount`: Number of function executions that have been completed
+* - `lastArgs`: The arguments from the most recent call to maybeExecute
+* - `lastExecutionTime`: Timestamp of the last function execution in milliseconds
+* - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
+* - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
+* - `status`: Current execution status ('disabled' | 'idle' | 'pending')
+*
+* @example
+* ```tsx
+* // Default behavior - no reactive state subscriptions
+* const [throttledValue, throttler] = useThrottledValue(rawValue, { wait: 1000 });
+*
+* // Opt-in to re-render when execution count changes (optimized for tracking executions)
+* const [throttledValue, throttler] = useThrottledValue(
+*   rawValue,
+*   { wait: 1000 },
+*   (state) => ({ executionCount: state.executionCount })
+* );
+*
+* // Opt-in to re-render when throttling state changes (optimized for loading indicators)
+* const [throttledValue, throttler] = useThrottledValue(
+*   rawValue,
+*   { wait: 1000 },
+*   (state) => ({
+*     isPending: state.isPending,
+*     status: state.status
+*   })
+* );
+*
+* // Opt-in to re-render when timing information changes (optimized for timing displays)
+* const [throttledValue, throttler] = useThrottledValue(
+*   rawValue,
+*   { wait: 1000 },
+*   (state) => ({
+*     lastExecutionTime: state.lastExecutionTime,
+*     nextExecutionTime: state.nextExecutionTime
+*   })
+* );
+*
+* // With custom leading/trailing behavior
+* const [throttledValue, throttler] = useThrottledValue(rawValue, {
+*   wait: 1000,
+*   leading: true,   // Update immediately on first change
+*   trailing: false  // Skip trailing edge updates
+* });
+*
+* // Access the selected throttler state (will be empty object {} unless selector provided)
+* const { executionCount, isPending } = throttler.state;
+* ```
+*/
+function useThrottledValue(value, options, selector) {
+	const [throttledValue, setThrottledValue, throttler] = useThrottledState(value, options, selector);
+	useEffect(() => {
+		setThrottledValue(value);
+	}, [value, setThrottledValue]);
+	return [throttledValue, throttler];
+}
+
+//#endregion
+export { useThrottledValue };
+//# sourceMappingURL=useThrottledValue.js.map

package/dist/throttler/useThrottledValue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThrottledValue.js","names":[],"sources":["../../src/throttler/useThrottledValue.ts"],"sourcesContent":["import { useEffect } from 'preact/hooks'\nimport { useThrottledState } from './useThrottledState'\nimport type { Dispatch, StateUpdater } from 'preact/hooks'\nimport type { PreactThrottler } from './useThrottler'\nimport type {\n  ThrottlerOptions,\n  ThrottlerState,\n} from '@tanstack/pacer/throttler'\n\n/**\n * A high-level Preact hook that creates a throttled version of a value that updates at most once within a specified time window.\n * This hook uses Preact's useState internally to manage the throttled state.\n *\n * Throttling ensures the value updates occur at a controlled rate regardless of how frequently the input value changes.\n * This is useful for rate-limiting expensive re-renders or API calls that depend on rapidly changing values.\n *\n * The hook returns a tuple containing:\n * - The throttled value that updates according to the leading/trailing edge behavior specified in the options\n * - The throttler instance with control methods\n *\n * For more direct control over throttling behavior without Preact state management,\n * consider using the lower-level useThrottler hook instead.\n *\n * ## State Management and Selector\n *\n * The hook uses TanStack Store for reactive state management via the underlying throttler instance.\n * The `selector` parameter allows you to specify which throttler 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 throttler state properties:\n * - `executionCount`: Number of function executions that have been completed\n * - `lastArgs`: The arguments from the most recent call to maybeExecute\n * - `lastExecutionTime`: Timestamp of the last function execution in milliseconds\n * - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds\n * - `isPending`: Whether the throttler is waiting for the timeout to trigger execution\n * - `status`: Current execution status ('disabled' | 'idle' | 'pending')\n *\n * @example\n * ```tsx\n * // Default behavior - no reactive state subscriptions\n * const [throttledValue, throttler] = useThrottledValue(rawValue, { wait: 1000 });\n *\n * // Opt-in to re-render when execution count changes (optimized for tracking executions)\n * const [throttledValue, throttler] = useThrottledValue(\n *   rawValue,\n *   { wait: 1000 },\n *   (state) => ({ executionCount: state.executionCount })\n * );\n *\n * // Opt-in to re-render when throttling state changes (optimized for loading indicators)\n * const [throttledValue, throttler] = useThrottledValue(\n *   rawValue,\n *   { wait: 1000 },\n *   (state) => ({\n *     isPending: state.isPending,\n *     status: state.status\n *   })\n * );\n *\n * // Opt-in to re-render when timing information changes (optimized for timing displays)\n * const [throttledValue, throttler] = useThrottledValue(\n *   rawValue,\n *   { wait: 1000 },\n *   (state) => ({\n *     lastExecutionTime: state.lastExecutionTime,\n *     nextExecutionTime: state.nextExecutionTime\n *   })\n * );\n *\n * // With custom leading/trailing behavior\n * const [throttledValue, throttler] = useThrottledValue(rawValue, {\n *   wait: 1000,\n *   leading: true,   // Update immediately on first change\n *   trailing: false  // Skip trailing edge updates\n * });\n *\n * // Access the selected throttler state (will be empty object {} unless selector provided)\n * const { executionCount, isPending } = throttler.state;\n * ```\n */\nexport function useThrottledValue<\n  TValue,\n  TSelected = ThrottlerState<Dispatch<StateUpdater<TValue>>>,\n>(\n  value: TValue,\n  options: ThrottlerOptions<Dispatch<StateUpdater<TValue>>>,\n  selector?: (\n    state: ThrottlerState<Dispatch<StateUpdater<TValue>>>,\n  ) => TSelected,\n): [TValue, PreactThrottler<Dispatch<StateUpdater<TValue>>, TSelected>] {\n  const [throttledValue, setThrottledValue, throttler] = useThrottledState(\n    value,\n    options,\n    selector,\n  )\n\n  useEffect(() => {\n    ;(setThrottledValue as (value: TValue) => void)(value)\n  }, [value, setThrottledValue])\n\n  return [throttledValue, throttler]\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqFA,SAAgB,kBAId,OACA,SACA,UAGsE;CACtE,MAAM,CAAC,gBAAgB,mBAAmB,aAAa,kBACrD,OACA,SACA,SACD;AAED,iBAAgB;AACb,EAAC,kBAA8C,MAAM;IACrD,CAAC,OAAO,kBAAkB,CAAC;AAE9B,QAAO,CAAC,gBAAgB,UAAU"}