[ADD] useLazyRef hook

Author: nDriaDev

apps/react-tools-demo/src/components/hooks/useLazyRef/UseLazyRef.tsx

@@ -0,0 +1,40 @@
+import { useRef } from "react";
+import { useInterval, useLazyRef, useRerender } from "../../../../../../packages/react-tools/src";
+
+/**
+There are two functions __initializer__ and __initializerLazy__ that log a message when they runs then sum and return number from 0 to 100.
+
+The component has:
+- a __lazyValue__ creates by _useLazyRef_ hook with __initializerLazy__ function as param.
+- a __value__ creates by _useRef_ hook with __initializer__ function executed as param.
+- a __rerender__ function created by _useRerender_ hook to force a rerender.
+- a __apply__ function created by _useInterval_ hook to execute __rerender__ function every second.
+- render a div with __lazyValue__ and __value__ values.
+
+If you open devtools will see that __initializerLazy__ message is logged once while __initializer__ message every rerender.
+ */
+const initializer = () => {
+	console.log("initializer run...")
+	return Array(100).fill(true).reduce((prev, curr, index) => prev + index, 0);
+}
+
+const initializerLazy = () => {
+	console.log("initializerLazy run...")
+	return Array(100).fill(true).reduce((prev, curr, index) => prev + index, 0);
+}
+
+export const UseLazyRef = () => {
+	const rerender = useRerender();
+	const [apply] = useInterval(() => rerender(), 1000);
+	const lazyValue = useLazyRef(initializerLazy);
+	const value = useRef(initializer());
+
+	apply();
+
+	return (
+		<div>
+			<p>Value is: {value.current}</p>
+			<p>LazyValue is: {lazyValue.current}</p>
+		</div>
+	);
+}

apps/react-tools-demo/src/constants/components.ts

@@ -37,6 +37,7 @@ export const COMPONENTS = [
 			"useMemoDeepCompare",
 			"useCallbackCompare",
 			"useCallbackDeepCompare",
+			"useLazyRef"
 		],
 		//EVENTS
 		[

apps/react-tools-demo/src/markdown/useLazyRef.md

@@ -0,0 +1,61 @@
+# useLazyRef
+Hook that works 'partially' like the _useState_ hook with lazy initialization: ensures that the __initializer__ function is executed only once.
+
+## Usage
+
+```tsx
+const initializer = () => {
+	console.log("initializer run...")
+	return Array(100).fill(true).reduce((prev, curr, index) => prev + index, 0);
+}
+
+const initializerLazy = () => {
+	console.log("initializerLazy run...")
+	return Array(100).fill(true).reduce((prev, curr, index) => prev + index, 0);
+}
+
+export const UseLazyRef = () => {
+	const rerender = useRerender();
+	const [apply] = useInterval(() => rerender(), 1000);
+	const lazyValue = useLazyRef(initializerLazy);
+	const value = useRef(initializer());
+
+	apply();
+
+	return (
+		<div>
+			<p>Value is: {value.current}</p>
+			<p>LazyValue is: {lazyValue.current}</p>
+		</div>
+	);
+}
+```
+
+> There are two functions __initializer__ and __initializerLazy__ that log a message when they runs then sum and return number from 0 to 100.
+> 
+> The component has:
+> - a __lazyValue__ creates by _useLazyRef_ hook with __initializerLazy__ function as param.
+> - a __value__ creates by _useRef_ hook with __initializer__ function executed as param.
+> - a __rerender__ function created by _useRerender_ hook to force a rerender.
+> - a __apply__ function created by _useInterval_ hook to execute __rerender__ function every second.
+> - render a div with __lazyValue__ and __value__ values.
+> 
+> If you open devtools will see that __initializerLazy__ message is logged once while __initializer__ message every rerender.
+
+
+## API
+
+```tsx
+useLazyRef <T>(initializer: () => T): React.MutableRefObject<T> 
+```
+
+> ### Params
+>
+> - __initializer__: _()=>T_
+>
+
+> ### Returns
+>
+> 
+> - _React.MutableRefObject<T>_  
+>

apps/react-tools-demo/src/markdown/useTitle.md

@@ -21,7 +21,9 @@ export const UseTitle = () => {
 }
 ```
 
-> First, in a variable outside the component is kept track of the page title. The _useTitle_ hook is invoked in the component with the _title_ __Title 1__ parameter and the returned _setTitle_ function is used. After 3 seconds the title is changed with the _setTitle_ function to _title_ __Title 2__. When the component is unmounted, the title saved in the variable outside the component is set as the title.
+> First, in a variable outside the component is kept track of the page title. The _useTitle_ hook is invoked in the component with the _title_ __Title 1__ parameter and the returned _setTitle_ function is used. After 3 seconds the title is changed with the _setTitle_ function to _title_ __Title 2__.
+> 
+> When the component is unmounted, the title saved in the variable outside the component is set as the title.
 
 
 ## API

packages/react-tools/README.md

@@ -35,6 +35,7 @@
 	- [x] useMemoizedFunction
 	- [x] useMemoCompare
 	- [x] useMemoDeepCompare
+	- [x] useLazyRef
 
 - __EVENTS__
 	- [x] useEvents

packages/react-tools/src/hooks/index.ts

@@ -40,4 +40,5 @@ export { useDocumentVisibility } from './useDocumentVisibility';
 export { useClipboard } from './useClipboard';
 export { useMediaQuery } from './useMediaQuery';
 export { useColorScheme } from './useColorScheme';
-export { useTitle } from './useTitle'
+export { useTitle } from './useTitle'
+export { useLazyRef } from './useLazyRef';

packages/react-tools/src/hooks/useLazyRef.ts

@@ -0,0 +1,15 @@
+import { useRef } from "react"
+
+const noValue = Symbol("useLazyRef.noValue");
+/**
+ * **`useLazyRef`**: Hook that works 'partially' like the _useState_ hook with lazy initialization: ensures that the __initializer__ function is executed only once.
+ * @param {()=>T} initializer
+ * @returns {React.MutableRefObject<T>}
+ */
+export const useLazyRef = <T>(initializer: () => T): React.MutableRefObject<T> => {
+	const ref = useRef<T | typeof noValue>(noValue);
+	if (ref.current === noValue) {
+		ref.current = initializer();
+	}
+	return ref as React.MutableRefObject<T>;
+}

packages/react-tools/src/index.ts

@@ -49,7 +49,8 @@ export {
 	useClipboard,
 	useMediaQuery,
 	useColorScheme,
-	useTitle
+	useTitle,
+	useLazyRef
 } from './hooks'
 
 export {