@aweebit/react-essentials 0.4.0 → 0.5.0

package/dist/hooks/useEventListener.d.ts

@@ -25,7 +25,7 @@
  */
 /**
  * Adds `handler` as a listener for the event `eventName` of `element`
- * (or `window` by default) with the provided `options` applied.
+ * (or `window` by default) with the provided `options` applied
  *
  * It is the user's responsibility to make sure `element` and `options` values
  * are correctly memoized!

package/dist/hooks/useEventListener.js

@@ -45,3 +45,4 @@ function useEventListener(eventName, handler, element, options) {
     }, [eventName, element, options]);
 }
 export default useEventListener;
+//# sourceMappingURL=useEventListener.js.map

package/dist/hooks/useEventListener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEventListener.js","sourceRoot":"","sources":["../../lib/hooks/useEventListener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAgD3D,SAAS,gBAAgB,CACvB,SAAiB,EACjB,OAA+B,EAC/B,OAAqB,EACrB,OAA2C;IAE3C,mCAAmC;IACnC,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAErC,eAAe,CAAC,GAAG,EAAE;QACnB,YAAY,CAAC,OAAO,GAAG,OAAO,CAAC;IACjC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAEd,SAAS,CAAC,GAAG,EAAE;QACb,8BAA8B;QAC9B,MAAM,aAAa,GAAG,OAAO,IAAI,MAAM,CAAC;QAExC,kEAAkE;QAClE,MAAM,QAAQ,GAAmB,CAAC,KAAK,EAAE,EAAE;YACzC,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC,CAAC;QAEF,aAAa,CAAC,gBAAgB,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAE7D,mCAAmC;QACnC,OAAO,GAAG,EAAE;YACV,aAAa,CAAC,mBAAmB,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAClE,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,eAAe,gBAAgB,CAAC"}

package/dist/hooks/useForceUpdate.d.ts

@@ -1,5 +1,27 @@
-export default function useForceUpdate(): [
-    () => void,
-    Record<PropertyKey, never>
-];
+/**
+ * Enables you to imperatively trigger re-rendering of components
+ *
+ * This hook is designed in the most general way possible in order to cover all
+ * imaginable use cases.
+ *
+ * @param callback An optional callback function to call during renders that
+ * were triggered with `forceUpdate()`
+ *
+ * Can be used for conditionally calling state setters when state needs to be
+ * reset. That is legal and better than using effects (see
+ * {@link https://react.dev/learn/-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes You Might Not Need an Effect > Adjusting some state when a prop changes}),
+ * but can often be avoided by using
+ * [`useStateWithDeps`]({@link ./useStateWithDeps.ts}) or
+ * [`useReducerWithDeps`]({@link ./useReducerWithDeps.ts}).
+ *
+ * Important: the callback function is called once per render, not once per
+ * `forceUpdate` call! If React batches `forceUpdate` calls, then it will only
+ * be called once.
+ *
+ * @returns An array with the following two elements:
+ *
+ * 1. A `forceUpdate` function that triggers a re-render
+ * 2. The number of times `forceUpdate` has been called so far
+ */
+export default function useForceUpdate(callback?: () => void): [() => void, bigint];
 //# sourceMappingURL=useForceUpdate.d.ts.map

package/dist/hooks/useForceUpdate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useForceUpdate.d.ts","sourceRoot":"","sources":["../../lib/hooks/useForceUpdate.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,UAAU,cAAc,IAAI;IACxC,MAAM,IAAI;IACV,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC;CAC3B,CAGA"}
+{"version":3,"file":"useForceUpdate.d.ts","sourceRoot":"","sources":["../../lib/hooks/useForceUpdate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,QAAQ,CAAC,EAAE,MAAM,IAAI,GACpB,CAAC,MAAM,IAAI,EAAE,MAAM,CAAC,CAUtB"}

package/dist/hooks/useForceUpdate.js

@@ -1,5 +1,38 @@
-import { useReducer } from 'react';
-export default function useForceUpdate() {
-    const [value, forceUpdate] = useReducer(() => ({}), {});
-    return [forceUpdate, value];
+import { useReducer, useRef } from 'react';
+/**
+ * Enables you to imperatively trigger re-rendering of components
+ *
+ * This hook is designed in the most general way possible in order to cover all
+ * imaginable use cases.
+ *
+ * @param callback An optional callback function to call during renders that
+ * were triggered with `forceUpdate()`
+ *
+ * Can be used for conditionally calling state setters when state needs to be
+ * reset. That is legal and better than using effects (see
+ * {@link https://react.dev/learn/-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes You Might Not Need an Effect > Adjusting some state when a prop changes}),
+ * but can often be avoided by using
+ * [`useStateWithDeps`]({@link ./useStateWithDeps.ts}) or
+ * [`useReducerWithDeps`]({@link ./useReducerWithDeps.ts}).
+ *
+ * Important: the callback function is called once per render, not once per
+ * `forceUpdate` call! If React batches `forceUpdate` calls, then it will only
+ * be called once.
+ *
+ * @returns An array with the following two elements:
+ *
+ * 1. A `forceUpdate` function that triggers a re-render
+ * 2. The number of times `forceUpdate` has been called so far
+ */
+export default function useForceUpdate(callback) {
+    // 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;
+        callback?.();
+    }
+    return [forceUpdate, counter];
 }
+//# sourceMappingURL=useForceUpdate.js.map

package/dist/hooks/useForceUpdate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useForceUpdate.js","sourceRoot":"","sources":["../../lib/hooks/useForceUpdate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,QAAqB;IAErB,6DAA6D;IAC7D,2EAA2E;IAC3E,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;IACnE,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,OAAO,KAAK,UAAU,CAAC,OAAO,EAAE,CAAC;QACnC,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;QAC7B,QAAQ,EAAE,EAAE,CAAC;IACf,CAAC;IACD,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AAChC,CAAC"}

package/dist/hooks/useReducerWithDeps.d.ts

@@ -0,0 +1,36 @@
+import { type ActionDispatch, type AnyActionArg, type DependencyList } from 'react';
+/**
+ * `useReducer` hook with an additional dependency array that resets the state
+ * to the `initialState` param when the dependencies passed in the `deps` array
+ * change
+ *
+ * ### On linter support
+ *
+ * The `react-hooks/exhaustive-deps` ESLint rule doesn't support hooks where
+ * the dependency array parameter is at any other position than the second.
+ * However, as we would like to keep the hook as compatible with `useReducer` as
+ * possible, we don't want to artificially change the parameter's position.
+ * Therefore, there will be no warnings about missing dependencies.
+ * Because of that, addition caution is advised!
+ * Be sure to check no dependencies are missing from the `deps` array.
+ *
+ * Related issue: {@link https://github.com/facebook/react/issues/25443}.
+ *
+ * Unlike `eslint-plugin-react-hooks` maintained by React's team, the unofficial
+ * `useExhaustiveDependencies` rule provided for Biome by Biome's team
+ * does actually have support for dependency arrays at other positions, see
+ * {@link https://biomejs.dev/linter/rules/use-exhaustive-dependencies/#validating-dependencies}.
+ *
+ * @param reducer The reducer function that specifies how the state gets updated
+ *
+ * @param initialState The state that will be set when the component mounts or
+ * the dependencies change
+ *
+ * It can also be a function which returns a state value. If the state is reset
+ * due to a change of dependencies, this function will be passed the previous
+ * state as its argument (will be `undefined` in the first call upon mount).
+ *
+ * @param deps Dependencies that reset the state to `initialState`
+ */
+export default function useReducerWithDeps<S, A extends AnyActionArg>(reducer: (prevState: S, ...args: A) => S, initialState: S | ((previousState?: S) => S), deps: DependencyList): [S, ActionDispatch<A>];
+//# sourceMappingURL=useReducerWithDeps.d.ts.map

package/dist/hooks/useReducerWithDeps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useReducerWithDeps.d.ts","sourceRoot":"","sources":["../../lib/hooks/useReducerWithDeps.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,EAGpB,MAAM,OAAO,CAAC;AAGf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,CAAC,EAAE,CAAC,SAAS,YAAY,EAClE,OAAO,EAAE,CAAC,SAAS,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,EACxC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAC5C,IAAI,EAAE,cAAc,GACnB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAYxB"}

package/dist/hooks/useReducerWithDeps.js

@@ -0,0 +1,46 @@
+import { useCallback, useRef, } from 'react';
+import useStateWithDeps from './useStateWithDeps';
+/**
+ * `useReducer` hook with an additional dependency array that resets the state
+ * to the `initialState` param when the dependencies passed in the `deps` array
+ * change
+ *
+ * ### On linter support
+ *
+ * The `react-hooks/exhaustive-deps` ESLint rule doesn't support hooks where
+ * the dependency array parameter is at any other position than the second.
+ * However, as we would like to keep the hook as compatible with `useReducer` as
+ * possible, we don't want to artificially change the parameter's position.
+ * Therefore, there will be no warnings about missing dependencies.
+ * Because of that, addition caution is advised!
+ * Be sure to check no dependencies are missing from the `deps` array.
+ *
+ * Related issue: {@link https://github.com/facebook/react/issues/25443}.
+ *
+ * Unlike `eslint-plugin-react-hooks` maintained by React's team, the unofficial
+ * `useExhaustiveDependencies` rule provided for Biome by Biome's team
+ * does actually have support for dependency arrays at other positions, see
+ * {@link https://biomejs.dev/linter/rules/use-exhaustive-dependencies/#validating-dependencies}.
+ *
+ * @param reducer The reducer function that specifies how the state gets updated
+ *
+ * @param initialState The state that will be set when the component mounts or
+ * the dependencies change
+ *
+ * It can also be a function which returns a state value. If the state is reset
+ * due to a change of dependencies, this function will be passed the previous
+ * state as its argument (will be `undefined` in the first call upon mount).
+ *
+ * @param deps Dependencies that reset the state to `initialState`
+ */
+export default function useReducerWithDeps(reducer, initialState, deps) {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const [state, setState] = useStateWithDeps(initialState, deps);
+    // Only the initially provided reducer is used
+    const reducerRef = useRef(reducer);
+    const dispatch = useCallback(function dispatch(...args) {
+        setState((previousState) => reducerRef.current(previousState, ...args));
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    return [state, dispatch];
+}
+//# sourceMappingURL=useReducerWithDeps.js.map

package/dist/hooks/useReducerWithDeps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useReducerWithDeps.js","sourceRoot":"","sources":["../../lib/hooks/useReducerWithDeps.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,WAAW,EACX,MAAM,GACP,MAAM,OAAO,CAAC;AACf,OAAO,gBAAgB,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CACxC,OAAwC,EACxC,YAA4C,EAC5C,IAAoB;IAEpB,uDAAuD;IACvD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,gBAAgB,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAE/D,8CAA8C;IAC9C,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnC,MAAM,QAAQ,GAAG,WAAW,CAAC,SAAS,QAAQ,CAAC,GAAG,IAAO;QACvD,QAAQ,CAAC,CAAC,aAAa,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IAC1E,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kDAAkD;IAE1D,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC3B,CAAC"}

package/dist/hooks/{useDerivedState.d.ts → useStateWithDeps.d.ts}

@@ -25,18 +25,18 @@
  */
 import { type DependencyList, type Dispatch, type SetStateAction } from 'react';
 /**
- * `useState` hook with an additional dependency array that resets
- * the state to the `initialState` param when the dependencies passed
- * in the `deps` array change.
- *
- * @param initialState
- * The state that will be set when the component mounts or the
- * dependencies change.
- *
- * It can also be a function which resolves to the state. If the state
- * is reset due to a change of dependencies, this function will be called with the previous
- * state (`undefined` for the first call upon mount).
- * @param deps Dependencies for this hook that resets the state to `initialState`
+ * `useState` hook with an additional dependency array that resets the state
+ * to the `initialState` param when the dependencies passed in the `deps` array
+ * change
+ *
+ * @param initialState The state that will be set when the component mounts or
+ * the dependencies change
+ *
+ * It can also be a function which returns a state value. If the state is reset
+ * due to a change of dependencies, this function will be passed the previous
+ * state as its argument (will be `undefined` in the first call upon mount).
+ *
+ * @param deps Dependencies that reset the state to `initialState`
  */
-export default function useDerivedState<S>(initialState: S | ((previousState?: S) => S), deps: DependencyList): [S, Dispatch<SetStateAction<S>>];
-//# sourceMappingURL=useDerivedState.d.ts.map
+export default function useStateWithDeps<S>(initialState: S | ((previousState?: S) => S), deps: DependencyList): [S, Dispatch<SetStateAction<S>>];
+//# sourceMappingURL=useStateWithDeps.d.ts.map

package/dist/hooks/useStateWithDeps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStateWithDeps.d.ts","sourceRoot":"","sources":["../../lib/hooks/useStateWithDeps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAIf;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CAAC,CAAC,EACxC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAC5C,IAAI,EAAE,cAAc,GACnB,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CA4ClC"}

package/dist/hooks/{useDerivedState.js → useStateWithDeps.js}

@@ -27,42 +27,31 @@ import { useCallback, useRef, } from 'react';
 import { depsAreEqual, isFunction } from '../utils';
 import useForceUpdate from './useForceUpdate';
 /**
- * `useState` hook with an additional dependency array that resets
- * the state to the `initialState` param when the dependencies passed
- * in the `deps` array change.
+ * `useState` hook with an additional dependency array that resets the state
+ * to the `initialState` param when the dependencies passed in the `deps` array
+ * change
  *
- * @param initialState
- * The state that will be set when the component mounts or the
- * dependencies change.
+ * @param initialState The state that will be set when the component mounts or
+ * the dependencies change
  *
- * It can also be a function which resolves to the state. If the state
- * is reset due to a change of dependencies, this function will be called with the previous
- * state (`undefined` for the first call upon mount).
- * @param deps Dependencies for this hook that resets the state to `initialState`
+ * It can also be a function which returns a state value. If the state is reset
+ * due to a change of dependencies, this function will be passed the previous
+ * state as its argument (will be `undefined` in the first call upon mount).
+ *
+ * @param deps Dependencies that reset the state to `initialState`
  */
-export default function useDerivedState(initialState, deps) {
-    const isMounted = useRef(false);
-    // Determine initial state
-    let usableInitialState = null;
-    if (!isMounted.current) {
-        isMounted.current = true;
-        if (isFunction(initialState)) {
-            usableInitialState = initialState();
-        }
-        else {
-            usableInitialState = initialState;
-        }
-    }
+export default function useStateWithDeps(initialState, deps) {
     // 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
-    const state = useRef(usableInitialState);
-    // Check if dependencies have changed
+    const state = useRef(undefined);
     const prevDeps = useRef(deps);
-    if (!depsAreEqual(prevDeps.current, deps)) {
+    const isMounted = useRef(false);
+    // If first render, or if dependencies have changed since last time
+    if (!isMounted.current || !depsAreEqual(prevDeps.current, deps)) {
         // Update state and deps
         let nextState;
         if (isFunction(initialState)) {
@@ -73,6 +62,7 @@ export default function useDerivedState(initialState, deps) {
         }
         state.current = nextState;
         prevDeps.current = deps;
+        isMounted.current = true;
     }
     const [forceUpdate] = useForceUpdate();
     const updateState = useCallback(function updateState(newState) {
@@ -90,3 +80,4 @@ export default function useDerivedState(initialState, deps) {
     }, []); // eslint-disable-line react-hooks/exhaustive-deps
     return [state.current, updateState];
 }
+//# sourceMappingURL=useStateWithDeps.js.map

package/dist/hooks/useStateWithDeps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStateWithDeps.js","sourceRoot":"","sources":["../../lib/hooks/useStateWithDeps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,WAAW,EACX,MAAM,GAIP,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,cAAc,MAAM,kBAAkB,CAAC;AAE9C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CACtC,YAA4C,EAC5C,IAAoB;IAEpB,kDAAkD;IAClD,gDAAgD;IAChD,qDAAqD;IACrD,uDAAuD;IACvD,kDAAkD;IAClD,2DAA2D;IAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,SAAc,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEhC,mEAAmE;IACnE,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;QAChE,wBAAwB;QACxB,IAAI,SAAY,CAAC;QACjB,IAAI,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7B,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,YAAY,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;QAC1B,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,GAAG,cAAc,EAAE,CAAC;IAEvC,MAAM,WAAW,GAAG,WAAW,CAAC,SAAS,WAAW,CAClD,QAAuC;QAEvC,IAAI,SAAY,CAAC;QACjB,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,SAAS,GAAG,QAAQ,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC;YAC1B,WAAW,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,kDAAkD;IAE1D,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AACtC,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { default as useDerivedState } from './hooks/useDerivedState';
 export { default as useEventListener } from './hooks/useEventListener';
 export { default as useForceUpdate } from './hooks/useForceUpdate';
+export { default as useReducerWithDeps } from './hooks/useReducerWithDeps';
+export { default as useStateWithDeps } from './hooks/useStateWithDeps';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
-export { default as useDerivedState } from './hooks/useDerivedState';
 export { default as useEventListener } from './hooks/useEventListener';
 export { default as useForceUpdate } from './hooks/useForceUpdate';
+export { default as useReducerWithDeps } from './hooks/useReducerWithDeps';
+export { default as useStateWithDeps } from './hooks/useStateWithDeps';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/utils/index.js

@@ -6,3 +6,4 @@ export function depsAreEqual(prevDeps, deps) {
     return (prevDeps.length === deps.length &&
         deps.every((dep, index) => Object.is(dep, prevDeps[index])));
 }
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/utils/index.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,QAAwB,EACxB,IAAoB;IAEpB,OAAO,CACL,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAC/B,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAC5D,CAAC;AACJ,CAAC"}

package/lib/hooks/useEventListener.ts

@@ -28,7 +28,7 @@ import { useEffect, useLayoutEffect, useRef } from 'react';
 
 /**
  * Adds `handler` as a listener for the event `eventName` of `element`
- * (or `window` by default) with the provided `options` applied.
+ * (or `window` by default) with the provided `options` applied
  *
  * It is the user's responsibility to make sure `element` and `options` values
  * are correctly memoized!

package/lib/hooks/useForceUpdate.ts

@@ -1,9 +1,40 @@
-import { useReducer } from 'react';
+import { useReducer, useRef } from 'react';
 
-export default function useForceUpdate(): [
-  () => void,
-  Record<PropertyKey, never>,
-] {
-  const [value, forceUpdate] = useReducer(() => ({}), {});
-  return [forceUpdate, value];
+/**
+ * Enables you to imperatively trigger re-rendering of components
+ *
+ * This hook is designed in the most general way possible in order to cover all
+ * imaginable use cases.
+ *
+ * @param callback An optional callback function to call during renders that
+ * were triggered with `forceUpdate()`
+ *
+ * Can be used for conditionally calling state setters when state needs to be
+ * reset. That is legal and better than using effects (see
+ * {@link https://react.dev/learn/-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes You Might Not Need an Effect > Adjusting some state when a prop changes}),
+ * but can often be avoided by using
+ * [`useStateWithDeps`]({@link ./useStateWithDeps.ts}) or
+ * [`useReducerWithDeps`]({@link ./useReducerWithDeps.ts}).
+ *
+ * Important: the callback function is called once per render, not once per
+ * `forceUpdate` call! If React batches `forceUpdate` calls, then it will only
+ * be called once.
+ *
+ * @returns An array with the following two elements:
+ *
+ * 1. A `forceUpdate` function that triggers a re-render
+ * 2. The number of times `forceUpdate` has been called so far
+ */
+export default 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;
+    callback?.();
+  }
+  return [forceUpdate, counter];
 }

package/lib/hooks/useReducerWithDeps.ts

@@ -0,0 +1,59 @@
+import {
+  type ActionDispatch,
+  type AnyActionArg,
+  type DependencyList,
+  useCallback,
+  useRef,
+} from 'react';
+import useStateWithDeps from './useStateWithDeps';
+
+/**
+ * `useReducer` hook with an additional dependency array that resets the state
+ * to the `initialState` param when the dependencies passed in the `deps` array
+ * change
+ *
+ * ### On linter support
+ *
+ * The `react-hooks/exhaustive-deps` ESLint rule doesn't support hooks where
+ * the dependency array parameter is at any other position than the second.
+ * However, as we would like to keep the hook as compatible with `useReducer` as
+ * possible, we don't want to artificially change the parameter's position.
+ * Therefore, there will be no warnings about missing dependencies.
+ * Because of that, addition caution is advised!
+ * Be sure to check no dependencies are missing from the `deps` array.
+ *
+ * Related issue: {@link https://github.com/facebook/react/issues/25443}.
+ *
+ * Unlike `eslint-plugin-react-hooks` maintained by React's team, the unofficial
+ * `useExhaustiveDependencies` rule provided for Biome by Biome's team
+ * does actually have support for dependency arrays at other positions, see
+ * {@link https://biomejs.dev/linter/rules/use-exhaustive-dependencies/#validating-dependencies}.
+ *
+ * @param reducer The reducer function that specifies how the state gets updated
+ *
+ * @param initialState The state that will be set when the component mounts or
+ * the dependencies change
+ *
+ * It can also be a function which returns a state value. If the state is reset
+ * due to a change of dependencies, this function will be passed the previous
+ * state as its argument (will be `undefined` in the first call upon mount).
+ *
+ * @param deps Dependencies that reset the state to `initialState`
+ */
+export default function useReducerWithDeps<S, A extends AnyActionArg>(
+  reducer: (prevState: S, ...args: A) => S,
+  initialState: S | ((previousState?: S) => S),
+  deps: DependencyList,
+): [S, ActionDispatch<A>] {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const [state, setState] = useStateWithDeps(initialState, deps);
+
+  // Only the initially provided reducer is used
+  const reducerRef = useRef(reducer);
+
+  const dispatch = useCallback(function dispatch(...args: A): void {
+    setState((previousState) => reducerRef.current(previousState, ...args));
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return [state, dispatch];
+}

package/lib/hooks/{useDerivedState.ts → useStateWithDeps.ts}

@@ -35,47 +35,36 @@ import { depsAreEqual, isFunction } from '../utils';
 import useForceUpdate from './useForceUpdate';
 
 /**
- * `useState` hook with an additional dependency array that resets
- * the state to the `initialState` param when the dependencies passed
- * in the `deps` array change.
+ * `useState` hook with an additional dependency array that resets the state
+ * to the `initialState` param when the dependencies passed in the `deps` array
+ * change
  *
- * @param initialState
- * The state that will be set when the component mounts or the
- * dependencies change.
+ * @param initialState The state that will be set when the component mounts or
+ * the dependencies change
  *
- * It can also be a function which resolves to the state. If the state
- * is reset due to a change of dependencies, this function will be called with the previous
- * state (`undefined` for the first call upon mount).
- * @param deps Dependencies for this hook that resets the state to `initialState`
+ * It can also be a function which returns a state value. If the state is reset
+ * due to a change of dependencies, this function will be passed the previous
+ * state as its argument (will be `undefined` in the first call upon mount).
+ *
+ * @param deps Dependencies that reset the state to `initialState`
  */
-export default function useDerivedState<S>(
+export default function useStateWithDeps<S>(
   initialState: S | ((previousState?: S) => S),
   deps: DependencyList,
 ): [S, Dispatch<SetStateAction<S>>] {
-  const isMounted = useRef(false);
-
-  // Determine initial state
-  let usableInitialState: S | null = null;
-  if (!isMounted.current) {
-    isMounted.current = true;
-    if (isFunction(initialState)) {
-      usableInitialState = initialState();
-    } else {
-      usableInitialState = initialState;
-    }
-  }
-
   // 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
-  const state = useRef(usableInitialState as S);
+  const state = useRef(undefined as S);
 
-  // Check if dependencies have changed
   const prevDeps = useRef(deps);
-  if (!depsAreEqual(prevDeps.current, deps)) {
+  const isMounted = useRef(false);
+
+  // If first render, or if dependencies have changed since last time
+  if (!isMounted.current || !depsAreEqual(prevDeps.current, deps)) {
     // Update state and deps
     let nextState: S;
     if (isFunction(initialState)) {
@@ -85,6 +74,7 @@ export default function useDerivedState<S>(
     }
     state.current = nextState;
     prevDeps.current = deps;
+    isMounted.current = true;
   }
 
   const [forceUpdate] = useForceUpdate();

package/lib/index.ts

@@ -1,3 +1,4 @@
-export { default as useDerivedState } from './hooks/useDerivedState';
 export { default as useEventListener } from './hooks/useEventListener';
 export { default as useForceUpdate } from './hooks/useForceUpdate';
+export { default as useReducerWithDeps } from './hooks/useReducerWithDeps';
+export { default as useStateWithDeps } from './hooks/useStateWithDeps';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aweebit/react-essentials",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "repository": "github:aweebit/react-essentials",
   "main": "dist/index.js",
@@ -19,9 +19,11 @@
   "peerDependencies": {
     "react": ">=18.0.0 <20"
   },
+  "dependencies": {
+    "@types/react": "19.1.6"
+  },
   "devDependencies": {
     "@eslint/js": "^9.28.0",
-    "@types/react": "^19.1.6",
     "eslint": "^9.28.0",
     "eslint-plugin-react-hooks": "^5.2.0",
     "husky": "^9.1.7",
@@ -29,7 +31,7 @@
     "prettier": "3.5.3",
     "rimraf": "^6.0.1",
     "typescript": "~5.8.3",
-    "typescript-eslint": "^8.33.0"
+    "typescript-eslint": "^8.33.1"
   },
   "license": "MIT"
 }

package/dist/hooks/useDerivedState.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useDerivedState.d.ts","sourceRoot":"","sources":["../../lib/hooks/useDerivedState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,cAAc,EACpB,MAAM,OAAO,CAAC;AAIf;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,CAAC,EACvC,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAC5C,IAAI,EAAE,cAAc,GACnB,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAsDlC"}