@aweebit/react-essentials 0.6.0 → 0.8.0

package/dist/misc/createSafeContext.d.ts

@@ -6,7 +6,8 @@ import type { ArgumentFallback } from '../utils.js';
  * as an argument to `useContext` or `use` (the hook produced with
  * {@linkcode createSafeContext} should be used instead)
  *
- * @see {@linkcode createSafeContext}
+ * @see
+ * {@linkcode createSafeContext}
  */
 export type RestrictedContext<T> = Context<T> extends Provider<T> ? {
     Provider: Provider<T>;
@@ -16,7 +17,11 @@ export type RestrictedContext<T> = Context<T> extends Provider<T> ? {
     displayName: string;
 };
 /**
- * @see {@linkcode createSafeContext}
+ * The return type of {@linkcode createSafeContext}
+ *
+ * @see
+ * {@linkcode createSafeContext},
+ * {@linkcode RestrictedContext}
  */
 export type SafeContext<DisplayName extends string, T> = {
     [K in `${DisplayName}Context`]: RestrictedContext<T>;
@@ -28,25 +33,59 @@ export type SafeContext<DisplayName extends string, T> = {
  * type and a hook that returns the current context value if one was provided,
  * or throws an error otherwise
  *
+ * The advantages over vanilla `createContext` are that no default value has to
+ * be provided, and that a meaningful context name is displayed in dev tools
+ * instead of generic `Context.Provider`.
+ *
  * @example
  * ```tsx
- * const { ItemsContext, useItems } = createSafeContext<string[]>()('Items');
+ * enum Direction {
+ *   Up,
+ *   Down,
+ *   Left,
+ *   Right,
+ * }
+ *
+ * // Before
+ * const DirectionContext = createContext<Direction | undefined>(undefined);
+ * DirectionContext.displayName = 'DirectionContext';
+ *
+ * const useDirection = () => {
+ *   const direction = useContext(DirectionContext);
+ *   if (direction === undefined) {
+ *     // Called outside of a <DirectionContext.Provider> boundary!
+ *     // Or maybe undefined was explicitly provided as the context value
+ *     // (ideally that shouldn't be allowed, but it is because we had to include
+ *     // undefined in the context type so as to provide a meaningful default)
+ *     throw new Error('No DirectionContext value was provided');
+ *   }
+ *   // Thanks to the undefined check, the type is now narrowed down to Direction
+ *   return direction;
+ * };
+ *
+ * // After
+ * const { DirectionContext, useDirection } =
+ *   createSafeContext<Direction>()('Direction'); // That's it :)
  *
  * const Parent = () => (
- *   <ItemsContext value={['compass', 'newspaper', 'banana']}>
+ *   // Providing undefined as the value is not allowed 👍
+ *   <Direction.Provider value={Direction.Up}>
  *     <Child />
- *   </ItemsContext>
+ *   </Direction.Provider>
  * );
  *
- * const Child = () => useItems().join(', ');
+ * const Child = () => `Current direction: ${Direction[useDirection()]}`;
  * ```
  *
  * @returns
  * A function that accepts a single string argument `displayName` (e.g.
- * `"Items"`) and returns an object with the following properties:
- * - ``` `${displayName}Context` ``` (e.g. `ItemsContext`): the context
- * - ``` `use${displayName}` ``` (e.g. `useItems`): a hook that returns the
+ * `"Direction"`) and returns an object with the following properties:
+ * - ``` `${displayName}Context` ``` (e.g. `DirectionContext`): the context
+ * - ``` `use${displayName}` ``` (e.g. `useDirection`): a hook that returns the
  *   current context value if one was provided, or throws an error otherwise
+ *
+ * @see
+ * {@linkcode SafeContext}
  */
 export declare function createSafeContext<T = never>(): <DisplayName extends string>(displayName: [T] extends [never] ? never : ArgumentFallback<DisplayName, never, string>) => SafeContext<DisplayName, T>;
 //# sourceMappingURL=createSafeContext.d.ts.map

package/dist/misc/createSafeContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createSafeContext.d.ts","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAA6B,MAAM,OAAO,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;;;GAOG;AAIH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC7B,OAAO,CAAC,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,GAC1B;IAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,GAC5D;IAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,WAAW,SAAS,MAAM,EAAE,CAAC,IAAI;KACtD,CAAC,IAAI,GAAG,WAAW,SAAS,GAAG,iBAAiB,CAAC,CAAC,CAAC;CACrD,GAAG;KACD,CAAC,IAAI,MAAM,WAAW,EAAE,GAAG,MAAM,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,KAAK,MACjC,WAAW,SAAS,MAAM,EAChC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC5B,KAAK,GACL,gBAAgB,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,KAC/C,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAsB/B"}
+{"version":3,"file":"createSafeContext.d.ts","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAA6B,MAAM,OAAO,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;;;;;;GAQG;AAIH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC7B,OAAO,CAAC,CAAC,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,GAC1B;IAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,GAC5D;IAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,WAAW,SAAS,MAAM,EAAE,CAAC,IAAI;KACtD,CAAC,IAAI,GAAG,WAAW,SAAS,GAAG,iBAAiB,CAAC,CAAC,CAAC;CACrD,GAAG;KACD,CAAC,IAAI,MAAM,WAAW,EAAE,GAAG,MAAM,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,KAAK,MACjC,WAAW,SAAS,MAAM,EAChC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAC5B,KAAK,GACL,gBAAgB,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,CAAC,KAC/C,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAsB/B"}

package/dist/misc/createSafeContext.js

@@ -5,25 +5,59 @@ const moValueSymbol = Symbol('noValue');
  * type and a hook that returns the current context value if one was provided,
  * or throws an error otherwise
  *
+ * The advantages over vanilla `createContext` are that no default value has to
+ * be provided, and that a meaningful context name is displayed in dev tools
+ * instead of generic `Context.Provider`.
+ *
  * @example
  * ```tsx
- * const { ItemsContext, useItems } = createSafeContext<string[]>()('Items');
+ * enum Direction {
+ *   Up,
+ *   Down,
+ *   Left,
+ *   Right,
+ * }
+ *
+ * // Before
+ * const DirectionContext = createContext<Direction | undefined>(undefined);
+ * DirectionContext.displayName = 'DirectionContext';
+ *
+ * const useDirection = () => {
+ *   const direction = useContext(DirectionContext);
+ *   if (direction === undefined) {
+ *     // Called outside of a <DirectionContext.Provider> boundary!
+ *     // Or maybe undefined was explicitly provided as the context value
+ *     // (ideally that shouldn't be allowed, but it is because we had to include
+ *     // undefined in the context type so as to provide a meaningful default)
+ *     throw new Error('No DirectionContext value was provided');
+ *   }
+ *   // Thanks to the undefined check, the type is now narrowed down to Direction
+ *   return direction;
+ * };
+ *
+ * // After
+ * const { DirectionContext, useDirection } =
+ *   createSafeContext<Direction>()('Direction'); // That's it :)
  *
  * const Parent = () => (
- *   <ItemsContext value={['compass', 'newspaper', 'banana']}>
+ *   // Providing undefined as the value is not allowed 👍
+ *   <Direction.Provider value={Direction.Up}>
  *     <Child />
- *   </ItemsContext>
+ *   </Direction.Provider>
  * );
  *
- * const Child = () => useItems().join(', ');
+ * const Child = () => `Current direction: ${Direction[useDirection()]}`;
  * ```
  *
  * @returns
  * A function that accepts a single string argument `displayName` (e.g.
- * `"Items"`) and returns an object with the following properties:
- * - ``` `${displayName}Context` ``` (e.g. `ItemsContext`): the context
- * - ``` `use${displayName}` ``` (e.g. `useItems`): a hook that returns the
+ * `"Direction"`) and returns an object with the following properties:
+ * - ``` `${displayName}Context` ``` (e.g. `DirectionContext`): the context
+ * - ``` `use${displayName}` ``` (e.g. `useDirection`): a hook that returns the
  *   current context value if one was provided, or throws an error otherwise
+ *
+ * @see
+ * {@linkcode SafeContext}
  */
 export function createSafeContext() {
     return (displayName) => {

package/dist/misc/createSafeContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"createSafeContext.js","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAG/E,MAAM,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AA2BxC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,WAEgD,EACnB,EAAE;QAC/B,MAAM,WAAW,GAAG,GAAG,WAA0B,SAAkB,CAAC;QACpE,MAAM,QAAQ,GAAG,MAAM,WAA0B,EAAW,CAAC;QAE7D,MAAM,OAAO,GAAG,aAAa,CAA2B,aAAa,CAAC,CAAC;QACvE,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;QAElC,OAAO;YACL,CAAC,WAAW,CAAC,EAAE,OAA+B;YAC9C,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE;gBACf,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;gBAClC,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;oBAC5B,MAAM,IAAI,KAAK,CAAC,MAAM,WAAW,qBAAqB,CAAC,CAAC;gBAC1D,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;SAKF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"createSafeContext.js","sourceRoot":"","sources":["../../src/misc/createSafeContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAG/E,MAAM,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AAgCxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CACL,WAEgD,EACnB,EAAE;QAC/B,MAAM,WAAW,GAAG,GAAG,WAA0B,SAAkB,CAAC;QACpE,MAAM,QAAQ,GAAG,MAAM,WAA0B,EAAW,CAAC;QAE7D,MAAM,OAAO,GAAG,aAAa,CAA2B,aAAa,CAAC,CAAC;QACvE,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;QAElC,OAAO;YACL,CAAC,WAAW,CAAC,EAAE,OAA+B;YAC9C,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE;gBACf,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;gBAClC,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;oBAC5B,MAAM,IAAI,KAAK,CAAC,MAAM,WAAW,qBAAqB,CAAC,CAAC;gBAC1D,CAAC;gBACD,OAAO,KAAK,CAAC;YACf,CAAC;SAKF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aweebit/react-essentials",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "repository": "github:aweebit/react-essentials",
   "main": "dist/index.js",

package/src/hooks/useEventListener.ts

@@ -5,101 +5,113 @@
  * @copyright 2020 Julien CARON
  */
 
-import { useEffect, useMemo, useRef } from 'react';
+import { useEffect, useMemo, useRef, type RefObject } from 'react';
 
 /**
- * Adds `handler` as a listener for the event `eventName` of `element` with the
- * provided `options` applied
- *
- * If `element` is `undefined`, `window` is used instead.
- *
- * If `element` is `null`, no event listener is added.
- *
- * @example
- * ```tsx
- * useEventListener('resize', () => {
- *   console.log(window.innerWidth, window.innerHeight);
- * });
- *
- * useEventListener(
- *   'visibilitychange',
- *   () => console.log(document.visibilityState),
- *   document
- * );
- *
- * const buttonRef = useRef<HTMLButtonElement>(null);
- * useEventListener("click", () => console.log("click"), buttonRef.current);
- * ```
+ * The type of {@linkcode useEventListener}
  *
- * @ignore
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithImplicitWindowTarget},
+ * {@linkcode UseEventListenerWithExplicitTarget},
+ * {@linkcode UseEventListenerWithAnyExplicitTarget}
  */
-export function useEventListener<
-  K extends keyof HTMLElementEventMap,
-  T extends HTMLElement,
+export type UseEventListener = UseEventListenerWithImplicitWindowTarget &
+  UseEventListenerWithExplicitTarget<Window, WindowEventMap> &
+  UseEventListenerWithExplicitTarget<Document, DocumentEventMap> &
+  UseEventListenerWithExplicitTarget<HTMLElement, HTMLElementEventMap> &
+  UseEventListenerWithExplicitTarget<SVGElement, SVGElementEventMap> &
+  UseEventListenerWithExplicitTarget<MathMLElement, MathMLElementEventMap> &
+  UseEventListenerWithAnyExplicitTarget;
+
+/**
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithImplicitWindowTargetArgs} */
+export type UseEventListenerWithImplicitWindowTarget = <
+  K extends keyof WindowEventMap,
 >(
-  eventName: K,
-  handler: (this: NoInfer<T>, event: HTMLElementEventMap[K]) => void,
-  element: T | null,
-  options?: boolean | AddEventListenerOptions,
-): void;
+  ...args: UseEventListenerWithImplicitWindowTargetArgs<K>
+) => void;
 
 /**
- * @see {@linkcode useEventListener}
- * @ignore
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithExplicitTargetArgs}
  */
-export function useEventListener<
-  K extends keyof SVGElementEventMap,
-  T extends SVGElement,
->(
-  eventName: K,
-  handler: (this: NoInfer<T>, event: SVGElementEventMap[K]) => void,
-  element: T | null,
-  options?: boolean | AddEventListenerOptions,
-): void;
+export type UseEventListenerWithExplicitTarget<
+  Target extends EventTarget,
+  EventMap = Record<string, Event>,
+> = <T extends Target, K extends keyof EventMap>(
+  ...args: UseEventListenerWithExplicitTargetArgs<EventMap, T, K>
+) => void;
 
 /**
- * @see {@linkcode useEventListener}
- * @ignore
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithExplicitTarget}
  */
-export function useEventListener<
-  K extends keyof MathMLElementEventMap,
-  T extends MathMLElement,
->(
-  eventName: K,
-  handler: (this: NoInfer<T>, event: MathMLElementEventMap[K]) => void,
-  element: T | null,
-  options?: boolean | AddEventListenerOptions,
-): void;
+export type UseEventListenerWithAnyExplicitTarget =
+  UseEventListenerWithExplicitTarget<EventTarget>;
 
 /**
- * @see {@linkcode useEventListener}
- * @ignore
+ * @see
+ * {@linkcode useEventListener},
+ * {@linkcode UseEventListenerWithExplicitTargetArgs}
  */
-export function useEventListener<K extends keyof DocumentEventMap>(
-  eventName: K,
-  handler: (this: Document, event: DocumentEventMap[K]) => void,
-  element: Document,
-  options?: boolean | AddEventListenerOptions,
-): void;
+export type UseEventListenerWithImplicitWindowTargetArgs<
+  K extends keyof WindowEventMap,
+> =
+  UseEventListenerWithExplicitTargetArgs<WindowEventMap, Window, K> extends [
+    unknown,
+    ...infer Args,
+  ]
+    ? Args
+    : never;
 
 /**
- * @see {@linkcode useEventListener}
- * @ignore
+ * @see
+ * {@linkcode useEventListener}
  */
-export function useEventListener<K extends keyof WindowEventMap>(
+export type UseEventListenerWithExplicitTargetArgs<
+  EventMap,
+  T extends EventTarget,
+  K extends keyof EventMap,
+> = [
+  target: T | (RefObject<T> & { addEventListener?: never }) | null,
   eventName: K,
-  handler: (this: Window, event: WindowEventMap[K]) => void,
-  element?: Window,
-  options?: boolean | AddEventListenerOptions,
-): void;
+  handler: (this: NoInfer<T>, event: EventMap[K]) => void,
+  options?: AddEventListenerOptions | boolean | undefined,
+];
+
+type UseEventListenerWithImplicitWindowTargetArgsAny =
+  UseEventListenerWithImplicitWindowTargetArgs<keyof WindowEventMap>;
+
+type UseEventListenerWithExplicitTargetArgsAny =
+  UseEventListenerWithExplicitTargetArgs<
+    Record<string, Event>,
+    EventTarget,
+    string
+  >;
 
 /**
- * Adds `handler` as a listener for the event `eventName` of `element` with the
+ * Adds `handler` as a listener for the event `eventName` of `target` with the
  * provided `options` applied
  *
- * If `element` is `undefined`, `window` is used instead.
+ * The following call signatures are available:
+ *
+ * ```ts
+ * function useEventListener(eventName, handler, options?): void;
+ * function useEventListener(target, eventName, handler, options?): void;
+ * ```
+ *
+ * For the full definition of the hook's type, see {@linkcode UseEventListener}.
  *
- * If `element` is `null`, no event listener is added.
+ * If `target` is not provided, `window` is used instead.
+ *
+ * If `target` is `null`, no event listener is added. This is useful when
+ * working with DOM element refs, or when the event listener needs to be removed
+ * temporarily.
  *
  * @example
  * ```tsx
@@ -107,29 +119,35 @@ export function useEventListener<K extends keyof WindowEventMap>(
  *   console.log(window.innerWidth, window.innerHeight);
  * });
  *
- * useEventListener(
- *   'visibilitychange',
- *   () => console.log(document.visibilityState),
- *   document
- * );
+ * useEventListener(document, 'visibilitychange', () => {
+ *   console.log(document.visibilityState);
+ * });
  *
  * const buttonRef = useRef<HTMLButtonElement>(null);
- * useEventListener("click", () => console.log("click"), buttonRef.current);
+ * useEventListener(buttonRef, 'click', () => console.log('click'));
  * ```
+ *
+ * @see
+ * {@linkcode UseEventListener}
  */
-export function useEventListener<T extends EventTarget>(
-  eventName: string,
-  handler: (this: NoInfer<T>, event: Event) => void,
-  element?: T | null,
-  options?: boolean | AddEventListenerOptions,
-): void;
-
-export function useEventListener(
-  eventName: string,
-  handler: (this: EventTarget, event: Event) => void,
-  element?: EventTarget | null,
-  options?: boolean | AddEventListenerOptions,
+export const useEventListener: UseEventListener = function useEventListener(
+  ...args:
+    | UseEventListenerWithImplicitWindowTargetArgsAny
+    | UseEventListenerWithExplicitTargetArgsAny
 ) {
+  const [target, eventName, handler, options]: [
+    target: EventTarget | RefObject<EventTarget> | null,
+    eventName: string,
+    handler: (this: never, event: Event) => void,
+    options?: AddEventListenerOptions | boolean | undefined,
+  ] =
+    typeof args[0] === 'string'
+      ? [window, ...(args as UseEventListenerWithImplicitWindowTargetArgsAny)]
+      : (args as UseEventListenerWithExplicitTargetArgsAny);
+
+  const unwrappedTarget =
+    target && !('addEventListener' in target) ? target.current : target;
+
   const handlerRef = useRef(handler);
   handlerRef.current = handler;
 
@@ -147,24 +165,19 @@ export function useEventListener(
   );
 
   useEffect(() => {
-    if (element === null) {
+    if (unwrappedTarget === null) {
       // No element has been attached to the ref yet
       return;
     }
 
-    // Define the listening target
-    const targetElement = element ?? window;
-
-    // Create event listener that calls handler function stored in ref
     const listener: typeof handler = function (event) {
       handlerRef.current.call(this, event);
     };
 
-    targetElement.addEventListener(eventName, listener, memoizedOptions);
+    unwrappedTarget.addEventListener(eventName, listener, memoizedOptions);
 
-    // Remove event listener on cleanup
     return () => {
-      targetElement.removeEventListener(eventName, listener, memoizedOptions);
+      unwrappedTarget.removeEventListener(eventName, listener, memoizedOptions);
     };
-  }, [eventName, element, memoizedOptions]);
-}
+  }, [unwrappedTarget, eventName, memoizedOptions]);
+} as UseEventListener;

package/src/hooks/useForceUpdate.ts

@@ -11,6 +11,55 @@ import type { useReducerWithDeps } from './useReducerWithDeps.js';
  * This hook is designed in the most general way possible in order to cover all
  * imaginable use cases.
  *
+ * @example
+ * Sometimes, React's immutability constraints mean too much unnecessary copying
+ * of data when new data arrives at a high frequency. In such cases, it might be
+ * desirable to ignore the constraints by embracing imperative patterns.
+ * Here is an example of a scenario where that can make sense:
+ *
+ * ```tsx
+ * type SensorData = { timestamp: number; value: number };
+ * const sensorDataRef = useRef<SensorData[]>([]);
+ * const mostRecentSensorDataTimestampRef = useRef<number>(0);
+ *
+ * const [forceUpdate, updateCount] = useForceUpdate();
+ * // Limiting the frequency of forced re-renders with some throttle function:
+ * const throttledForceUpdateRef = useRef(throttle(forceUpdate));
+ *
+ * useEffect(() => {
+ *   return sensorDataObservable.subscribe((data: SensorData) => {
+ *     // Imagine new sensor data arrives every 1 millisecond. If we were following
+ *     // React's immutability rules by creating a new array every time, the data
+ *     // that's already there would have to be copied many times before the new
+ *     // data would even get a chance to be reflected in the UI for the first time
+ *     // because it typically takes much longer than 1 millisecond for a new frame
+ *     // to be displayed. To prevent the waste of computational resources, we just
+ *     // mutate the existing array every time instead:
+ *     sensorDataRef.current.push(data);
+ *     if (data.timestamp > mostRecentSensorDataTimestampRef.current) {
+ *       mostRecentSensorDataTimestampRef.current = data.timestamp;
+ *     }
+ *     throttledForceUpdateRef.current();
+ *   });
+ * }, []);
+ *
+ * const [timeWindow, setTimeWindow] = useState(1000);
+ * const selectedSensorData = useMemo(
+ *   () => {
+ *     // Keep this line if you don't want to disable the
+ *     // react-hooks/exhaustive-deps ESLint rule:
+ *     updateCount;
+ *     const threshold = mostRecentSensorDataTimestampRef.current - timeWindow;
+ *     return sensorDataRef.current.filter(
+ *       ({ timestamp }) => timestamp >= threshold,
+ *     );
+ *   },
+ *   // sensorDataRef.current always references the same array, so listing it as a
+ *   // dependency is pointless. Instead, updateCount should be used:
+ *   [updateCount, timeWindow],
+ * );
+ * ```
+ *
  * @param callback An optional callback function to call during renders that
  * were triggered with `forceUpdate()`
  *
@@ -32,11 +81,11 @@ import type { useReducerWithDeps } from './useReducerWithDeps.js';
 export function useForceUpdate(callback?: () => void): [() => void, bigint] {
   // It is very unlikely that the number of updates will exceed
   // Number.MAX_SAFE_INTEGER, but not impossible. That is why we use bigints.
-  const [counter, forceUpdate] = useReducer((prev) => prev + 1n, 0n);
-  const counterRef = useRef(counter);
-  if (counter !== counterRef.current) {
-    counterRef.current = counter;
+  const [updateCount, forceUpdate] = useReducer((prev) => prev + 1n, 0n);
+  const updateCountRef = useRef(updateCount);
+  if (updateCount !== updateCountRef.current) {
+    updateCountRef.current = updateCount;
     callback?.();
   }
-  return [forceUpdate, counter];
+  return [forceUpdate, updateCount];
 }

package/src/hooks/useReducerWithDeps.ts

@@ -1,4 +1,4 @@
-import { type DependencyList, useCallback, useRef } from 'react';
+import { type DependencyList, useRef } from 'react';
 import { useStateWithDeps } from './useStateWithDeps.js';
 
 // We cannot simply import the following types from @types/react since they are
@@ -18,6 +18,9 @@ export type ActionDispatch<ActionArg extends AnyActionArg> = (
  * `useReducer` hook with an additional dependency array `deps` that resets the
  * state to `initialState` when dependencies change
  *
+ * For motivation and examples, see
+ * https://github.com/facebook/react/issues/33041.
+ *
  * ### On linter support
  *
  * The `react-hooks/exhaustive-deps` ESLint rule doesn't support hooks where
@@ -26,7 +29,7 @@ export type ActionDispatch<ActionArg extends AnyActionArg> = (
  * possible, we don't want to artificially change the parameter's position.
  * Therefore, there will be no warnings about missing dependencies.
  * Because of that, additional caution is advised!
- * Be sure to check no dependencies are missing from the `deps` array.
+ * Be sure to check that no dependencies are missing from the `deps` array.
  *
  * Related issue: {@link https://github.com/facebook/react/issues/25443}.
  *
@@ -57,9 +60,9 @@ export function useReducerWithDeps<S, A extends AnyActionArg>(
   // Only the initially provided reducer is used
   const reducerRef = useRef(reducer);
 
-  const dispatch = useCallback(function dispatch(...args: A): void {
+  const dispatch = useRef(function dispatch(...args: A): void {
     setState((previousState) => reducerRef.current(previousState, ...args));
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  }).current;
 
   return [state, dispatch];
 }

package/src/hooks/useStateWithDeps.ts

@@ -6,7 +6,6 @@
  */
 
 import {
-  useCallback,
   useRef,
   type DependencyList,
   type Dispatch,
@@ -19,6 +18,41 @@ import { useForceUpdate } from './useForceUpdate.js';
  * `useState` hook with an additional dependency array `deps` that resets the
  * state to `initialState` when dependencies change
  *
+ * For motivation and more examples, see
+ * https://github.com/facebook/react/issues/33041.
+ *
+ * @example
+ * ```tsx
+ * type Activity = 'breakfast' | 'exercise' | 'swim' | 'board games' | 'dinner';
+ *
+ * const timeOfDayOptions = ['morning', 'afternoon', 'evening'] as const;
+ * type TimeOfDay = (typeof timeOfDayOptions)[number];
+ *
+ * const activityOptionsByTimeOfDay: {
+ *   [K in TimeOfDay]: [Activity, ...Activity[]];
+ * } = {
+ *   morning: ['breakfast', 'exercise', 'swim'],
+ *   afternoon: ['exercise', 'swim', 'board games'],
+ *   evening: ['board games', 'dinner'],
+ * };
+ *
+ * export function Example() {
+ *   const [timeOfDay, setTimeOfDay] = useState<TimeOfDay>('morning');
+ *
+ *   const activityOptions = activityOptionsByTimeOfDay[timeOfDay];
+ *   const [activity, setActivity] = useStateWithDeps<Activity>(
+ *     (prev) => {
+ *       // Make sure activity is always valid for the current timeOfDay value,
+ *       // but also don't reset it unless necessary:
+ *       return prev && activityOptions.includes(prev) ? prev : activityOptions[0];
+ *     },
+ *     [activityOptions],
+ *   );
+ *
+ *   return '...';
+ * }
+ * ```
+ *
  * @param initialState The value to which the state is set when the component is
  * mounted or dependencies change
  *
@@ -32,12 +66,10 @@ export function useStateWithDeps<S>(
   initialState: S | ((previousState?: S) => S),
   deps: DependencyList,
 ): [S, Dispatch<SetStateAction<S>>] {
-  // It would be possible to use useState instead of
-  // useRef to store the state, however this would
-  // trigger re-renders whenever the state is reset due
-  // to a change in dependencies. In order to avoid these
-  // re-renders, the state is stored in a ref and an
-  // update is triggered via forceUpdate below when necessary
+  // It would be possible to use useState instead of useRef to store the state,
+  // however this would trigger re-renders whenever the state is reset due to a
+  // change in dependencies. In order to avoid these re-renders, the state is
+  // stored in a ref, and updates are triggered with forceUpdate when necessary.
   const state = useRef(undefined as S);
 
   const prevDeps = useRef(deps);
@@ -59,7 +91,7 @@ export function useStateWithDeps<S>(
 
   const [forceUpdate] = useForceUpdate();
 
-  const updateState = useCallback(function updateState(
+  const updateState = useRef(function updateState(
     newState: S | ((previousState: S) => S),
   ): void {
     let nextState: S;
@@ -72,7 +104,7 @@ export function useStateWithDeps<S>(
       state.current = nextState;
       forceUpdate();
     }
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  }).current;
 
   return [state.current, updateState];
 }