use-debounce - npm Package Compare versions

Comparing version 5.1.0 to 5.2.0

CHANGELOG.md

@@ -0,1 +1,5 @@
+## 5.2.0
+
+- Added `useThrottledCallback`
+
 ## 5.1.0
@@ -2,0 +6,0 @@

esm/index.d.ts

 import useDebounce from './useDebounce';
 import useDebouncedCallback from './useDebouncedCallback';
-export { useDebounce, useDebouncedCallback };
+import useThrottledCallback from './useThrottledCallback';
+export { useDebounce, useDebouncedCallback, useThrottledCallback };

esm/index.js

 import useDebounce from './useDebounce';
 import useDebouncedCallback from './useDebouncedCallback';
-export { useDebounce, useDebouncedCallback };
+import useThrottledCallback from './useThrottledCallback';
+export { useDebounce, useDebouncedCallback, useThrottledCallback };

esm/useDebouncedCallback.d.ts

@@ -1,6 +0,8 @@
-export interface Options {
-    maxWait?: number;
+export interface CallOptions {
     leading?: boolean;
     trailing?: boolean;
 }
+export interface Options extends CallOptions {
+    maxWait?: number;
+}
 export interface ControlFunctions {
@@ -18,2 +20,64 @@ cancel: () => void;
 }
+/**
+ * Creates a debounced function that delays invoking `func` until after `wait`
+ * milliseconds have elapsed since the last time the debounced function was
+ * invoked, or until the next browser frame is drawn. The debounced function
+ * comes with a `cancel` method to cancel delayed `func` invocations and a
+ * `flush` method to immediately invoke them. Provide `options` to indicate
+ * whether `func` should be invoked on the leading and/or trailing edge of the
+ * `wait` timeout. The `func` is invoked with the last arguments provided to the
+ * debounced function. Subsequent calls to the debounced function return the
+ * result of the last `func` invocation.
+ *
+ * **Note:** If `leading` and `trailing` options are `true`, `func` is
+ * invoked on the trailing edge of the timeout only if the debounced function
+ * is invoked more than once during the `wait` timeout.
+ *
+ * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred
+ * until the next tick, similar to `setTimeout` with a timeout of `0`.
+ *
+ * If `wait` is omitted in an environment with `requestAnimationFrame`, `func`
+ * invocation will be deferred until the next frame is drawn (typically about
+ * 16ms).
+ *
+ * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)
+ * for details over the differences between `debounce` and `throttle`.
+ *
+ * @category Function
+ * @param {Function} func The function to debounce.
+ * @param {number} [wait=0]
+ *  The number of milliseconds to delay; if omitted, `requestAnimationFrame` is
+ *  used (if available, otherwise it will be setTimeout(...,0)).
+ * @param {Object} [options={}] The options object.
+ * @param {boolean} [options.leading=false]
+ *  Specify invoking on the leading edge of the timeout.
+ * @param {number} [options.maxWait]
+ *  The maximum time `func` is allowed to be delayed before it's invoked.
+ * @param {boolean} [options.trailing=true]
+ *  Specify invoking on the trailing edge of the timeout.
+ * @returns {Function} Returns the new debounced function.
+ * @example
+ *
+ * // Avoid costly calculations while the window size is in flux.
+ * const resizeHandler = useDebouncedCallback(calculateLayout, 150);
+ * window.addEventListener('resize', resizeHandler)
+ *
+ * // Invoke `sendMail` when clicked, debouncing subsequent calls.
+ * const clickHandler = useDebouncedCallback(sendMail, 300, {
+ *   leading: true,
+ *   trailing: false,
+ * })
+ * <button onClick={clickHandler}>click me</button>
+ *
+ * // Ensure `batchLog` is invoked once after 1 second of debounced calls.
+ * const debounced = useDebouncedCallback(batchLog, 250, { 'maxWait': 1000 })
+ * const source = new EventSource('/stream')
+ * source.addEventListener('message', debounced)
+ *
+ * // Cancel the trailing debounced invocation.
+ * window.addEventListener('popstate', debounced.cancel)
+ *
+ * // Check for pending invocations.
+ * const status = debounced.pending() ? "Pending..." : "Ready"
+ */
 export default function useDebouncedCallback<T extends (...args: any[]) => ReturnType<T>>(func: T, wait?: number, options?: Options): DebouncedState<T>;

esm/useDebouncedCallback.js

 import { useRef, useCallback, useEffect, useMemo } from 'react';
+/**
+ * Creates a debounced function that delays invoking `func` until after `wait`
+ * milliseconds have elapsed since the last time the debounced function was
+ * invoked, or until the next browser frame is drawn. The debounced function
+ * comes with a `cancel` method to cancel delayed `func` invocations and a
+ * `flush` method to immediately invoke them. Provide `options` to indicate
+ * whether `func` should be invoked on the leading and/or trailing edge of the
+ * `wait` timeout. The `func` is invoked with the last arguments provided to the
+ * debounced function. Subsequent calls to the debounced function return the
+ * result of the last `func` invocation.
+ *
+ * **Note:** If `leading` and `trailing` options are `true`, `func` is
+ * invoked on the trailing edge of the timeout only if the debounced function
+ * is invoked more than once during the `wait` timeout.
+ *
+ * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred
+ * until the next tick, similar to `setTimeout` with a timeout of `0`.
+ *
+ * If `wait` is omitted in an environment with `requestAnimationFrame`, `func`
+ * invocation will be deferred until the next frame is drawn (typically about
+ * 16ms).
+ *
+ * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)
+ * for details over the differences between `debounce` and `throttle`.
+ *
+ * @category Function
+ * @param {Function} func The function to debounce.
+ * @param {number} [wait=0]
+ *  The number of milliseconds to delay; if omitted, `requestAnimationFrame` is
+ *  used (if available, otherwise it will be setTimeout(...,0)).
+ * @param {Object} [options={}] The options object.
+ * @param {boolean} [options.leading=false]
+ *  Specify invoking on the leading edge of the timeout.
+ * @param {number} [options.maxWait]
+ *  The maximum time `func` is allowed to be delayed before it's invoked.
+ * @param {boolean} [options.trailing=true]
+ *  Specify invoking on the trailing edge of the timeout.
+ * @returns {Function} Returns the new debounced function.
+ * @example
+ *
+ * // Avoid costly calculations while the window size is in flux.
+ * const resizeHandler = useDebouncedCallback(calculateLayout, 150);
+ * window.addEventListener('resize', resizeHandler)
+ *
+ * // Invoke `sendMail` when clicked, debouncing subsequent calls.
+ * const clickHandler = useDebouncedCallback(sendMail, 300, {
+ *   leading: true,
+ *   trailing: false,
+ * })
+ * <button onClick={clickHandler}>click me</button>
+ *
+ * // Ensure `batchLog` is invoked once after 1 second of debounced calls.
+ * const debounced = useDebouncedCallback(batchLog, 250, { 'maxWait': 1000 })
+ * const source = new EventSource('/stream')
+ * source.addEventListener('message', debounced)
+ *
+ * // Cancel the trailing debounced invocation.
+ * window.addEventListener('popstate', debounced.cancel)
+ *
+ * // Check for pending invocations.
+ * const status = debounced.pending() ? "Pending..." : "Ready"
+ */
 export default function useDebouncedCallback(func, wait, options) {
@@ -3,0 +65,0 @@ var _this = this;

lib/index.d.ts

 import useDebounce from './useDebounce';
 import useDebouncedCallback from './useDebouncedCallback';
-export { useDebounce, useDebouncedCallback };
+import useThrottledCallback from './useThrottledCallback';
+export { useDebounce, useDebouncedCallback, useThrottledCallback };

lib/index.js

@@ -7,1 +7,3 @@ "use strict";
 exports.useDebouncedCallback = useDebouncedCallback_1.default;
+var useThrottledCallback_1 = require("./useThrottledCallback");
+exports.useThrottledCallback = useThrottledCallback_1.default;

lib/useDebouncedCallback.d.ts

@@ -1,6 +0,8 @@
-export interface Options {
-    maxWait?: number;
+export interface CallOptions {
     leading?: boolean;
     trailing?: boolean;
 }
+export interface Options extends CallOptions {
+    maxWait?: number;
+}
 export interface ControlFunctions {
@@ -18,2 +20,64 @@ cancel: () => void;
 }
+/**
+ * Creates a debounced function that delays invoking `func` until after `wait`
+ * milliseconds have elapsed since the last time the debounced function was
+ * invoked, or until the next browser frame is drawn. The debounced function
+ * comes with a `cancel` method to cancel delayed `func` invocations and a
+ * `flush` method to immediately invoke them. Provide `options` to indicate
+ * whether `func` should be invoked on the leading and/or trailing edge of the
+ * `wait` timeout. The `func` is invoked with the last arguments provided to the
+ * debounced function. Subsequent calls to the debounced function return the
+ * result of the last `func` invocation.
+ *
+ * **Note:** If `leading` and `trailing` options are `true`, `func` is
+ * invoked on the trailing edge of the timeout only if the debounced function
+ * is invoked more than once during the `wait` timeout.
+ *
+ * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred
+ * until the next tick, similar to `setTimeout` with a timeout of `0`.
+ *
+ * If `wait` is omitted in an environment with `requestAnimationFrame`, `func`
+ * invocation will be deferred until the next frame is drawn (typically about
+ * 16ms).
+ *
+ * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)
+ * for details over the differences between `debounce` and `throttle`.
+ *
+ * @category Function
+ * @param {Function} func The function to debounce.
+ * @param {number} [wait=0]
+ *  The number of milliseconds to delay; if omitted, `requestAnimationFrame` is
+ *  used (if available, otherwise it will be setTimeout(...,0)).
+ * @param {Object} [options={}] The options object.
+ * @param {boolean} [options.leading=false]
+ *  Specify invoking on the leading edge of the timeout.
+ * @param {number} [options.maxWait]
+ *  The maximum time `func` is allowed to be delayed before it's invoked.
+ * @param {boolean} [options.trailing=true]
+ *  Specify invoking on the trailing edge of the timeout.
+ * @returns {Function} Returns the new debounced function.
+ * @example
+ *
+ * // Avoid costly calculations while the window size is in flux.
+ * const resizeHandler = useDebouncedCallback(calculateLayout, 150);
+ * window.addEventListener('resize', resizeHandler)
+ *
+ * // Invoke `sendMail` when clicked, debouncing subsequent calls.
+ * const clickHandler = useDebouncedCallback(sendMail, 300, {
+ *   leading: true,
+ *   trailing: false,
+ * })
+ * <button onClick={clickHandler}>click me</button>
+ *
+ * // Ensure `batchLog` is invoked once after 1 second of debounced calls.
+ * const debounced = useDebouncedCallback(batchLog, 250, { 'maxWait': 1000 })
+ * const source = new EventSource('/stream')
+ * source.addEventListener('message', debounced)
+ *
+ * // Cancel the trailing debounced invocation.
+ * window.addEventListener('popstate', debounced.cancel)
+ *
+ * // Check for pending invocations.
+ * const status = debounced.pending() ? "Pending..." : "Ready"
+ */
 export default function useDebouncedCallback<T extends (...args: any[]) => ReturnType<T>>(func: T, wait?: number, options?: Options): DebouncedState<T>;

lib/useDebouncedCallback.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 var react_1 = require("react");
+/**
+ * Creates a debounced function that delays invoking `func` until after `wait`
+ * milliseconds have elapsed since the last time the debounced function was
+ * invoked, or until the next browser frame is drawn. The debounced function
+ * comes with a `cancel` method to cancel delayed `func` invocations and a
+ * `flush` method to immediately invoke them. Provide `options` to indicate
+ * whether `func` should be invoked on the leading and/or trailing edge of the
+ * `wait` timeout. The `func` is invoked with the last arguments provided to the
+ * debounced function. Subsequent calls to the debounced function return the
+ * result of the last `func` invocation.
+ *
+ * **Note:** If `leading` and `trailing` options are `true`, `func` is
+ * invoked on the trailing edge of the timeout only if the debounced function
+ * is invoked more than once during the `wait` timeout.
+ *
+ * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred
+ * until the next tick, similar to `setTimeout` with a timeout of `0`.
+ *
+ * If `wait` is omitted in an environment with `requestAnimationFrame`, `func`
+ * invocation will be deferred until the next frame is drawn (typically about
+ * 16ms).
+ *
+ * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)
+ * for details over the differences between `debounce` and `throttle`.
+ *
+ * @category Function
+ * @param {Function} func The function to debounce.
+ * @param {number} [wait=0]
+ *  The number of milliseconds to delay; if omitted, `requestAnimationFrame` is
+ *  used (if available, otherwise it will be setTimeout(...,0)).
+ * @param {Object} [options={}] The options object.
+ * @param {boolean} [options.leading=false]
+ *  Specify invoking on the leading edge of the timeout.
+ * @param {number} [options.maxWait]
+ *  The maximum time `func` is allowed to be delayed before it's invoked.
+ * @param {boolean} [options.trailing=true]
+ *  Specify invoking on the trailing edge of the timeout.
+ * @returns {Function} Returns the new debounced function.
+ * @example
+ *
+ * // Avoid costly calculations while the window size is in flux.
+ * const resizeHandler = useDebouncedCallback(calculateLayout, 150);
+ * window.addEventListener('resize', resizeHandler)
+ *
+ * // Invoke `sendMail` when clicked, debouncing subsequent calls.
+ * const clickHandler = useDebouncedCallback(sendMail, 300, {
+ *   leading: true,
+ *   trailing: false,
+ * })
+ * <button onClick={clickHandler}>click me</button>
+ *
+ * // Ensure `batchLog` is invoked once after 1 second of debounced calls.
+ * const debounced = useDebouncedCallback(batchLog, 250, { 'maxWait': 1000 })
+ * const source = new EventSource('/stream')
+ * source.addEventListener('message', debounced)
+ *
+ * // Cancel the trailing debounced invocation.
+ * window.addEventListener('popstate', debounced.cancel)
+ *
+ * // Check for pending invocations.
+ * const status = debounced.pending() ? "Pending..." : "Ready"
+ */
 function useDebouncedCallback(func, wait, options) {
@@ -5,0 +67,0 @@ var _this = this;

package.json

 {
   "name": "use-debounce",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "Debounce hook for react",
@@ -95,4 +95,9 @@ "main": "lib/index.js",
       "limit": "1 KB"
+    },
+    {
+      "path": "esm/index.js",
+      "import": "{ useThrottledCallback }",
+      "limit": "1 KB"
     }
   ]
 }

README.md

@@ -305,1 +305,39 @@ <div align="center">
 | equalityFn | (prev, next) => prev === next | Comparator function which shows if timeout should be started                                                                     |                                                                        |
+
+## useThrottledCallback
+
+You are able to use throttled callback with this library also (starting 5.2.0 version).
+For this purpose use:
+
+```
+import useThrottledCallback from 'use-debounce/useThrottledCallback';
+```
+
+or
+
+```
+import { useThrottledCallback } from 'use-debounce';
+```
+
+Several examples:
+
+1. Avoid excessively updating the position while scrolling.
+
+   ```js
+   const scrollHandler = useThrottledCallback(updatePosition, 100);
+   window.addEventListener('scroll', scrollHandler);
+   ```
+
+2. Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.
+   ```js
+   const throttled = useThrottledCallback(renewToken, 300000, { 'trailing': false })
+   <button onClick={throttled}>click</button>
+   ```
+
+All the params for `useThrottledCallback` are the same as for `useDebouncedCallback` except `maxWait` option. As it's not needed for throttle callbacks.
+
+# Special thanks:
+
+[@tryggvigy](https://github.com/tryggvigy) — for managing lots of new features of the library like trailing and leading params, throttle callback, etc;
+
+[@omgovich](https://github.com/omgovich) — for reducing bundle size.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

65176

increased by60.59%

Number of package files

20

increased by25%

Lines of code

839

increased by129.86%

Number of lines in readme file

343

increased by12.46%

No dependency changes