@kopexa/use-debounced-callback 0.0.0-canary-20250721165623

package/README.md

@@ -0,0 +1,24 @@
+# @kopexa/use-debounced-callback
+
+A Quick description of the component
+
+> This is an internal utility, not intended for public usage.
+
+## Installation
+
+```sh
+yarn add @kopexa/use-debounced-callback
+# or
+npm i @kopexa/use-debounced-callback
+```
+
+## Contribution
+
+Yes please! See the
+[contributing guidelines](https://github.com/kopexa-grc/sight/blob/master/CONTRIBUTING.md)
+for details.
+
+## License
+
+This project is licensed under the terms of the
+[MIT license](https://github.com/kopexa-grc/sight/blob/master/LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+/** Configuration options for controlling the behavior of the debounced function. */
+type DebounceOptions = {
+    /**
+     * Determines whether the function should be invoked on the leading edge of the timeout.
+     * @default false
+     */
+    leading?: boolean;
+    /**
+     * Determines whether the function should be invoked on the trailing edge of the timeout.
+     * @default false
+     */
+    trailing?: boolean;
+    /**
+     * The maximum time the specified function is allowed to be delayed before it is invoked.
+     */
+    maxWait?: number;
+};
+/** Functions to manage a debounced callback. */
+type ControlFunctions = {
+    /** Cancels pending function invocations. */
+    cancel: () => void;
+    /** Immediately invokes pending function invocations. */
+    flush: () => void;
+    /**
+     * Checks if there are any pending function invocations.
+     * @returns `true` if there are pending invocations, otherwise `false`.
+     */
+    isPending: () => boolean;
+};
+/**
+ * Represents the state and control functions of a debounced callback.
+ * Subsequent calls to the debounced function return the result of the last invocation.
+ * Note: If there are no previous invocations, the result will be undefined.
+ * Ensure proper handling in your code.
+ */
+type DebouncedState<T extends (...args: any) => ReturnType<T>> = ((...args: Parameters<T>) => ReturnType<T> | undefined) & ControlFunctions;
+/**
+ * Custom hook that creates a debounced version of a callback function.
+ * @template T - Type of the original callback function.
+ * @param {T} func - The callback function to be debounced.
+ * @param {number} delay - The delay in milliseconds before the callback is invoked (default is `500` milliseconds).
+ * @param {DebounceOptions} [options] - Options to control the behavior of the debounced function.
+ * @returns {DebouncedState<T>} A debounced version of the original callback along with control functions.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-debounce-callback)
+ * @example
+ * ```tsx
+ * const debouncedCallback = useDebounceCallback(
+ *   (searchTerm) => {
+ *     // Perform search after user stops typing for 500 milliseconds
+ *     searchApi(searchTerm);
+ *   },
+ *   500
+ * );
+ *
+ * // Later in the component
+ * debouncedCallback('react hooks'); // Will invoke the callback after 500 milliseconds of inactivity.
+ * ```
+ */
+declare function useDebounceCallback<T extends (...args: any) => ReturnType<T>>(func: T, delay?: number, options?: DebounceOptions): DebouncedState<T>;
+
+export { type DebouncedState, useDebounceCallback };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/** Configuration options for controlling the behavior of the debounced function. */
+type DebounceOptions = {
+    /**
+     * Determines whether the function should be invoked on the leading edge of the timeout.
+     * @default false
+     */
+    leading?: boolean;
+    /**
+     * Determines whether the function should be invoked on the trailing edge of the timeout.
+     * @default false
+     */
+    trailing?: boolean;
+    /**
+     * The maximum time the specified function is allowed to be delayed before it is invoked.
+     */
+    maxWait?: number;
+};
+/** Functions to manage a debounced callback. */
+type ControlFunctions = {
+    /** Cancels pending function invocations. */
+    cancel: () => void;
+    /** Immediately invokes pending function invocations. */
+    flush: () => void;
+    /**
+     * Checks if there are any pending function invocations.
+     * @returns `true` if there are pending invocations, otherwise `false`.
+     */
+    isPending: () => boolean;
+};
+/**
+ * Represents the state and control functions of a debounced callback.
+ * Subsequent calls to the debounced function return the result of the last invocation.
+ * Note: If there are no previous invocations, the result will be undefined.
+ * Ensure proper handling in your code.
+ */
+type DebouncedState<T extends (...args: any) => ReturnType<T>> = ((...args: Parameters<T>) => ReturnType<T> | undefined) & ControlFunctions;
+/**
+ * Custom hook that creates a debounced version of a callback function.
+ * @template T - Type of the original callback function.
+ * @param {T} func - The callback function to be debounced.
+ * @param {number} delay - The delay in milliseconds before the callback is invoked (default is `500` milliseconds).
+ * @param {DebounceOptions} [options] - Options to control the behavior of the debounced function.
+ * @returns {DebouncedState<T>} A debounced version of the original callback along with control functions.
+ * @public
+ * @see [Documentation](https://usehooks-ts.com/react-hook/use-debounce-callback)
+ * @example
+ * ```tsx
+ * const debouncedCallback = useDebounceCallback(
+ *   (searchTerm) => {
+ *     // Perform search after user stops typing for 500 milliseconds
+ *     searchApi(searchTerm);
+ *   },
+ *   500
+ * );
+ *
+ * // Later in the component
+ * debouncedCallback('react hooks'); // Will invoke the callback after 500 milliseconds of inactivity.
+ * ```
+ */
+declare function useDebounceCallback<T extends (...args: any) => ReturnType<T>>(func: T, delay?: number, options?: DebounceOptions): DebouncedState<T>;
+
+export { type DebouncedState, useDebounceCallback };

package/dist/index.js

@@ -0,0 +1,70 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useDebounceCallback: () => useDebounceCallback
+});
+module.exports = __toCommonJS(index_exports);
+var import_use_unmount = require("@kopexa/use-unmount");
+var import_lodash = __toESM(require("lodash.debounce"));
+var import_react = require("react");
+function useDebounceCallback(func, delay = 500, options) {
+  const debouncedFunc = (0, import_react.useRef)(null);
+  (0, import_use_unmount.useUnmount)(() => {
+    if (debouncedFunc.current) {
+      debouncedFunc.current.cancel();
+    }
+  });
+  const debounced = (0, import_react.useMemo)(() => {
+    const debouncedFuncInstance = (0, import_lodash.default)(func, delay, options);
+    const wrappedFunc = (...args) => {
+      return debouncedFuncInstance(...args);
+    };
+    wrappedFunc.cancel = () => {
+      debouncedFuncInstance.cancel();
+    };
+    wrappedFunc.isPending = () => {
+      return !!debouncedFunc.current;
+    };
+    wrappedFunc.flush = () => {
+      return debouncedFuncInstance.flush();
+    };
+    return wrappedFunc;
+  }, [func, delay, options]);
+  (0, import_react.useEffect)(() => {
+    debouncedFunc.current = (0, import_lodash.default)(func, delay, options);
+  }, [func, delay, options]);
+  return debounced;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useDebounceCallback
+});

package/dist/index.mjs

@@ -0,0 +1,35 @@
+// src/index.ts
+import { useUnmount } from "@kopexa/use-unmount";
+import debounce from "lodash.debounce";
+import { useEffect, useMemo, useRef } from "react";
+function useDebounceCallback(func, delay = 500, options) {
+  const debouncedFunc = useRef(null);
+  useUnmount(() => {
+    if (debouncedFunc.current) {
+      debouncedFunc.current.cancel();
+    }
+  });
+  const debounced = useMemo(() => {
+    const debouncedFuncInstance = debounce(func, delay, options);
+    const wrappedFunc = (...args) => {
+      return debouncedFuncInstance(...args);
+    };
+    wrappedFunc.cancel = () => {
+      debouncedFuncInstance.cancel();
+    };
+    wrappedFunc.isPending = () => {
+      return !!debouncedFunc.current;
+    };
+    wrappedFunc.flush = () => {
+      return debouncedFuncInstance.flush();
+    };
+    return wrappedFunc;
+  }, [func, delay, options]);
+  useEffect(() => {
+    debouncedFunc.current = debounce(func, delay, options);
+  }, [func, delay, options]);
+  return debounced;
+}
+export {
+  useDebounceCallback
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@kopexa/use-debounced-callback",
+  "version": "0.0.0-canary-20250721165623",
+  "description": "",
+  "keywords": [
+    "use-debounced-callback"
+  ],
+  "author": "Kopexa <hello@kopexa.com>",
+  "homepage": "https://kopexa.com",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kopexa-grc/sight.git",
+    "directory": "packages/hooks/use-debounced-callback"
+  },
+  "bugs": {
+    "url": "https://github.com/kopexa-grc/sight/issues"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0-rc.0"
+  },
+  "dependencies": {
+    "lodash.debounce": "^4.0.8",
+    "@kopexa/use-unmount": "0.0.0-canary-20250721165623"
+  },
+  "clean-package": "../../../clean-package.config.json",
+  "tsup": {
+    "clean": true,
+    "target": "es2019",
+    "format": [
+      "cjs",
+      "esm"
+    ]
+  },
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup src --dts",
+    "build:fast": "tsup src",
+    "dev": "pnpm build:fast --watch",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc --noEmit"
+  }
+}