diff --git a/src/useForceUpdate.ts b/src/useForceUpdate.ts index 803b328..5872d9e 100644 --- a/src/useForceUpdate.ts +++ b/src/useForceUpdate.ts @@ -1,6 +1,23 @@ import { useDebugValue } from 'react'; import useState from './useState'; +/** + * Custom React utility hook that provides a way to force the a component to update. It's + * recommended to _only be used_ when the DOM is dependent on a ref value. + * + * @example + * ```js + * const update = useForceUpdate(); + * const ref = useRef(1); + * + * const increase = () => { + * ref.current += 1; + * update(); + * }; + * ``` + * + * @returns an update function that, when called, will force the component to update + */ const useForceUpdate = () => { const [tick, setTick] = useState(-1); const update = () => setTick(tick => tick + 1); diff --git a/src/useMap.ts b/src/useMap.ts index 86f7d1a..8ce89d4 100644 --- a/src/useMap.ts +++ b/src/useMap.ts @@ -1,6 +1,20 @@ import { useDebugValue, useRef } from 'react'; import useForceUpdate from './useForceUpdate'; +/** + * Custom React hook for using an ES6 Map as a state variable inside your React component. + * + * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map + * + * @example + * ```js + * const map = useMap([['foo', 'bar'], ['baz', 'qux']]); + * const fooValue = map.get('foo'); + * ``` + * + * @param entries the initial value of the Map + * @returns the current Map state variable + */ const useMap = (entries?: [T, U][]) => { const update = useForceUpdate(); const mapRef = useRef(new Map(entries)); diff --git a/src/useSet.ts b/src/useSet.ts index bce9aea..8b56773 100644 --- a/src/useSet.ts +++ b/src/useSet.ts @@ -1,6 +1,20 @@ import { useDebugValue, useRef } from 'react'; import useForceUpdate from './useForceUpdate'; +/** + * Custom React hook for using an ES6 Set as a state variable inside your React component. + * + * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set + * + * @example + * ```js + * const set = useSet([1, 2, 3]); + * const hasOne = set.has(1); + * ``` + * + * @param iterable the initial value of the Set + * @returns the current Set state variable + */ const useSet = (iterable?: Iterable) => { const update = useForceUpdate(); const setRef = useRef(new Set(iterable));