From 837da651c1c231e5bec97b9a713350e59ecd37bc Mon Sep 17 00:00:00 2001
From: Ayub-Begimkulov <begimkulov963@gmail.com>
Date: Sun, 14 Mar 2021 15:17:52 +0300
Subject: [PATCH] update readme

---
 README.md | 82 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 60 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index e62b312..aebcb34 100644
--- a/README.md
+++ b/README.md
@@ -39,52 +39,90 @@ const App = () => {
 };
 ```
 
-## Customization
+## Customizing
 
-If you want to pass custom `debounce` or `throttle` implementation (or any function that has similar interface), you could use `createDebounceHook`. It takes a function that'll debounce a callback and returns hook.
+This library uses its own implementations of `debounce` and `throttle` functions. But in some cases, you may want to change it (not enough options, smaller bundle size, etc.). For this purpose, you could use `createDebounceHook`:
 
 ```jsx
 import { createDebounceHook } from "tiny-use-debounce";
-import { debounce, throttle } from "./some/file";
+import { debounce, throttle } from "lodash";
 
 const useDebounce = createDebounceHook(debounce);
 const useThrottle = createDebounceHook(throttle);
+
+const options = {
+  leading: true,
+};
+
+const App = () => {
+  const debouncedFn = useDebounce(() => console.log("here"), 100, options);
+  const throttledFn = useThrottle(() => console.log("here"), 100, options);
+  // ...
+};
 ```
 
 ## Memoization
 
-The function returned from the hook will be alway memoized and have the same reference if `options` object is referentially equal. So if they don't change between rerenders, move them out of the component. If the change, `useMemo` to prevent updates on each render.
+By default, functions returned from hooks will always be memoized.
 
 ```jsx
-import { useMemo } from "react";
-import { useDebounce } from "tiny-use-debounce";
+const debouncedFn = useDebounce(() => {
+  /* ... */
+}, 100);
+
+useEffect(() => {
+  /* ... */
+}, [
+  //could be safely used as a dependency since reference will never change
+  debounceFn,
+]);
+```
+
+But if you create your own hook with `createDebounceHook`, you need to be a little more cautious. The first argument (the callback) will not make any effect on memoization. But other arguments will be compared referentially. So if your `debounce` implementation uses objects as options they need to be declared outside of the component or memoized. Take a look at the example below:
+
+```jsx
+import { createDebounceHook } from "tiny-use-debounce";
+import { debounce, throttle } from "lodash";
+
+const useDebounce = createDebounceHook(debounce);
 
-// options are the same, we can move them out
-// of the component
 const stableOptions = { leading: true };
 
-const App = ({ shouldCallInitially }) => {
-  const debounceFn = useDebounce(
+const App = () => {
+  const options = { leading: true };
+
+  // this function will be recreated on each rerender
+  // because options object has new reference
+  const debounceFn1 = useDebounce(
     () => {
       /* ... */
     },
-    200,
-    stableOptions
+    100,
+    options
   );
 
-  // options are dynamic, useMemo to reduce
-  // updates
-  const dynamicDebounceOptions = useMemo(
-    () => ({ leading: shouldCallInitially }),
-    [shouldCallInitially]
+  // this function will always have the same reference
+  // because all additional arguments have the same
+  // reference between renders
+  const debounceFn2 = useDebounce(
+    () => {
+      /* ... */
+    },
+    100,
+    stableOptions
   );
 
-  const debouncedFn2 = useDebounce(
+  const [leading, setLeading] = useState(true);
+  const memoOptions = useMemo(() => ({ leading }), [leading]);
+
+  // this function will only update when `leading`
+  // changes, other updates will not break memoization
+  const debounceFn3 = useDebounce(
     () => {
       /* ... */
     },
-    200,
-    dynamicDebounceOptions
+    100,
+    memoOptions
   );
 };
 ```
@@ -103,7 +141,7 @@ Creates hook that uses proved function for debouncing.
 
 Usage:
 
-- `useDebounce(cb, wait?, options?)`
+- `useDebounce(cb, wait)`
 
 Creates debounced function.
 
@@ -111,7 +149,7 @@ Creates debounced function.
 
 Usage:
 
-- `useThrottle(cb, wait?, options?)`
+- `useThrottle(cb, wait)`
 
 Creates throttled function.