@himanshu-sorathiya/react-kit 1.0.27 → 1.0.29

package/dist/index.d.ts

@@ -417,85 +417,1094 @@ export type UseKeyReturn = () => void;
  * ```
  */
 export declare function useKey(key: string, handler: (event: KeyboardEvent) => void, options?: UseKeyOptions): UseKeyReturn;
-export interface DebounceOptions {
+/**
+ * Configuration for `useBatcher`.
+ *
+ * All three flush triggers (`maxSize`, `maxWait`, `quietPeriod`) are
+ * optional and independent — configure any combination, and whichever
+ * condition is met first triggers the flush. If none are configured, the
+ * batch only ever flushes when `flush()` is called manually.
+ */
+export interface BatchOptions<Item> {
+	/**
+	 * Flushes the batch immediately once it reaches this many items.
+	 * Checked on every `add()` call, before either timer-based trigger is
+	 * considered.
+	 *
+	 * Invalid input (not a positive number) is ignored — not clamped to a
+	 * fallback — with a dev-mode warning, since there's no sensible
+	 * default size to fall back to.
+	 *
+	 * @defaultValue `undefined` (no size ceiling)
+	 */
+	maxSize?: number;
+	/**
+	 * A hard ceiling, in milliseconds, on how long a batch can sit before
+	 * flushing — measured from the moment the *first* item of the current
+	 * batch was added, not the most recent one. Guarantees a maximum
+	 * latency per item regardless of how long the batch keeps growing.
+	 *
+	 * Invalid input (not a non-negative number) is ignored with a dev-mode
+	 * warning.
+	 *
+	 * @defaultValue `undefined` (no time ceiling)
+	 */
 	maxWait?: number;
-	leading?: boolean;
-	trailing?: boolean;
+	/**
+	 * Flushes the batch once this many milliseconds pass with no further
+	 * items added — resets on every `add()` call, unlike `maxWait`. Use
+	 * this when you want to wait for activity to genuinely settle before
+	 * flushing, rather than enforcing a hard per-item latency ceiling.
+	 *
+	 * If both `maxWait` and `quietPeriod` are configured and `quietPeriod`
+	 * is not shorter than `maxWait`, `maxWait` will almost always win the
+	 * race — a dev-mode warning flags this combination.
+	 *
+	 * Invalid input (not a non-negative number) is ignored with a dev-mode
+	 * warning.
+	 *
+	 * @defaultValue `undefined` (no quiet-period trigger)
+	 */
+	quietPeriod?: number;
+	/**
+	 * Called with a snapshot of the current batch contents every time it
+	 * changes — after every `add()`, and after every flush or `cancel()`
+	 * (with an empty array). This is the mechanism for getting live,
+	 * reactive access to what's currently queued (e.g. a "3 items
+	 * queued…" indicator) without `useBatcher` itself needing to hold the
+	 * full item list in React state.
+	 *
+	 * Safe to pass a fresh inline function on every render — it's captured
+	 * in a ref and refreshed via effect, same as `onFlush`.
+	 *
+	 * @defaultValue `undefined`
+	 */
+	onItemsChange?: (items: readonly Item[]) => void;
 }
-export interface UseDebounceReturn {
-	run: <Args extends unknown[]>(func: (...args: Args) => void, ...args: Args) => void;
-	cancel: () => void;
+/**
+ * The object returned by `useBatcher`.
+ */
+export interface UseBatcherReturn<Item> {
+	/**
+	 * Adds `item` to the current batch. Never rejected, never deferred to
+	 * a future call — the item is always accepted immediately. Depending
+	 * on the configured triggers, this may also cause an immediate flush
+	 * (e.g. if `maxSize` is now reached).
+	 */
+	add: (item: Item) => void;
+	/**
+	 * Immediately flushes whatever is currently batched, bypassing
+	 * `maxWait`/`quietPeriod` entirely. A no-op if the batch is empty —
+	 * `onFlush` is never called with zero items.
+	 */
 	flush: () => void;
+	/**
+	 * Discards the current batch entirely, without ever calling
+	 * `onFlush`. Clears any pending timers.
+	 */
+	cancel: () => void;
+	/**
+	 * Suspends all automatic flush triggers (`maxSize`, `maxWait`,
+	 * `quietPeriod`). Items added via `add()` while paused still
+	 * accumulate normally — pausing stops the flushing machinery, not the
+	 * accumulation. The only way to flush while paused is a manual
+	 * `flush()` call.
+	 */
+	pause: () => void;
+	/**
+	 * Resumes automatic flushing. If the batch already meets `maxSize`
+	 * (because items kept arriving while paused), flushes immediately.
+	 * Otherwise, re-arms `maxWait`/`quietPeriod` timers from scratch —
+	 * pausing does not preserve partial progress toward either deadline;
+	 * resuming starts a fresh clock for whatever's still batched.
+	 */
+	resume: () => void;
+	/** The number of items currently in the batch. */
+	size: number;
+	/** `true` whenever `size > 0`. */
 	isPending: boolean;
+	/** `true` after `pause()`, until the next `resume()`. */
+	isPaused: boolean;
+}
+/**
+ * Groups rapid, individual `add()` calls into batches, flushing the whole
+ * accumulated group to `onFlush` at once — instead of debouncing,
+ * throttling, or rate-limiting, all of which discard some calls along the
+ * way. Nothing added to a `useBatcher` is ever dropped; it's only ever
+ * grouped.
+ *
+ * A batch flushes when any configured trigger fires first: reaching
+ * `maxSize` items, `maxWait` milliseconds since the batch's first item,
+ * or `quietPeriod` milliseconds of no new items. All three are optional
+ * and can be combined freely. If none are configured, only a manual
+ * `flush()` call ever empties the batch.
+ *
+ * Unlike the debounce/throttle/rate-limit hook families, there's no
+ * separate `Callback`/`State`/`Value` wrapper — `onFlush` is a single
+ * fixed handler (captured in a ref and always current, so a fresh inline
+ * function on every render is safe), and live access to the current batch
+ * contents is available via the `onItemsChange` option instead of a
+ * dedicated hook.
+ *
+ * @example
+ * ```tsx
+ * function AnalyticsProvider({ children }: { children: React.ReactNode }) {
+ *   const { add } = useBatcher<AnalyticsEvent>(
+ *     (events) => sendAnalyticsBatch(events),
+ *     { maxSize: 20, maxWait: 5000 },
+ *   );
+ *
+ *   // `track` can be called as often as needed — events are grouped and
+ *   // sent in batches of up to 20, at least once every 5 seconds.
+ *   const track = (event: AnalyticsEvent) => add(event);
+ *
+ *   return (
+ *     <AnalyticsContext.Provider value={{ track }}>
+ *       {children}
+ *     </AnalyticsContext.Provider>
+ *   );
+ * }
+ * ```
+ *
+ * @param onFlush - Called with every item accumulated since the last
+ * flush, as a snapshot array. Safe to pass a fresh inline function on
+ * every render.
+ * @param options - See {@link BatchOptions}.
+ * @returns See {@link UseBatcherReturn}.
+ */
+export declare function useBatcher<Item>(onFlush: (items: readonly Item[]) => void, options?: BatchOptions<Item>): UseBatcherReturn<Item>;
+/**
+ * Adds an optional custom equality comparator to any hook that manages a
+ * value and needs to decide whether a "new" value is actually different
+ * enough to justify a re-render.
+ *
+ * Used by the `State` and `Value` variants of debounce/throttle/rate-limit
+ * (e.g. `useDebouncedValue`, `useThrottledState`) to avoid committing a
+ * value that is deeply/semantically equal to the value already held,
+ * which would otherwise trigger a wasted re-render.
+ *
+ * @example
+ * ```tsx
+ * useDebouncedValue(user, 300, {
+ *   equalityFn: (previous, next) => previous.id === next.id,
+ * });
+ * ```
+ */
+export interface EqualityFnOption<T> {
+	/**
+	 * Called with the currently-held value and the candidate next value.
+	 * Return `true` if they should be treated as equal (no update should be
+	 * committed); return `false` to allow the update through.
+	 *
+	 * Defaults to `Object.is` when omitted, or when an invalid (non-function)
+	 * value is provided — see the consuming hook's dev-mode warning.
+	 */
+	equalityFn?: (previous: T, next: T) => boolean;
 }
-export declare function useDebounce(delay: number, options?: DebounceOptions): UseDebounceReturn;
+/**
+ * Configuration for `useDebouncer` and every hook built on top of it.
+ *
+ * @remarks
+ * `leading` and `trailing` may both be set to `false` at the same time —
+ * the hook will not silently correct this for you. That configuration
+ * means the debounced function will never run; a dev-mode warning is
+ * logged to help catch it early, but the choice itself is respected.
+ */
+export interface DebounceOptions {
+	/**
+	 * A hard ceiling, in milliseconds, on how long invocation can be
+	 * deferred. If a continuous stream of calls keeps pushing the trailing
+	 * timer out, `maxWait` forces a synchronous invocation once this many
+	 * milliseconds have elapsed since the current cycle began — regardless
+	 * of whether the trailing window has settled yet.
+	 *
+	 * Only evaluated at the moment `run()` is called; it is not an
+	 * independent background timer, so it can't fire while no calls are
+	 * coming in.
+	 *
+	 * @defaultValue `undefined` (no ceiling)
+	 */
+	maxWait?: number;
+	/**
+	 * When `true`, invokes on the leading edge — immediately, on the first
+	 * call of a new debounce cycle (i.e. when no cycle is currently active).
+	 *
+	 * @defaultValue `false`
+	 */
+	leading?: boolean;
+	/**
+	 * When `true`, invokes on the trailing edge — once `delay` milliseconds
+	 * have elapsed with no further calls.
+	 *
+	 * Defaults to `true` regardless of `leading`'s value. With
+	 * `{ leading: true, trailing: true }` (both edges enabled), a single
+	 * isolated call only fires once (the leading edge) — the trailing edge
+	 * only fires if at least one more call arrives before the window
+	 * closes.
+	 *
+	 * @defaultValue `true`
+	 */
+	trailing?: boolean;
+}
+/**
+ * Options for `useDebouncedState`: all of {@link DebounceOptions}, plus an
+ * optional equality comparator used to skip committing a value equivalent
+ * to the one already held.
+ */
+export type UseDebouncedStateOptions<T> = DebounceOptions & EqualityFnOption<T>;
+/**
+ * Options for `useDebouncedValue`: all of {@link DebounceOptions}, plus an
+ * optional equality comparator used to skip committing a value equivalent
+ * to the one already held.
+ */
+export type UseDebouncedValueOptions<T> = DebounceOptions & EqualityFnOption<T>;
+/**
+ * The object returned by `useDebouncedCallback`.
+ */
 export interface UseDebouncedCallbackReturn<Args extends unknown[]> {
+	/**
+	 * A stable, debounced wrapper around `func`. Safe to call from any
+	 * event handler; internally always invokes the most recently rendered
+	 * `func`, even though `debouncedFunc`'s own identity doesn't change
+	 * across re-renders.
+	 */
 	debouncedFunc: (...args: Args) => void;
+	/** See {@link UseDebouncerReturn.cancel}. */
 	cancel: () => void;
+	/** See {@link UseDebouncerReturn.flush}. */
 	flush: () => void;
+	/** See {@link UseDebouncerReturn.isPending}. */
 	isPending: boolean;
 }
+/**
+ * Debounces a single function.
+ *
+ * `func` is captured in a ref and refreshed on every render — you can pass
+ * a fresh inline closure every time without resetting the pending debounce
+ * cycle, and the debounced wrapper always calls the *latest* `func`,
+ * closing over whatever props/state were current when it actually fires
+ * (never a stale closure from whenever the wrapper was first created).
+ *
+ * @example
+ * ```tsx
+ * function SearchBox() {
+ *   const { debouncedFunc: handleSearch, isPending } = useDebouncedCallback(
+ *     (query: string) => fetchResults(query),
+ *     400,
+ *   );
+ *
+ *   return (
+ *     <>
+ *       <input onChange={(e) => handleSearch(e.target.value)} />
+ *       {isPending && <span>Typing…</span>}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param func - The function to debounce. Safe to pass a new closure on
+ * every render.
+ * @param delay - See {@link useDebouncer}.
+ * @param options - See {@link DebounceOptions}.
+ * @returns See {@link UseDebouncedCallbackReturn}.
+ */
 export declare function useDebouncedCallback<Args extends unknown[]>(func: (...args: Args) => void, delay: number, options?: DebounceOptions): UseDebouncedCallbackReturn<Args>;
+/**
+ * The tuple returned by `useDebouncedState`, mirroring `useState`'s
+ * `[value, setValue]` shape with a third element carrying debounce
+ * controls.
+ */
 export type UseDebouncedStateReturn<T> = [
+	/** The current, committed state value. */
 	T,
-	(value: T) => void,
+	/**
+	 * Schedules a debounced update to state. Accepts either a plain value
+	 * or a `useState`-style functional updater (`(previous) => next`).
+	 *
+	 * The functional-updater form composes correctly across multiple rapid
+	 * calls made before the debounce settles — e.g. calling
+	 * `setValue((p) => p + 1)` three times in a row schedules a cumulative
+	 * `+3`, not three competing `+1`s racing to be "the" pending value.
+	 * `previous` in that case refers to the most recently *scheduled*
+	 * value, not necessarily the currently-committed state — this matters
+	 * if you're chaining updates faster than the debounce settles.
+	 */
+	(value: T | ((previous: T) => T)) => void,
 	{
+		/** See {@link UseDebouncerReturn.isPending}. */
 		isPending: boolean;
+		/**
+		 * Cancels any pending debounced update. Also resyncs the internal
+		 * "next value to commit" tracking back to the current committed
+		 * state, so a subsequent functional update starts from the right
+		 * baseline instead of building on a discarded value.
+		 */
 		cancel: () => void;
+		/** See {@link UseDebouncerReturn.flush}. */
 		flush: () => void;
-		forceSetValue: (value: T) => void;
+		/**
+		 * Bypasses debounce scheduling entirely and applies the value (or
+		 * updater) immediately. Also cancels any debounced update that was
+		 * still pending, so it can't land afterward and silently overwrite
+		 * this forced value.
+		 */
+		forceSetValue: (value: T | ((previous: T) => T)) => void;
 	}
 ];
-export declare function useDebouncedState<T>(initialValue: T | (() => T), delay: number, options?: DebounceOptions): UseDebouncedStateReturn<T>;
-export type UseDebouncedValueReturn<T> = T;
-export declare function useDebouncedValue<T>(value: T, delay: number, options?: DebounceOptions): UseDebouncedValueReturn<T>;
+/**
+ * A `useState`-shaped hook whose setter defers its effect on state until
+ * the debounce window settles, instead of applying immediately.
+ *
+ * @example
+ * ```tsx
+ * function NoteEditor() {
+ *   const [note, setNote, { isPending, flush, forceSetValue }] =
+ *     useDebouncedState("", 800);
+ *
+ *   return (
+ *     <>
+ *       <textarea onChange={(e) => setNote(e.target.value)} />
+ *       <p>Committed: {note}</p>
+ *       {isPending && <span>Unsaved changes…</span>}
+ *       <button onClick={flush}>Save Now</button>
+ *       <button onClick={() => forceSetValue("")}>Reset</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param initialValue - Initial state value, or a `useState`-style lazy
+ * initializer function (`() => T`).
+ * @param delay - See {@link useDebouncer}.
+ * @param options - See {@link UseDebouncedStateOptions}.
+ * @returns See {@link UseDebouncedStateReturn}.
+ */
+export declare function useDebouncedState<T>(initialValue: T | (() => T), delay: number, options?: UseDebouncedStateOptions<T>): UseDebouncedStateReturn<T>;
+/**
+ * The tuple returned by `useDebouncedValue`.
+ */
+export type UseDebouncedValueReturn<T> = [
+	/** The debounced (lagging) mirror of the source value. */
+	T,
+	{
+		/** See {@link UseDebouncerReturn.isPending}. */
+		isPending: boolean;
+		/** Cancels the pending sync to the latest source value. */
+		cancel: () => void;
+		/** Immediately commits the latest source value, bypassing the delay. */
+		flush: () => void;
+	}
+];
+/**
+ * Mirrors `value`, but the mirror only updates `delay` milliseconds after
+ * `value` stops changing — a safe, stable dependency for an expensive
+ * effect (filtering, fetching) that shouldn't re-run on every keystroke.
+ *
+ * @example
+ * ```tsx
+ * function ProductFilterField() {
+ *   const [query, setQuery] = useState("");
+ *   const [debouncedQuery] = useDebouncedValue(query, 350);
+ *
+ *   // `debouncedQuery` only updates 350ms after typing stops.
+ *
+ *   return (
+ *     <input value={query} onChange={(e) => setQuery(e.target.value)} />
+ *   );
+ * }
+ * ```
+ *
+ * @param value - The source value to debounce. Every change re-arms the
+ * debounce window.
+ * @param delay - See {@link useDebouncer}.
+ * @param options - See {@link UseDebouncedValueOptions}.
+ * @returns See {@link UseDebouncedValueReturn}.
+ */
+export declare function useDebouncedValue<T>(value: T, delay: number, options?: UseDebouncedValueOptions<T>): UseDebouncedValueReturn<T>;
+/**
+ * The object returned by `useDebouncer`.
+ */
+export interface UseDebouncerReturn {
+	/**
+	 * Registers `func` (with `args`) as the function this debounce cycle
+	 * will invoke, and (re)arms the debounce timer.
+	 *
+	 * Each call to `run()` accepts its own function — you are not locked
+	 * into debouncing a single, fixed callback. If `run()` is called again
+	 * before the pending timer fires, the previously-registered function
+	 * and arguments are discarded entirely in favor of the new ones (a
+	 * "last write wins" swap, not a queue).
+	 *
+	 * @example
+	 * ```ts
+	 * const { run } = useDebouncer(300);
+	 *
+	 * run((query: string) => fetchResults(query), searchTerm);
+	 * ```
+	 */
+	run: <Args extends unknown[]>(func: (...args: Args) => void, ...args: Args) => void;
+	/**
+	 * Clears the pending timer and discards whatever function/arguments
+	 * were registered via `run()`, without invoking anything. Sets
+	 * `isPending` back to `false`.
+	 */
+	cancel: () => void;
+	/**
+	 * If a function is currently pending invocation, invokes it immediately
+	 * (with its most recently registered arguments) and clears the timer.
+	 * If nothing is pending, this is a no-op.
+	 */
+	flush: () => void;
+	/**
+	 * `true` whenever a trailing invocation is still scheduled to happen
+	 * when the current cycle settles. `false` once it's known nothing
+	 * further will fire — including immediately after a leading-edge
+	 * invocation if `trailing` is disabled, not merely once the full window
+	 * elapses.
+	 */
+	isPending: boolean;
+}
+/**
+ * The debounce engine underlying every hook in this family.
+ *
+ * `useDebouncer` is a low-level scheduling primitive: a single timer and a
+ * single "next function to run" slot. Calling `run(func, ...args)`
+ * registers `func` as the occupant of that slot; if `run()` is called
+ * again before the timer fires, the new function/arguments replace the old
+ * ones outright.
+ *
+ * Most consumers won't reach for this directly — `useDebouncedCallback`,
+ * `useDebouncedState`, and `useDebouncedValue` are thin, purpose-built
+ * wrappers around it for the common cases (debouncing one fixed callback,
+ * a piece of state, or an incoming value). Use `useDebouncer` directly when
+ * you need the "swap, don't queue" behavior across genuinely different
+ * functions — see the example below.
+ *
+ * @example
+ * ```tsx
+ * function DocumentActionBar() {
+ *   const { run, isPending } = useDebouncer(1000);
+ *
+ *   const handleSave = () => run(() => saveDocument());
+ *   const handleCancel = () => run(() => discardChanges());
+ *
+ *   return (
+ *     <>
+ *       <button onClick={handleSave}>Save</button>
+ *       <button onClick={handleCancel}>Cancel</button>
+ *       {isPending && <span>Pending…</span>}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param delay - Milliseconds to wait before a trailing invocation fires.
+ * Coerced to a non-negative number; invalid input falls back to `0` with a
+ * dev-mode warning.
+ * @param options - See {@link DebounceOptions}.
+ * @returns See {@link UseDebouncerReturn}.
+ */
+export declare function useDebouncer(delay: number, options?: DebounceOptions): UseDebouncerReturn;
+/**
+ * Configuration for `useRateLimiter` and every hook built on top of it.
+ */
 export interface RateLimitOptions {
+	/**
+	 * Called whenever a call is rejected because no executions remain in
+	 * the current window.
+	 *
+	 * Safe to pass a fresh inline function on every render — it's captured
+	 * in a ref and refreshed via effect, so it never causes the underlying
+	 * timers to reset.
+	 *
+	 * @defaultValue `undefined`
+	 */
 	onRateLimitReached?: () => void;
+	/**
+	 * Determines how the allowance replenishes once consumed.
+	 *
+	 * - `"burst"` — fixed window. All executions reset to the full `limit`
+	 *   at once, only once the entire `windowMs` duration has elapsed
+	 *   since the window began.
+	 * - `"gradual"` — trickle refill. Executions return proportionately as
+	 *   time passes (`windowMs / limit` per execution), with no hard reset
+	 *   boundary.
+	 *
+	 * @defaultValue `"burst"`
+	 */
 	refillStrategy?: "burst" | "gradual";
 }
-export interface UseRateLimitReturn {
-	run: <Args extends unknown[]>(func: (...args: Args) => void, ...args: Args) => void;
+/**
+ * Options for `useRateLimitedState`: all of {@link RateLimitOptions}, plus
+ * an optional equality comparator used to skip committing a value
+ * equivalent to the one already held.
+ */
+export type UseRateLimitedStateOptions<T> = RateLimitOptions & EqualityFnOption<T>;
+/**
+ * Options for `useRateLimitedValue`: all of {@link RateLimitOptions}, plus
+ * an optional equality comparator used to skip committing a value
+ * equivalent to the one already held.
+ */
+export type UseRateLimitedValueOptions<T> = RateLimitOptions & EqualityFnOption<T>;
+/**
+ * The object returned by `useRateLimitedCallback`.
+ */
+export interface UseRateLimitedCallbackReturn<Args extends unknown[]> {
+	/**
+	 * A stable, rate-limited wrapper around `func`. Always invokes the
+	 * most recently rendered `func`, even though `rateLimitedFunc`'s own
+	 * identity doesn't change across re-renders.
+	 *
+	 * @returns `true` if `func` was invoked, `false` if the call was
+	 * rejected because the allowance is exhausted.
+	 */
+	rateLimitedFunc: (...args: Args) => boolean;
+	/** See {@link UseRateLimiterReturn.reset}. */
+	reset: () => void;
+	/** See {@link UseRateLimiterReturn.remaining}. */
 	remaining: number;
+	/** See {@link UseRateLimiterReturn.isRateLimited}. */
 	isRateLimited: boolean;
 }
-export declare function useRateLimit(limit: number, windowMs: number, options?: RateLimitOptions): UseRateLimitReturn;
-export interface UseRateLimitedCallbackReturn<Args extends unknown[]> {
-	rateLimitedFunc: (...args: Args) => void;
+/**
+ * Rate-limits a single function.
+ *
+ * `func` is captured in a ref and refreshed on every render — you can
+ * pass a fresh inline closure every time without resetting the
+ * underlying allowance tracking, and the wrapper always calls the
+ * *latest* `func`.
+ *
+ * @example
+ * ```tsx
+ * function SearchBox() {
+ *   const { rateLimitedFunc, isRateLimited } = useRateLimitedCallback(
+ *     (query: string) => fetch(`/api/search?q=${query}`),
+ *     10,
+ *     60_000,
+ *     { refillStrategy: "gradual" },
+ *   );
+ *
+ *   return (
+ *     <input
+ *       disabled={isRateLimited}
+ *       onChange={(e) => rateLimitedFunc(e.target.value)}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param func - The function to rate-limit. Safe to pass a new closure
+ * on every render.
+ * @param limit - See {@link useRateLimiter}.
+ * @param windowMs - See {@link useRateLimiter}.
+ * @param options - See {@link RateLimitOptions}.
+ * @returns See {@link UseRateLimitedCallbackReturn}.
+ */
+export declare function useRateLimitedCallback<Args extends unknown[]>(func: (...args: Args) => void, limit: number, windowMs: number, options?: RateLimitOptions): UseRateLimitedCallbackReturn<Args>;
+/**
+ * The tuple returned by `useRateLimitedState`, mirroring `useState`'s
+ * `[value, setValue]` shape with a third element carrying rate-limit
+ * controls.
+ */
+export type UseRateLimitedStateReturn<T> = [
+	/** The current, committed state value. */
+	T,
+	/**
+	 * Attempts to update state. Accepts either a plain value or a
+	 * `useState`-style functional updater (`(previous) => next`).
+	 *
+	 * Unlike the debounce/throttle `State` variants, nothing here is ever
+	 * deferred — the update either applies immediately (against the
+	 * genuinely current state, via React's own functional `setState`) or
+	 * is rejected outright and state doesn't change at all. There's no
+	 * "most recently scheduled value" to reason about, since nothing is
+	 * ever queued.
+	 *
+	 * @returns `true` if the update was applied, `false` if it was
+	 * rejected because the allowance is exhausted.
+	 */
+	(value: T | ((previous: T) => T)) => boolean,
+	{
+		/** See {@link UseRateLimiterReturn.remaining}. */
+		remaining: number;
+		/** See {@link UseRateLimiterReturn.isRateLimited}. */
+		isRateLimited: boolean;
+		/** See {@link UseRateLimiterReturn.reset}. */
+		reset: () => void;
+		/**
+		 * Bypasses rate-limit enforcement entirely and applies the value
+		 * (or updater) immediately. Does not consume any of the allowance.
+		 */
+		forceSetValue: (value: T | ((previous: T) => T)) => void;
+	}
+];
+/**
+ * A `useState`-shaped hook whose setter can be rejected once the
+ * allowance for the current window is exhausted, instead of always
+ * applying.
+ *
+ * @example
+ * ```tsx
+ * function GenerationDemo() {
+ *   const [result, generate, { remaining, isRateLimited }] =
+ *     useRateLimitedState<string | null>(null, 3, 60_000);
+ *
+ *   const handleGenerate = () => {
+ *     if (!generate(`Result #${Math.random()}`)) {
+ *       toast("Free limit reached — try again in a minute.");
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={handleGenerate} disabled={isRateLimited}>
+ *         Generate ({remaining} left)
+ *       </button>
+ *       <p>{result}</p>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param initialValue - Initial state value, or a `useState`-style lazy
+ * initializer function (`() => T`).
+ * @param limit - See {@link useRateLimiter}.
+ * @param windowMs - See {@link useRateLimiter}.
+ * @param options - See {@link UseRateLimitedStateOptions}.
+ * @returns See {@link UseRateLimitedStateReturn}.
+ */
+export declare function useRateLimitedState<T>(initialValue: T | (() => T), limit: number, windowMs: number, options?: UseRateLimitedStateOptions<T>): UseRateLimitedStateReturn<T>;
+/**
+ * The tuple returned by `useRateLimitedValue`.
+ */
+export type UseRateLimitedValueReturn<T> = [
+	/** The rate-limited mirror of the source value. */
+	T,
+	{
+		/** See {@link UseRateLimiterReturn.remaining}. */
+		remaining: number;
+		/** See {@link UseRateLimiterReturn.isRateLimited}. */
+		isRateLimited: boolean;
+		/** See {@link UseRateLimiterReturn.reset}. */
+		reset: () => void;
+	}
+];
+/**
+ * Mirrors `value`, but the mirror updates at most `limit` times per
+ * `windowMs` window.
+ *
+ * @remarks
+ * This has a meaningfully weaker guarantee than `useDebouncedValue` /
+ * `useThrottledValue`. Those hooks eventually deliver the *latest* value
+ * once their window settles, even if intermediate values were skipped.
+ * This hook does not — once the allowance is exhausted, incoming changes
+ * to `value` are dropped outright until the allowance refills, with no
+ * queueing and no catch-up. The mirror simply stays frozen at whatever it
+ * last committed until it's allowed to update again.
+ *
+ * @example
+ * ```tsx
+ * function NotificationFeed({ latestNotification }: { latestNotification: string }) {
+ *   const [visibleNotification] = useRateLimitedValue(latestNotification, 3, 10_000);
+ *
+ *   // At most 3 notifications surface per 10s window; any beyond that
+ *   // are silently dropped rather than queued for later display.
+ *
+ *   return <Toast message={visibleNotification} />;
+ * }
+ * ```
+ *
+ * @param value - The source value to rate-limit. Every change is subject
+ * to the current allowance.
+ * @param limit - See {@link useRateLimiter}.
+ * @param windowMs - See {@link useRateLimiter}.
+ * @param options - See {@link UseRateLimitedValueOptions}.
+ * @returns See {@link UseRateLimitedValueReturn}.
+ */
+export declare function useRateLimitedValue<T>(value: T, limit: number, windowMs: number, options?: UseRateLimitedValueOptions<T>): UseRateLimitedValueReturn<T>;
+/**
+ * The object returned by `useRateLimiter`.
+ */
+export interface UseRateLimiterReturn {
+	/**
+	 * Attempts to invoke `func` (with `args`) against the current
+	 * allowance.
+	 *
+	 * Unlike `useDebouncer`/`useThrottler`, nothing here is ever deferred —
+	 * every call to `run()` resolves synchronously, right now: either an
+	 * execution is available and `func` runs immediately, or it isn't and
+	 * `func` doesn't run at all (no queueing, no later catch-up).
+	 *
+	 * Each call accepts its own function, so a single `useRateLimiter`
+	 * instance can gate several different actions against one shared
+	 * allowance if needed.
+	 *
+	 * @returns `true` if `func` was invoked, `false` if the call was
+	 * rejected because the current window's allowance is exhausted.
+	 *
+	 * @example
+	 * ```ts
+	 * const { run } = useRateLimiter(3, 10_000);
+	 *
+	 * const didFire = run(() => submitForm());
+	 * if (!didFire) showToast("Too many attempts — please wait.");
+	 * ```
+	 */
+	run: <Args extends unknown[]>(func: (...args: Args) => void, ...args: Args) => boolean;
+	/**
+	 * Immediately restores the full allowance and clears any in-progress
+	 * background refill, bypassing the normal window/refill timing
+	 * entirely. Useful after an unrelated event that should grant a fresh
+	 * allowance outright — e.g. a successful CAPTCHA, or a plan upgrade.
+	 */
+	reset: () => void;
+	/**
+	 * The number of executions currently available. Kept accurate in real
+	 * time — including while idle, with no further calls to `run()` —
+	 * by a self-scheduling background timer that mirrors whichever
+	 * `refillStrategy` is configured.
+	 */
 	remaining: number;
+	/** Convenience flag, equivalent to `remaining === 0`. */
 	isRateLimited: boolean;
 }
-export declare function useRateLimitedCallback<Args extends unknown[]>(func: (...args: Args) => void, limit: number, windowMs: number, options?: RateLimitOptions): UseRateLimitedCallbackReturn<Args>;
+/**
+ * The rate-limiting engine underlying every hook in this family.
+ *
+ * `useRateLimiter` grants up to `limit` executions per `windowMs` window,
+ * replenished according to `refillStrategy`. Unlike debounce or throttle,
+ * it never delays or reshapes *when* something runs — every call is an
+ * immediate accept-or-reject decision against the current allowance.
+ *
+ * Most consumers won't reach for this directly — `useRateLimitedCallback`,
+ * `useRateLimitedState`, and `useRateLimitedValue` are thin, purpose-built
+ * wrappers around it for the common cases.
+ *
+ * @example
+ * ```tsx
+ * function SubmitButton() {
+ *   const { run, remaining, isRateLimited } = useRateLimiter(3, 10_000, {
+ *     refillStrategy: "burst",
+ *     onRateLimitReached: () => toast("Too many attempts."),
+ *   });
+ *
+ *   return (
+ *     <button onClick={() => run(submitForm)} disabled={isRateLimited}>
+ *       Submit ({remaining} left)
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @param limit - Maximum executions allowed per window. Coerced to a
+ * non-negative integer with a floor of `1`; invalid input falls back to
+ * `1` with a dev-mode warning.
+ * @param windowMs - Length of the rate-limit window, in milliseconds.
+ * Coerced to a non-negative number; invalid input falls back to `0` with
+ * a dev-mode warning. A value of `0` disables rate limiting entirely
+ * (every call is allowed) rather than causing a division error — also
+ * dev-warned, since it's rarely intentional.
+ * @param options - See {@link RateLimitOptions}.
+ * @returns See {@link UseRateLimiterReturn}.
+ */
+export declare function useRateLimiter(limit: number, windowMs: number, options?: RateLimitOptions): UseRateLimiterReturn;
+/**
+ * Configuration for `useThrottler` and every hook built on top of it.
+ *
+ * @remarks
+ * `leading` and `trailing` may both be set to `false` at the same time —
+ * the hook will not silently correct this for you. That configuration
+ * means the throttled function will never run; a dev-mode warning is
+ * logged to help catch it early, but the choice itself is respected.
+ */
 export interface ThrottleOptions {
+	/**
+	 * When `true`, invokes immediately on the first call of a new cooldown
+	 * window.
+	 *
+	 * @defaultValue `true`
+	 */
 	leading?: boolean;
+	/**
+	 * When `true`, invokes once more at the end of the cooldown window,
+	 * using the most recently passed function/arguments — but only if at
+	 * least one call arrived after the leading edge fired. A single
+	 * isolated call with both edges enabled only fires once.
+	 *
+	 * @defaultValue `true`
+	 */
 	trailing?: boolean;
 }
-export interface UseThrottleReturn {
-	run: <Args extends unknown[]>(func: (...args: Args) => void, ...args: Args) => void;
-	cancel: () => void;
-	flush: () => void;
-	isPending: boolean;
-}
-export declare function useThrottle(delay: number, options?: ThrottleOptions): UseThrottleReturn;
+/**
+ * Options for `useThrottledState`: all of {@link ThrottleOptions}, plus an
+ * optional equality comparator used to skip committing a value equivalent
+ * to the one already held.
+ */
+export type UseThrottledStateOptions<T> = ThrottleOptions & EqualityFnOption<T>;
+/**
+ * Options for `useThrottledValue`: all of {@link ThrottleOptions}, plus an
+ * optional equality comparator used to skip committing a value equivalent
+ * to the one already held.
+ */
+export type UseThrottledValueOptions<T> = ThrottleOptions & EqualityFnOption<T>;
+/**
+ * The object returned by `useThrottledCallback`.
+ */
 export interface UseThrottledCallbackReturn<Args extends unknown[]> {
+	/**
+	 * A stable, throttled wrapper around `func`. Safe to attach directly
+	 * to an event listener; internally always invokes the most recently
+	 * rendered `func`, even though `throttledFunc`'s own identity doesn't
+	 * change across re-renders.
+	 */
 	throttledFunc: (...args: Args) => void;
+	/** See {@link UseThrottlerReturn.cancel}. */
 	cancel: () => void;
+	/** See {@link UseThrottlerReturn.flush}. */
 	flush: () => void;
+	/** See {@link UseThrottlerReturn.isPending}. */
 	isPending: boolean;
 }
+/**
+ * Throttles a single function.
+ *
+ * `func` is captured in a ref and refreshed on every render — you can pass
+ * a fresh inline closure every time without resetting the running cooldown
+ * window, and the throttled wrapper always calls the *latest* `func`,
+ * closing over whatever props/state were current when it actually fires
+ * (never a stale closure from whenever the wrapper was first created).
+ *
+ * @example
+ * ```tsx
+ * function WindowSizeLogger() {
+ *   const { throttledFunc: handleResize } = useThrottledCallback(
+ *     () => console.log("width:", window.innerWidth),
+ *     200,
+ *   );
+ *
+ *   useEffect(() => {
+ *     window.addEventListener("resize", handleResize);
+ *     return () => window.removeEventListener("resize", handleResize);
+ *   }, [handleResize]);
+ *
+ *   return null;
+ * }
+ * ```
+ *
+ * @param func - The function to throttle. Safe to pass a new closure on
+ * every render.
+ * @param delay - See {@link useThrottler}.
+ * @param options - See {@link ThrottleOptions}.
+ * @returns See {@link UseThrottledCallbackReturn}.
+ */
 export declare function useThrottledCallback<Args extends unknown[]>(func: (...args: Args) => void, delay: number, options?: ThrottleOptions): UseThrottledCallbackReturn<Args>;
+/**
+ * The tuple returned by `useThrottledState`, mirroring `useState`'s
+ * `[value, setValue]` shape with a third element carrying throttle
+ * controls.
+ */
 export type UseThrottledStateReturn<T> = [
+	/** The current (throttled) state value. */
 	T,
-	(value: T) => void,
+	/**
+	 * Schedules a throttled update to state. Accepts either a plain value
+	 * or a `useState`-style functional updater (`(previous) => next`).
+	 *
+	 * The functional-updater form composes correctly across multiple rapid
+	 * calls made before the cooldown window settles — e.g. calling
+	 * `setValue((p) => p + 1)` three times in a row schedules a cumulative
+	 * `+3`, not three competing `+1`s racing to be "the" pending value.
+	 * `previous` in that case refers to the most recently *scheduled*
+	 * value, not necessarily the currently-committed state — this matters
+	 * if you're chaining updates faster than the window settles.
+	 */
+	(value: T | ((previous: T) => T)) => void,
 	{
+		/** See {@link UseThrottlerReturn.isPending}. */
 		isPending: boolean;
+		/**
+		 * Cancels any pending throttled update. Also resyncs the internal
+		 * "next value to commit" tracking back to the current committed
+		 * state, so a subsequent functional update starts from the right
+		 * baseline instead of building on a discarded value.
+		 */
 		cancel: () => void;
+		/** See {@link UseThrottlerReturn.flush}. */
 		flush: () => void;
-		forceSetValue: (value: T) => void;
+		/**
+		 * Bypasses throttle scheduling entirely and applies the value (or
+		 * updater) immediately. Also cancels any throttled update that was
+		 * still pending, so it can't land afterward and silently overwrite
+		 * this forced value.
+		 */
+		forceSetValue: (value: T | ((previous: T) => T)) => void;
 	}
 ];
-export declare function useThrottledState<T>(initialValue: T | (() => T), delay: number, options?: ThrottleOptions): UseThrottledStateReturn<T>;
-export type UseThrottledValueReturn<T> = T;
-export declare function useThrottledValue<T>(value: T, delay: number, options?: ThrottleOptions): UseThrottledValueReturn<T>;
+/**
+ * A `useState`-shaped hook whose setter rate-limits its effect on state
+ * instead of applying immediately.
+ *
+ * @example
+ * ```tsx
+ * function ScoreBoard() {
+ *   const [score, setScore, { flush, forceSetValue, isPending }] =
+ *     useThrottledState(() => expensiveInitialScore(), 500);
+ *
+ *   return (
+ *     <>
+ *       <p>Score: {score}</p>
+ *       <button onClick={() => setScore((s) => s + 1)}>+1 (throttled)</button>
+ *       <button onClick={flush}>Flush pending update</button>
+ *       <button onClick={() => forceSetValue(0)}>Reset instantly</button>
+ *       {isPending && <span>update queued…</span>}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param initialValue - Initial state value, or a `useState`-style lazy
+ * initializer function (`() => T`).
+ * @param delay - See {@link useThrottler}.
+ * @param options - See {@link UseThrottledStateOptions}.
+ * @returns See {@link UseThrottledStateReturn}.
+ */
+export declare function useThrottledState<T>(initialValue: T | (() => T), delay: number, options?: UseThrottledStateOptions<T>): UseThrottledStateReturn<T>;
+/**
+ * The tuple returned by `useThrottledValue`.
+ */
+export type UseThrottledValueReturn<T> = [
+	/** The throttled (rate-limited) mirror of the source value. */
+	T,
+	{
+		/** See {@link UseThrottlerReturn.isPending}. */
+		isPending: boolean;
+		/** Cancels the pending sync to the latest source value. */
+		cancel: () => void;
+		/** Immediately commits the latest source value, bypassing the wait. */
+		flush: () => void;
+	}
+];
+/**
+ * Mirrors `value`, but the mirror updates at most once every `delay`
+ * milliseconds — a safe, rate-limited dependency for an expensive
+ * downstream render (chart, canvas, map) driven by a fast-changing source
+ * like a slider or live coordinates.
+ *
+ * @remarks
+ * With the default `{ leading: true }`, the mirror updates almost
+ * immediately on the first change — throttle is about limiting *rate*,
+ * not deferring the first response the way debounce does.
+ *
+ * @example
+ * ```tsx
+ * function SliderDemo() {
+ *   const [raw, setRaw] = useState(0);
+ *   const [throttled] = useThrottledValue(raw, 100);
+ *
+ *   return (
+ *     <>
+ *       <input
+ *         type="range"
+ *         value={raw}
+ *         onChange={(e) => setRaw(Number(e.target.value))}
+ *       />
+ *       <HeavyPreview value={throttled} />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param value - The source value to throttle. Every change is subject to
+ * the cooldown window.
+ * @param delay - See {@link useThrottler}.
+ * @param options - See {@link UseThrottledValueOptions}.
+ * @returns See {@link UseThrottledValueReturn}.
+ */
+export declare function useThrottledValue<T>(value: T, delay: number, options?: UseThrottledValueOptions<T>): UseThrottledValueReturn<T>;
+/**
+ * The object returned by `useThrottler`.
+ */
+export interface UseThrottlerReturn {
+	/**
+	 * Registers `func` (with `args`) as the function this cooldown window
+	 * will invoke.
+	 *
+	 * Each call to `run()` accepts its own function — you are not locked
+	 * into throttling a single, fixed callback. If a trailing invocation is
+	 * still pending when `run()` is called again, the previously-registered
+	 * function and arguments are replaced by the new ones — whichever call
+	 * was most recent before the window closes is the one that fires (a
+	 * "last write wins" swap, not a queue).
+	 *
+	 * @example
+	 * ```ts
+	 * const { run } = useThrottler(200);
+	 *
+	 * run((x: number, y: number) => logPosition(x, y), clientX, clientY);
+	 * ```
+	 */
+	run: <Args extends unknown[]>(func: (...args: Args) => void, ...args: Args) => void;
+	/**
+	 * Clears any pending trailing invocation and resets the cooldown
+	 * window entirely — the next call to `run()` is treated as the start
+	 * of a fresh window. Sets `isPending` back to `false`.
+	 */
+	cancel: () => void;
+	/**
+	 * If a trailing invocation is currently pending, invokes it
+	 * immediately (with its most recently registered arguments) and clears
+	 * the timer. If nothing is pending, this is a no-op.
+	 */
+	flush: () => void;
+	/**
+	 * `true` whenever a trailing invocation is still scheduled to fire
+	 * before the current cooldown window closes. `false` once it's known
+	 * nothing further will happen — including right after a leading-edge
+	 * invocation with no follow-up call yet, not merely once the whole
+	 * window elapses.
+	 */
+	isPending: boolean;
+}
+/**
+ * The throttle engine underlying every hook in this family.
+ *
+ * `useThrottler` is a low-level scheduling primitive: a single cooldown
+ * window and a single "next function to run" slot. Unlike debounce,
+ * additional calls that arrive mid-window do not push the window out
+ * further — they just update which function/arguments will fire when the
+ * *existing* window closes. This is what keeps a continuous stream of
+ * calls (mousemove, scroll, resize) firing at a steady cadence instead of
+ * only ever firing once activity stops.
+ *
+ * Most consumers won't reach for this directly — `useThrottledCallback`,
+ * `useThrottledState`, and `useThrottledValue` are thin, purpose-built
+ * wrappers around it for the common cases. Use `useThrottler` directly
+ * when you need the "swap, don't queue" behavior across genuinely
+ * different functions.
+ *
+ * @example
+ * ```tsx
+ * function ActivityLogger() {
+ *   const { run, isPending } = useThrottler(1000);
+ *
+ *   return (
+ *     <div
+ *       onMouseMove={(e) => run(logMouseMove, e.clientX, e.clientY)}
+ *       onKeyDown={(e) => run(logKeyPress, e.key)}
+ *     >
+ *       {isPending ? "Recording…" : "Idle"}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param delay - Length of the cooldown window, in milliseconds. Coerced
+ * to a non-negative number; invalid input falls back to `0` with a
+ * dev-mode warning.
+ * @param options - See {@link ThrottleOptions}.
+ * @returns See {@link UseThrottlerReturn}.
+ */
+export declare function useThrottler(delay: number, options?: ThrottleOptions): UseThrottlerReturn;
 export type ScrollAlign = "start" | "center" | "end" | "auto";
 export type Axis = "vertical" | "horizontal";
 export interface ScrollToOffsetOptions {