import { SolidPacerOptions } from "../types/index.js"; import { SolidThrottler, SolidThrottlerOptions } from "./createThrottler.js"; import { Accessor, Setter } from "solid-js"; import { ThrottlerState } from "@tanstack/pacer/throttler"; //#region src/throttler/createThrottledValue.d.ts /** * A high-level Solid hook that creates a throttled version of a value that updates at most once within a specified time window. * This hook uses Solid's createSignal 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 updates or API calls that depend on rapidly changing values. * * The hook returns a tuple containing: * - An accessor function that provides the throttled value * - The throttler instance with control methods * * The throttled value will update according to the leading/trailing edge behavior specified in the options. * * For more direct control over throttling behavior without Solid state management, * consider using the lower-level createThrottler 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 reactive updates, * optimizing performance by preventing unnecessary subscriptions 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 reactive updates and gives you * full control over when your component subscribes to state changes. Only when you provide a selector will * the reactive system track the selected state values. * * Available throttler state properties: * - `executionCount`: Number of function executions that have been completed * - `isPending`: Whether the throttler is waiting for the timeout to trigger trailing execution * - `lastArgs`: The arguments from the most recent call to maybeExecute * - `lastExecutionTime`: Unix timestamp of the last execution * - `nextExecutionTime`: Unix timestamp of the next allowed execution * - `status`: Current execution status ('disabled' | 'idle' | 'pending') * * @example * ```tsx * // Default behavior - no reactive state subscriptions * const [throttledValue, throttler] = createThrottledValue(rawValue, { wait: 1000 }); * * // Opt-in to reactive updates when pending state changes (optimized for loading indicators) * const [throttledValue, throttler] = createThrottledValue( * rawValue, * { wait: 1000 }, * (state) => ({ isPending: state.isPending }) * ); * * // Use the throttled value * console.log(throttledValue()); // Access the current throttled value * * // Access throttler state via signals * console.log('Is pending:', throttler.state().isPending); * * // Control the throttler * throttler.cancel(); // Cancel any pending updates * ``` */ export declare function createThrottledValue(value: Accessor, initialOptions: SolidPacerOptions, TSelected>>, selector?: (state: ThrottlerState>) => TSelected): [Accessor, SolidThrottler, TSelected>]; //#endregion