@himanshu-sorathiya/react-kit 1.0.26 → 1.0.28

package/dist/index.d.ts

@@ -417,85 +417,938 @@ export type UseKeyReturn = () => void;
  * ```
  */
 export declare function useKey(key: string, handler: (event: KeyboardEvent) => void, options?: UseKeyOptions): UseKeyReturn;
+/**
+ * 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;
+}
+/**
+ * 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;
 }
-export interface UseDebounceReturn {
-	run: <Args extends unknown[]>(func: (...args: Args) => void, ...args: Args) => void;
-	cancel: () => void;
-	flush: () => void;
-	isPending: boolean;
-}
-export declare function useDebounce(delay: number, options?: DebounceOptions): UseDebounceReturn;
+/**
+ * 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 {
@@ -816,43 +1669,295 @@ export interface UseSortReturn<T> {
 	getSortIndex: (id: string) => number | undefined;
 }
 export declare function useSort<T>(data?: T[], initialSorts?: SortState): UseSortReturn<T>;
+/**
+ * Defines how a value of type `T` is converted to and from the string
+ * format that `localStorage`/`sessionStorage` can actually store — the Web
+ * Storage API only ever stores strings.
+ *
+ * Implement this to store types the default JSON-based serializer can't
+ * round-trip faithfully, e.g. `Map`, `Set`, `Date`, or `bigint` — see
+ * `mapSerializer`, `setSerializer`, `dateSerializer`, and
+ * `bigIntSerializer` in `serializers.ts` for ready-made ones.
+ *
+ * @typeParam T - The in-memory value type this serializer handles.
+ */
 export interface StorageSerializer<T> {
+	/** Converts an in-memory value into the string that gets stored. */
 	serialize: (value: T) => string;
+	/**
+	 * Converts a stored string back into an in-memory value.
+	 *
+	 * @throws If the raw string can't be converted back into `T`. The hook
+	 * catches this, falls back to `initialValue`, and reports the error —
+	 * see `onError` on {@link BaseStorageOptions}.
+	 */
 	deserialize: (raw: string) => T;
 }
+/**
+ * Options shared by `useLocalStorage` and `useSessionStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
 export interface BaseStorageOptions<T> {
+	/**
+	 * Custom (de)serializer for values that don't round-trip through
+	 * `JSON.stringify`/`JSON.parse` cleanly.
+	 *
+	 * @defaultValue `defaultSerializer` (plain `JSON.stringify`/`JSON.parse`)
+	 */
 	serializer?: StorageSerializer<T>;
+	/**
+	 * Whether to synchronously read the existing stored value on mount.
+	 *
+	 * - `true` (default): `value` reflects storage from the very first
+	 *   render it's allowed to (see the SSR note below).
+	 * - `false`: `value` starts as `undefined` and only reflects storage
+	 *   once `isHydrated` becomes `true`, one render after mount. Use this
+	 *   if you'd rather render a loading/skeleton state than briefly show a
+	 *   value that might change right after.
+	 *
+	 * Either way, on the server — and during the client's hydration render
+	 * — `value` is always `initialValue`. This option only affects timing
+	 * on the client, after that point.
+	 *
+	 * @defaultValue `true`
+	 */
 	initializeWithValue?: boolean;
+	/**
+	 * Whether other instances of this hook watching the *same key* in the
+	 * *same tab* stay in sync with each other. Implemented via a
+	 * `CustomEvent` dispatched on `window` — the browser's native `storage`
+	 * event never fires in the tab that made the change, so without this,
+	 * two components reading the same key in one tab would drift apart.
+	 *
+	 * @defaultValue `true`
+	 */
 	sameInstanceSync?: boolean;
+	/**
+	 * Called whenever the hook hits an unexpected condition: a failed
+	 * read, a failed write, a failed cross-instance deserialize, or an
+	 * attempt to change the storage key at runtime. Fires in every
+	 * environment, including production — use this for telemetry/error
+	 * reporting.
+	 *
+	 * This is *not* a replacement for the dev-only `console.warn` the hook
+	 * also emits for the same conditions (visible when
+	 * `process.env.NODE_ENV !== "production"`) — both fire independently.
+	 */
+	onError?: (error: Error) => void;
 }
+/**
+ * Payload carried by the same-tab `CustomEvent` used for
+ * {@link BaseStorageOptions.sameInstanceSync}. Internal — not part of the
+ * public hook API, but exported so `useStorageEngine.ts` can import it.
+ */
 export interface StorageCustomEventDetail {
+	/** The new serialized value, or `null` if the key was removed. */
 	value: string | null;
+	/**
+	 * A per-hook-instance identifier, used so an instance can recognize —
+	 * and ignore — the event it just dispatched itself.
+	 */
 	instanceId: symbol;
 }
-export interface UseLocalStorageOptions<T> extends BaseStorageOptions<T> {
-	crossInstanceSync?: boolean;
-}
-export interface UseLocalStorageReturn<T> {
+/**
+ * The shape returned by {@link useStorageEngine} — and, re-exported, by
+ * both `useLocalStorage` and `useSessionStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+interface UseStorageEngineReturn<T> {
+	/**
+	 * The current value.
+	 *
+	 * - `undefined` if nothing is stored yet and no `initialValue` was
+	 *   given, or — when `initializeWithValue: false` — before hydration
+	 *   completes.
+	 * - On the server, and during the client's hydration render, this is
+	 *   always `initialValue`: real storage can only be read client-side,
+	 *   and reading it any earlier would produce a hydration mismatch.
+	 */
 	value: T | undefined;
+	/**
+	 * Writes a new value to storage. Accepts either the value directly, or
+	 * an updater function that receives the current value and returns the
+	 * next one — the same convention as `useState`'s setter.
+	 *
+	 * A no-op if storage isn't available (SSR, or storage access blocked).
+	 */
 	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
+	/**
+	 * Removes the key from storage entirely and resets `value` back to
+	 * whatever `initialValue` was passed to the hook.
+	 *
+	 * A no-op if storage isn't available (SSR, or storage access blocked).
+	 */
 	removeValue: () => void;
+	/**
+	 * `true` once the client has mounted and the hook has settled on its
+	 * real (non-server-snapshot) value. Useful for showing a loading state
+	 * instead of a value that might change the instant hydration finishes.
+	 */
 	isHydrated: boolean;
+	/**
+	 * The most recent error the hook encountered — a failed read, write,
+	 * or cross-instance sync, or an attempted key change — or `null` if
+	 * nothing has gone wrong (or an error was cleared by a subsequent
+	 * successful write/remove). See `onError` on {@link BaseStorageOptions}
+	 * for an imperative alternative to reading this reactively.
+	 */
 	error: Error | null;
 }
-export declare function useLocalStorage<T = unknown>(key: string, initialValue?: T, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;
-export type UseSessionStorageOptions<T> = BaseStorageOptions<T>;
-export interface UseSessionStorageReturn<T> {
-	value: T | undefined;
-	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
-	removeValue: () => void;
-	isHydrated: boolean;
-	error: Error | null;
+/**
+ * Options accepted by `useLocalStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+export interface UseLocalStorageOptions<T> extends BaseStorageOptions<T> {
+	/**
+	 * Whether this hook instance should sync with the same key changing in
+	 * *other tabs/windows* on the same origin, via the browser's native
+	 * `storage` event. Has no `sessionStorage` equivalent — sessionStorage
+	 * isn't shared across tabs, so there's nothing to sync in that case.
+	 *
+	 * @defaultValue `true`
+	 */
+	crossInstanceSync?: boolean;
 }
-export declare function useSessionStorage<T = unknown>(key: string, initialValue?: T, options?: UseSessionStorageOptions<T>): UseSessionStorageReturn<T>;
+/**
+ * Reads and writes a `localStorage` key, kept in sync with React state.
+ *
+ * - Persists across page reloads and browser restarts (unlike
+ *   `useSessionStorage`).
+ * - Stays in sync with every component in the current tab watching the
+ *   same key — see {@link UseLocalStorageOptions.sameInstanceSync} — and
+ *   with other tabs/windows on the same origin — see
+ *   {@link UseLocalStorageOptions.crossInstanceSync}.
+ * - Safe under SSR: on the server, and during the client's hydration
+ *   render, `value` is always `initialValue`. The real stored value is
+ *   only read client-side, immediately after hydration.
+ *
+ * @typeParam T - The type of value being stored. Defaults to `unknown` if
+ * omitted — pass an explicit type argument for anything beyond ad-hoc use.
+ * @param key - The `localStorage` key to read and write. Changing this on
+ * a later render isn't supported; the hook warns (dev console + `onError`)
+ * and keeps using the original key if you do.
+ * @param initialValue - Used when nothing is stored yet, as the value
+ * shown before hydration completes, and as what `removeValue` resets to.
+ * @param options - See {@link UseLocalStorageOptions}.
+ * @returns `{ value, setValue, removeValue, isHydrated, error }`.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * const { value: theme, setValue: setTheme } = useLocalStorage<"light" | "dark">("theme", "light");
+ *
+ * <button onClick={() => setTheme(prev => (prev === "light" ? "dark" : "light"))}>
+ *   Toggle theme
+ * </button>
+ * ```
+ *
+ * @example
+ * With a custom serializer and error reporting:
+ * ```tsx
+ * const { value, setValue, error } = useLocalStorage("lastSeen", new Date(), {
+ *   serializer: dateSerializer,
+ *   onError: (err) => reportToErrorTracker(err),
+ * });
+ * ```
+ */
+export declare function useLocalStorage<T = unknown>(key: string, initialValue?: T, options?: UseLocalStorageOptions<T>): UseStorageEngineReturn<T>;
+/**
+ * Options accepted by `useSessionStorage`. Identical to
+ * `BaseStorageOptions` — unlike `UseLocalStorageOptions`, there's no
+ * `crossInstanceSync` option here, since sessionStorage isn't shared
+ * across tabs in the first place.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+export type UseSessionStorageOptions<T> = BaseStorageOptions<T>;
+/**
+ * Reads and writes a `sessionStorage` key, kept in sync with React state.
+ *
+ * - Scoped to the current tab: cleared when the tab closes, and not
+ *   shared with other tabs (unlike `useLocalStorage`).
+ * - Stays in sync with every component in the current tab watching the
+ *   same key — see {@link UseSessionStorageOptions.sameInstanceSync}.
+ * - Safe under SSR: on the server, and during the client's hydration
+ *   render, `value` is always `initialValue`. The real stored value is
+ *   only read client-side, immediately after hydration.
+ *
+ * @typeParam T - The type of value being stored. Defaults to `unknown` if
+ * omitted — pass an explicit type argument for anything beyond ad-hoc use.
+ * @param key - The `sessionStorage` key to read and write. Changing this
+ * on a later render isn't supported; the hook warns (dev console +
+ * `onError`) and keeps using the original key if you do.
+ * @param initialValue - Used when nothing is stored yet, as the value
+ * shown before hydration completes, and as what `removeValue` resets to.
+ * @param options - See {@link UseSessionStorageOptions}.
+ * @returns `{ value, setValue, removeValue, isHydrated, error }`.
+ *
+ * @example
+ * ```tsx
+ * const { value: draft, setValue: setDraft } = useSessionStorage("draft-comment", "");
+ *
+ * <textarea value={draft ?? ""} onChange={(e) => setDraft(e.target.value)} />
+ * ```
+ */
+export declare function useSessionStorage<T = unknown>(key: string, initialValue?: T, options?: UseSessionStorageOptions<T>): UseStorageEngineReturn<T>;
+/**
+ * The default serializer used when no `serializer` option is passed to
+ * `useLocalStorage`/`useSessionStorage`. Plain `JSON.stringify`/
+ * `JSON.parse` — works for any JSON-safe value (objects, arrays, strings,
+ * numbers, booleans, `null`), but not `Map`, `Set`, `Date`, `bigint`, or
+ * `undefined` (see the other serializers below for those).
+ */
 export declare const defaultSerializer: StorageSerializer<unknown>;
+/**
+ * Serializer for `Map` values. `JSON.stringify` can't handle `Map`
+ * directly, so this round-trips it via an array of `[key, value]` entries.
+ *
+ * @typeParam K - The map's key type.
+ * @typeParam V - The map's value type.
+ *
+ * @example
+ * ```ts
+ * useLocalStorage("tags", new Map<string, number>(), {
+ *   serializer: mapSerializer<string, number>(),
+ * });
+ * ```
+ */
 export declare function mapSerializer<K, V>(): StorageSerializer<Map<K, V>>;
+/**
+ * Serializer for `Set` values, round-tripped via a plain array.
+ *
+ * @typeParam V - The set's value type.
+ *
+ * @example
+ * ```ts
+ * useLocalStorage("selectedIds", new Set<string>(), {
+ *   serializer: setSerializer<string>(),
+ * });
+ * ```
+ */
 export declare function setSerializer<V>(): StorageSerializer<Set<V>>;
+/**
+ * Serializer for `Date` values, stored as an ISO 8601 string
+ * (`Date.prototype.toISOString`).
+ *
+ * @throws During `deserialize`, if the stored string isn't a valid date —
+ * caught by the hook, which falls back to `initialValue` and reports the
+ * error via `onError`/the dev console warning.
+ */
 export declare const dateSerializer: StorageSerializer<Date>;
+/**
+ * Serializer for `bigint` values. `JSON.stringify` throws on `bigint`
+ * values, so this stores them as a plain decimal string instead.
+ *
+ * @throws During `deserialize`, if the stored string can't be converted to
+ * a `bigint` — caught by the hook, which falls back to `initialValue` and
+ * reports the error via `onError`/the dev console warning.
+ */
 export declare const bigIntSerializer: StorageSerializer<bigint>;
 export interface FuzzyHighlighterProps {
 	text: string;
@@ -948,4 +2053,9 @@ export declare function useVisibility<T = unknown>(options?: {
 	initialVisibleIds?: VisibilityId[];
 }): UseVisibilityReturn<T>;
 
+export {
+	UseStorageEngineReturn as UseLocalStorageReturn,
+	UseStorageEngineReturn as UseSessionStorageReturn,
+};
+
 export {};