react-hook-toolkit 4.0.0 → 5.0.0

package/dist/chunk1516/chunk1819.d.ts

@@ -0,0 +1,90 @@
+import { DependencyList } from 'react';
+/**
+ * Like useState but fires a callback after the state update has been applied
+ * and the component has re-rendered (via useEffect).
+ */
+export declare function useStateWithCallback<T>(initialValue: T): [T, (value: T, callback?: (v: T) => void) => void];
+/**
+ * Like useState for objects but merges partial updates (à la class component setState).
+ * Only call with object types.
+ */
+export declare function useMergeState<T extends Record<string, any>>(initialState: T): [T, (patch: Partial<T>) => void, () => void];
+/**
+ * useState augmented with a reset() function that returns the state to its
+ * initial value without needing to hold a reference to that value.
+ */
+export declare function useResetState<T>(initialValue: T): [T, React.Dispatch<React.SetStateAction<T>>, () => void];
+/**
+ * State that stays in sync across browser tabs/windows via the BroadcastChannel API.
+ * Falls back to a regular useState when BroadcastChannel is unavailable.
+ */
+export declare function useSyncedState<T>(channel: string, initialValue: T): [T, (value: T) => void];
+/**
+ * Derives a value from a source value using a transform function.
+ * Re-computes only when the source changes (same as useMemo but with a
+ * clearer "derive from source" intent).
+ */
+export declare function useDerivedState<S, T>(source: S, transform: (source: S) => T, deps?: DependencyList): T;
+/**
+ * State with a patch() method that does a deep-partial update (one level).
+ * Useful for updating nested config/settings objects.
+ */
+export declare function usePatch<T extends Record<string, any>>(initialState: T): {
+    state: T;
+    patch: (partial: Partial<T>) => void;
+    set: React.Dispatch<React.SetStateAction<T>>;
+    reset: () => void;
+};
+/**
+ * Evaluates an initializer function exactly once (on mount) and returns the
+ * result for the lifetime of the component. Unlike useMemo, this is guaranteed
+ * never to be re-computed.
+ */
+export declare function useConstant<T>(init: () => T): T;
+/**
+ * Memoizes a computed value with explicit dependencies.
+ * A semantic alias for useMemo that makes the "compute" intent clearer.
+ */
+export declare function useComputed<T>(compute: () => T, deps: DependencyList): T;
+/**
+ * Returns a stable function reference that always delegates to the latest
+ * version of the provided callback. A semantic alias for useEventCallback —
+ * safe to pass to event listeners without causing re-subscriptions.
+ */
+export declare function useStableCallback<T extends (...args: any[]) => any>(fn: T): T;
+/**
+ * Returns the number of times the component has rendered.
+ * Starts at 1 (the initial render). Useful for debugging performance.
+ */
+export declare function useRenderCount(): number;
+/**
+ * Like useEffect but uses deep equality to compare deps instead of reference equality.
+ * Prevents spurious re-runs when object/array deps are recreated with the same values.
+ */
+export declare function useDeepCompareEffect(effect: React.EffectCallback, deps: DependencyList): void;
+/**
+ * Like useMemo but uses deep equality to compare deps.
+ */
+export declare function useDeepCompareMemo<T>(factory: () => T, deps: DependencyList): T;
+/**
+ * Returns true when the value is shallowly equal to the previous render's value.
+ * Returns the previous (stable) reference when equal so downstream memos don't break.
+ */
+export declare function useShallowEqual<T>(value: T): T;
+interface UseErrorBoundaryReturn {
+    error: Error | null;
+    resetError: () => void;
+    showBoundary: (error: Error) => void;
+}
+/**
+ * Imperative error-boundary hook. Call showBoundary(error) to surface an error
+ * to the nearest React error boundary. Call resetError() to clear it.
+ * Pair with an <ErrorBoundary> component in the tree.
+ */
+export declare function useErrorBoundary(): UseErrorBoundaryReturn;
+/**
+ * Wraps useReducer to log every dispatched action and resulting state to the
+ * console in development mode. Zero overhead in production.
+ */
+export declare function useReducerLogger<S, A>(reducer: React.Reducer<S, A>, initialState: S): [S, React.Dispatch<A>];
+export {};

package/dist/chunk1516/chunk1819.js

@@ -0,0 +1,235 @@
+import { useState, useEffect, useCallback, useRef, useMemo, useReducer } from 'react';
+// ─── useStateWithCallback ─────────────────────────────────────────────────────
+/**
+ * Like useState but fires a callback after the state update has been applied
+ * and the component has re-rendered (via useEffect).
+ */
+export function useStateWithCallback(initialValue) {
+    const [state, setState] = useState(initialValue);
+    const callbackRef = useRef(null);
+    const setStateWithCallback = useCallback((value, callback) => {
+        callbackRef.current = callback !== null && callback !== void 0 ? callback : null;
+        setState(value);
+    }, []);
+    useEffect(() => {
+        if (callbackRef.current) {
+            callbackRef.current(state);
+            callbackRef.current = null;
+        }
+    }, [state]);
+    return [state, setStateWithCallback];
+}
+// ─── useMergeState ────────────────────────────────────────────────────────────
+/**
+ * Like useState for objects but merges partial updates (à la class component setState).
+ * Only call with object types.
+ */
+export function useMergeState(initialState) {
+    const [state, setState] = useState(initialState);
+    const merge = useCallback((patch) => {
+        setState(prev => (Object.assign(Object.assign({}, prev), patch)));
+    }, []);
+    const reset = useCallback(() => setState(initialState), []);
+    return [state, merge, reset];
+}
+// ─── useResetState ────────────────────────────────────────────────────────────
+/**
+ * useState augmented with a reset() function that returns the state to its
+ * initial value without needing to hold a reference to that value.
+ */
+export function useResetState(initialValue) {
+    const initial = useRef(initialValue);
+    const [state, setState] = useState(initialValue);
+    const reset = useCallback(() => setState(initial.current), []);
+    return [state, setState, reset];
+}
+// ─── useSyncedState ───────────────────────────────────────────────────────────
+/**
+ * State that stays in sync across browser tabs/windows via the BroadcastChannel API.
+ * Falls back to a regular useState when BroadcastChannel is unavailable.
+ */
+export function useSyncedState(channel, initialValue) {
+    const [state, setState] = useState(initialValue);
+    const channelRef = useRef(null);
+    useEffect(() => {
+        if (typeof BroadcastChannel === 'undefined')
+            return;
+        const bc = new BroadcastChannel(channel);
+        channelRef.current = bc;
+        bc.onmessage = (e) => setState(e.data);
+        return () => bc.close();
+    }, [channel]);
+    const set = useCallback((value) => {
+        var _a;
+        setState(value);
+        (_a = channelRef.current) === null || _a === void 0 ? void 0 : _a.postMessage(value);
+    }, []);
+    return [state, set];
+}
+// ─── useDerivedState ──────────────────────────────────────────────────────────
+/**
+ * Derives a value from a source value using a transform function.
+ * Re-computes only when the source changes (same as useMemo but with a
+ * clearer "derive from source" intent).
+ */
+export function useDerivedState(source, transform, deps) {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    return useMemo(() => transform(source), deps !== null && deps !== void 0 ? deps : [source]);
+}
+// ─── usePatch ─────────────────────────────────────────────────────────────────
+/**
+ * State with a patch() method that does a deep-partial update (one level).
+ * Useful for updating nested config/settings objects.
+ */
+export function usePatch(initialState) {
+    const initial = useRef(initialState);
+    const [state, set] = useState(initialState);
+    const patch = useCallback((partial) => set(prev => (Object.assign(Object.assign({}, prev), partial))), []);
+    const reset = useCallback(() => set(initial.current), []);
+    return { state, patch, set, reset };
+}
+// ─── useConstant ──────────────────────────────────────────────────────────────
+/**
+ * Evaluates an initializer function exactly once (on mount) and returns the
+ * result for the lifetime of the component. Unlike useMemo, this is guaranteed
+ * never to be re-computed.
+ */
+export function useConstant(init) {
+    const ref = useRef(null);
+    if (ref.current === null) {
+        ref.current = { value: init() };
+    }
+    return ref.current.value;
+}
+// ─── useComputed ──────────────────────────────────────────────────────────────
+/**
+ * Memoizes a computed value with explicit dependencies.
+ * A semantic alias for useMemo that makes the "compute" intent clearer.
+ */
+export function useComputed(compute, deps) {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    return useMemo(compute, deps);
+}
+// ─── useStableCallback ────────────────────────────────────────────────────────
+/**
+ * Returns a stable function reference that always delegates to the latest
+ * version of the provided callback. A semantic alias for useEventCallback —
+ * safe to pass to event listeners without causing re-subscriptions.
+ */
+export function useStableCallback(fn) {
+    const ref = useRef(fn);
+    useEffect(() => { ref.current = fn; });
+    return useCallback((...args) => ref.current(...args), []);
+}
+// ─── useRenderCount ───────────────────────────────────────────────────────────
+/**
+ * Returns the number of times the component has rendered.
+ * Starts at 1 (the initial render). Useful for debugging performance.
+ */
+export function useRenderCount() {
+    const count = useRef(0);
+    count.current += 1;
+    return count.current;
+}
+// ─── useDeepCompare ───────────────────────────────────────────────────────────
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (typeof a === 'object') {
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        if (keysA.length !== keysB.length)
+            return false;
+        return keysA.every(k => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/**
+ * Like useEffect but uses deep equality to compare deps instead of reference equality.
+ * Prevents spurious re-runs when object/array deps are recreated with the same values.
+ */
+export function useDeepCompareEffect(effect, deps) {
+    const ref = useRef(undefined);
+    if (!deepEqual(ref.current, deps)) {
+        ref.current = deps;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    useEffect(effect, [ref.current]);
+}
+/**
+ * Like useMemo but uses deep equality to compare deps.
+ */
+export function useDeepCompareMemo(factory, deps) {
+    const ref = useRef(undefined);
+    if (!deepEqual(ref.current, deps)) {
+        ref.current = deps;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    return useMemo(factory, [ref.current]);
+}
+// ─── useShallowEqual ──────────────────────────────────────────────────────────
+function shallowEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    if (a === null || b === null)
+        return false;
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every(k => a[k] === b[k]);
+}
+/**
+ * Returns true when the value is shallowly equal to the previous render's value.
+ * Returns the previous (stable) reference when equal so downstream memos don't break.
+ */
+export function useShallowEqual(value) {
+    const ref = useRef(value);
+    if (!shallowEqual(ref.current, value)) {
+        ref.current = value;
+    }
+    return ref.current;
+}
+/**
+ * Imperative error-boundary hook. Call showBoundary(error) to surface an error
+ * to the nearest React error boundary. Call resetError() to clear it.
+ * Pair with an <ErrorBoundary> component in the tree.
+ */
+export function useErrorBoundary() {
+    const [error, setError] = useState(null);
+    // Re-throw during render so the nearest ErrorBoundary catches it
+    if (error)
+        throw error;
+    const showBoundary = useCallback((err) => setError(err), []);
+    const resetError = useCallback(() => setError(null), []);
+    return { error, resetError, showBoundary };
+}
+// ─── useReducerLogger ─────────────────────────────────────────────────────────
+/**
+ * Wraps useReducer to log every dispatched action and resulting state to the
+ * console in development mode. Zero overhead in production.
+ */
+export function useReducerLogger(reducer, initialState) {
+    const wrappedReducer = useCallback((state, action) => {
+        const nextState = reducer(state, action);
+        if (process.env.NODE_ENV !== 'production') {
+            console.groupCollapsed(`[useReducerLogger] action:`, action);
+            console.log('prev state:', state);
+            console.log('next state:', nextState);
+            console.groupEnd();
+        }
+        return nextState;
+    }, [reducer]);
+    return useReducer(wrappedReducer, initialState);
+}

package/dist/chunk1516/chunk1920.d.ts

@@ -0,0 +1,104 @@
+interface UsePaginationOptions {
+    total: number;
+    pageSize?: number;
+    initialPage?: number;
+}
+interface UsePaginationReturn {
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    offset: number;
+    isFirstPage: boolean;
+    isLastPage: boolean;
+    next: () => void;
+    prev: () => void;
+    goTo: (page: number) => void;
+    setPageSize: (size: number) => void;
+}
+/**
+ * Manages client-side pagination state: current page, page size, total pages,
+ * and navigation helpers.
+ */
+export declare function usePagination(options: UsePaginationOptions): UsePaginationReturn;
+interface UsePollingOptions {
+    interval?: number;
+    immediate?: boolean;
+    enabled?: boolean;
+}
+interface UsePollingReturn<T> {
+    data: T | null;
+    error: Error | null;
+    loading: boolean;
+    start: () => void;
+    stop: () => void;
+    isPolling: boolean;
+}
+/**
+ * Repeatedly calls an async function on a fixed interval.
+ * Returns the latest data/error and start/stop controls.
+ */
+export declare function usePolling<T>(fetcher: () => Promise<T>, options?: UsePollingOptions): UsePollingReturn<T>;
+interface UseAbortFetchReturn<T> {
+    data: T | null;
+    error: Error | null;
+    loading: boolean;
+    abort: () => void;
+    refetch: () => void;
+}
+/**
+ * Fetches a URL with an AbortController so in-flight requests are automatically
+ * cancelled on unmount or when the URL changes.
+ */
+export declare function useAbortFetch<T>(url: string, options?: RequestInit): UseAbortFetchReturn<T>;
+interface UseLazyFetchReturn<T> {
+    data: T | null;
+    error: Error | null;
+    loading: boolean;
+    fetch: (url: string, options?: RequestInit) => Promise<void>;
+    reset: () => void;
+}
+/**
+ * A fetch hook that does NOT run on mount. Call the returned fetch() function
+ * to trigger a request imperatively (e.g. on button click).
+ */
+export declare function useLazyFetch<T>(): UseLazyFetchReturn<T>;
+interface UseOptimisticUpdateReturn<T> {
+    data: T;
+    isPending: boolean;
+    error: Error | null;
+    update: (optimisticValue: T, action: () => Promise<T>) => Promise<void>;
+    rollback: () => void;
+}
+/**
+ * Applies an optimistic value immediately while an async action runs.
+ * Rolls back to the previous value on error.
+ */
+export declare function useOptimisticUpdate<T>(initialData: T): UseOptimisticUpdateReturn<T>;
+interface UseStopwatchReturn {
+    elapsedMs: number;
+    isRunning: boolean;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+    lap: () => number;
+    laps: number[];
+}
+/**
+ * A stopwatch that tracks elapsed milliseconds with start/stop/reset/lap controls.
+ */
+export declare function useStopwatch(): UseStopwatchReturn;
+interface UseIdleCallbackOptions {
+    timeout?: number;
+    immediate?: boolean;
+}
+/**
+ * Schedules a callback with requestIdleCallback, falling back to setTimeout
+ * in environments that don't support it (e.g. Safari).
+ */
+export declare function useIdleCallback(callback: () => void, options?: UseIdleCallbackOptions): void;
+/**
+ * useEffect wrapper that accepts an async function and handles cleanup safely.
+ * The async function receives an isCancelled() check to guard async operations.
+ */
+export declare function useAsyncEffect(effect: (isCancelled: () => boolean) => Promise<void | (() => void)>, deps?: React.DependencyList): void;
+export {};