@jobber/hooks 2.16.0 → 2.17.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./useBool";
 export * from "./useBreakpoints";
 export * from "./useCallbackRef";
 export * from "./useCollectionQuery";
+export * from "./useDebounce";
 export * from "./useFocusTrap";
 export * from "./useFormState";
 export * from "./useInView";

package/dist/index.js

@@ -18,6 +18,7 @@ __exportStar(require("./useBool"), exports);
 __exportStar(require("./useBreakpoints"), exports);
 __exportStar(require("./useCallbackRef"), exports);
 __exportStar(require("./useCollectionQuery"), exports);
+__exportStar(require("./useDebounce"), exports);
 __exportStar(require("./useFocusTrap"), exports);
 __exportStar(require("./useFormState"), exports);
 __exportStar(require("./useInView"), exports);

package/dist/useDebounce/index.d.ts

@@ -0,0 +1 @@
+export { useDebounce } from "./useDebounce";

package/dist/useDebounce/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDebounce = void 0;
+var useDebounce_1 = require("./useDebounce");
+Object.defineProperty(exports, "useDebounce", { enumerable: true, get: function () { return useDebounce_1.useDebounce; } });

package/dist/useDebounce/useDebounce.d.ts

@@ -0,0 +1,11 @@
+import { debounce } from "es-toolkit";
+type AnyFunction = (...args: any[]) => any;
+/**
+ * A hook to easily manage debounced functions, including their cleanup.
+ * @param func The function to debounce.
+ * @param wait The number of milliseconds to delay.
+ * @param options Optional debounce settings.
+ * @returns The debounced function.
+ */
+export declare function useDebounce<T extends AnyFunction>(func: T, wait: number, options?: Parameters<typeof debounce>[2]): import("es-toolkit").DebouncedFunction<(...args: Parameters<T>) => any>;
+export {};

package/dist/useDebounce/useDebounce.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDebounce = useDebounce;
+const react_1 = require("react");
+const es_toolkit_1 = require("es-toolkit");
+const useCallbackRef_1 = require("../useCallbackRef");
+/**
+ * A hook to easily manage debounced functions, including their cleanup.
+ * @param func The function to debounce.
+ * @param wait The number of milliseconds to delay.
+ * @param options Optional debounce settings.
+ * @returns The debounced function.
+ */
+function useDebounce(func, wait, options) {
+    const funcRef = (0, useCallbackRef_1.useCallbackRef)(func);
+    // Note: do not add additional dependencies! There is currently no use case where we would change
+    // the wait delay or options between renders. By not tracking as dependencies, this allows
+    // consumers of useDebounce to provide a raw object for options rather than forcing them to
+    // memoize that param. Same with the func they provide, we're using a ref to keep that up
+    // to date and to avoid forcing the consumer to memoize it.
+    const debounced = (0, react_1.useMemo)(() => {
+        return (0, es_toolkit_1.debounce)((...args) => funcRef(...args), wait, options);
+    }, [funcRef]);
+    (0, react_1.useEffect)(() => {
+        // If the debounced function is recreated (or unmounted), cancel the last call.
+        return () => debounced.cancel();
+    }, [debounced]);
+    return debounced;
+}

package/dist/useDebounce/useDebounce.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/useDebounce/useDebounce.test.js

@@ -0,0 +1,190 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = __importStar(require("react"));
+const react_2 = require("@testing-library/react");
+const user_event_1 = __importDefault(require("@testing-library/user-event"));
+const useDebounce_1 = require("./useDebounce");
+const DEBOUNCE_WAIT = 300;
+describe("useDebounce", () => {
+    beforeEach(() => {
+        jest.useFakeTimers();
+    });
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+    it("should debounce the function call", () => __awaiter(void 0, void 0, void 0, function* () {
+        const mockFn = jest.fn();
+        const { result } = (0, react_2.renderHook)(() => (0, useDebounce_1.useDebounce)(mockFn, DEBOUNCE_WAIT));
+        result.current("test");
+        expect(mockFn).not.toHaveBeenCalled();
+        (0, react_2.act)(() => {
+            jest.advanceTimersByTime(DEBOUNCE_WAIT);
+        });
+        expect(mockFn).toHaveBeenCalledWith("test");
+        expect(mockFn).toHaveBeenCalledTimes(1);
+    }));
+    it("should cancel pending debounced calls on unmount", () => {
+        const mockFn = jest.fn();
+        const { result, unmount } = (0, react_2.renderHook)(() => (0, useDebounce_1.useDebounce)(mockFn, DEBOUNCE_WAIT));
+        result.current("test");
+        unmount();
+        (0, react_2.act)(() => {
+            jest.advanceTimersByTime(DEBOUNCE_WAIT);
+        });
+        expect(mockFn).not.toHaveBeenCalled();
+    });
+    it("should handle multiple calls within the debounce period", () => {
+        const mockFn = jest.fn();
+        const { result } = (0, react_2.renderHook)(() => (0, useDebounce_1.useDebounce)(mockFn, DEBOUNCE_WAIT));
+        result.current("first");
+        (0, react_2.act)(() => {
+            jest.advanceTimersByTime(DEBOUNCE_WAIT / 2);
+        });
+        result.current("second");
+        (0, react_2.act)(() => {
+            jest.advanceTimersByTime(DEBOUNCE_WAIT);
+        });
+        expect(mockFn).toHaveBeenCalledTimes(1);
+        expect(mockFn).toHaveBeenCalledWith("second");
+    });
+    it("should not recreate debounced function when options object reference changes", () => {
+        const mockFn = jest.fn();
+        const debounceEgdesOption = ["trailing"];
+        // Use a function that returns a new options object each time
+        const { result, rerender } = (0, react_2.renderHook)(({ options }) => (0, useDebounce_1.useDebounce)(mockFn, DEBOUNCE_WAIT, options), { initialProps: { options: { edges: debounceEgdesOption } } });
+        const debounceRef = result.current;
+        rerender({ options: { edges: debounceEgdesOption } });
+        expect(debounceRef).toBe(result.current);
+    });
+    it("should not recreate debounced function when options config changes", () => {
+        const mockFn = jest.fn();
+        // Largely arbitrary, this value x 2 must simply be less than the debounce wait
+        const TIME_INCREMENT_LESSER_THAN_DEBOUNCE_WAIT = 1;
+        // Start with trailing edge
+        const debounceEgdesOption = ["trailing"];
+        // Use a function that returns a new options object each time
+        const { result, rerender } = (0, react_2.renderHook)(({ options }) => (0, useDebounce_1.useDebounce)(mockFn, DEBOUNCE_WAIT, options), { initialProps: { options: { edges: debounceEgdesOption } } });
+        result.current("first");
+        (0, react_2.act)(() => {
+            jest.advanceTimersByTime(TIME_INCREMENT_LESSER_THAN_DEBOUNCE_WAIT);
+        });
+        expect(mockFn).not.toHaveBeenCalled();
+        // This means it calls immediately at the leading edge of the timeout.
+        rerender({ options: { edges: ["leading"] } });
+        result.current("second");
+        (0, react_2.act)(() => {
+            jest.advanceTimersByTime(TIME_INCREMENT_LESSER_THAN_DEBOUNCE_WAIT);
+        });
+        // The config change should be ignored, options are hardcoded
+        expect(mockFn).not.toHaveBeenCalled();
+    });
+    it("should work with React components", () => __awaiter(void 0, void 0, void 0, function* () {
+        function DebouncedComponent() {
+            const [value, setValue] = (0, react_1.useState)("");
+            const [debouncedValue, setDebouncedValue] = (0, react_1.useState)("");
+            const debouncedSetValue = (0, useDebounce_1.useDebounce)((newValue) => {
+                setDebouncedValue(newValue);
+            }, DEBOUNCE_WAIT);
+            (0, react_1.useEffect)(() => {
+                debouncedSetValue(value);
+            }, [value, debouncedSetValue]);
+            return (react_1.default.createElement("div", null,
+                react_1.default.createElement("input", { "data-testid": "input", value: value, onChange: e => setValue(e.target.value) }),
+                react_1.default.createElement("div", { "data-testid": "debounced-value" }, debouncedValue)));
+        }
+        (0, react_2.render)(react_1.default.createElement(DebouncedComponent, null));
+        const input = react_2.screen.getByTestId("input");
+        const debouncedValue = react_2.screen.getByTestId("debounced-value");
+        const user = user_event_1.default.setup({ advanceTimers: jest.advanceTimersByTime });
+        yield user.type(input, "test");
+        expect(debouncedValue.textContent).toBe("");
+        (0, react_2.act)(() => {
+            jest.advanceTimersByTime(DEBOUNCE_WAIT + 100);
+        });
+        expect(debouncedValue.textContent).toBe("test");
+    }), 10000);
+    it("should properly handle options object", () => __awaiter(void 0, void 0, void 0, function* () {
+        function DebouncedComponent() {
+            const [count, setCount] = (0, react_1.useState)(0);
+            const [debouncedCount, setDebouncedCount] = (0, react_1.useState)(0);
+            const options = {
+                edges: ["leading", "trailing"],
+            };
+            const debouncedSetCount = (0, useDebounce_1.useDebounce)((value) => {
+                setDebouncedCount(value);
+            }, DEBOUNCE_WAIT, options);
+            return (react_1.default.createElement("div", null,
+                react_1.default.createElement("button", { "data-testid": "increment", onClick: () => {
+                        const newCount = count + 1;
+                        setCount(newCount);
+                        debouncedSetCount(newCount);
+                    }, type: "button" }, "Increment"),
+                react_1.default.createElement("div", { "data-testid": "count" }, count),
+                react_1.default.createElement("div", { "data-testid": "debounced-count" }, debouncedCount)));
+        }
+        (0, react_2.render)(react_1.default.createElement(DebouncedComponent, null));
+        const incrementButton = react_2.screen.getByTestId("increment");
+        const debouncedCount = react_2.screen.getByTestId("debounced-count");
+        const user = user_event_1.default.setup({ advanceTimers: jest.advanceTimersByTime });
+        yield user.click(incrementButton);
+        // With leading edge, the value should be updated immediately
+        expect(debouncedCount.textContent).toBe("1");
+        yield user.click(incrementButton);
+        yield user.click(incrementButton);
+        // Additional clicks shouldn't update immediately (debounced)
+        expect(debouncedCount.textContent).toBe("1");
+        // After the debounce period, the trailing edge should update with the latest value
+        (0, react_2.act)(() => {
+            jest.advanceTimersByTime(DEBOUNCE_WAIT);
+        });
+        expect(debouncedCount.textContent).toBe("3");
+    }));
+    it("should abort debounced function when signal is aborted", () => __awaiter(void 0, void 0, void 0, function* () {
+        const mockFn = jest.fn();
+        const controller = new AbortController();
+        const { result } = (0, react_2.renderHook)(() => (0, useDebounce_1.useDebounce)(mockFn, DEBOUNCE_WAIT, { signal: controller.signal }));
+        result.current("test");
+        (0, react_2.act)(() => {
+            controller.abort();
+        });
+        (0, react_2.act)(() => {
+            jest.advanceTimersByTime(DEBOUNCE_WAIT + 100);
+        });
+        expect(mockFn).not.toHaveBeenCalled();
+    }));
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jobber/hooks",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "license": "MIT",
   "main": "./dist/index.js",
   "types": "./dist/index.d.js",
@@ -29,6 +29,7 @@
     "uuid": "^8.3.2"
   },
   "dependencies": {
+    "es-toolkit": "^1.39.7",
     "lodash": "^4.17.20",
     "resize-observer-polyfill": "^1.5.1",
     "tiny-invariant": "^1.3.3",
@@ -39,5 +40,5 @@
     "@apollo/client": "^3.0.0",
     "react": "^18.2.0"
   },
-  "gitHead": "c2a9c186f140e9ba404a4c45240f59ac2c517936"
+  "gitHead": "5b2a570f0d657e82d04a8d60964242f67da3fab0"
 }

package/useDebounce.d.ts

@@ -0,0 +1 @@
+export * from "./dist/useDebounce";

package/useDebounce.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true,
+});
+
+var useDebounce = require("./dist/useDebounce");
+
+Object.keys(useDebounce).forEach(function(key) {
+  if (key === "default" || key === "__esModule") return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return useDebounce[key];
+    },
+  });
+});