@khanacademy/wonder-blocks-timing 4.0.1 → 5.0.0

package/src/hooks/__tests__/use-timeout.test.ts

@@ -1,4 +1,5 @@
-import {renderHook} from "@testing-library/react-hooks";
+import {renderHook, act} from "@testing-library/react-hooks";
+import {SchedulePolicy, ClearPolicy, ActionPolicy} from "../../util/policies";
 
 import {useTimeout} from "../use-timeout";
 
@@ -7,129 +8,482 @@ describe("useTimeout", () => {
         jest.useFakeTimers();
     });
 
-    it("should not fire if 'active' is false", () => {
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    it("throws if the action is not a function", () => {
         // Arrange
-        const action = jest.fn();
 
         // Act
-        renderHook(() => useTimeout(action, 500, false));
-        jest.advanceTimersByTime(501);
+        const {result} = renderHook(() => useTimeout(null as any, 1000));
 
         // Assert
-        expect(action).not.toHaveBeenCalled();
+        expect(result.error).toEqual(Error("Action must be a function"));
     });
 
-    it("should not fire before the timeout", () => {
+    it("throws if the period is less than 0", () => {
         // Arrange
-        const action = jest.fn();
 
         // Act
-        renderHook(() => useTimeout(action, 500, true));
-        jest.advanceTimersByTime(499);
+        const {result} = renderHook(() => useTimeout(() => {}, -1));
 
         // Assert
-        expect(action).not.toHaveBeenCalled();
+        expect(result.error).toEqual(Error("Timeout period must be >= 0"));
     });
 
-    it("should fire after the timeout", () => {
+    it("should return an ITimeout", () => {
         // Arrange
-        const action = jest.fn();
+        const {result} = renderHook(() => useTimeout(() => {}, 1000));
 
         // Act
-        renderHook(() => useTimeout(action, 500, true));
-        jest.advanceTimersByTime(501);
 
         // Assert
-        expect(action).toHaveBeenCalledTimes(1);
+        expect(result.current).toEqual(
+            expect.objectContaining({
+                clear: expect.any(Function),
+                set: expect.any(Function),
+                isSet: expect.any(Boolean),
+            }),
+        );
+    });
+
+    it("should default to being immediately set", () => {
+        // Arrange
+        const {result} = renderHook(() => useTimeout(() => {}, 1000));
+
+        // Act
+
+        // Assert
+        expect(result.current.isSet).toBe(true);
     });
 
-    it("should fire after time after 'active' changes to true", () => {
+    it("should call the action before unmounting", () => {
         // Arrange
         const action = jest.fn();
-        const {rerender} = renderHook(
-            ({active}: any) => useTimeout(action, 500, active),
-            {initialProps: {active: false}},
+        const {unmount} = renderHook(() =>
+            useTimeout(action, 1000, {
+                clearPolicy: ClearPolicy.Resolve,
+            }),
         );
 
         // Act
-        rerender({active: true});
-        jest.advanceTimersByTime(501);
+        act(() => {
+            unmount();
+        });
 
         // Assert
         expect(action).toHaveBeenCalled();
     });
 
-    it("should not fire after the timeout if 'active' changes to false", () => {
+    it("should call the current action", () => {
         // Arrange
-        const action = jest.fn();
+        const action1 = jest.fn();
+        const action2 = jest.fn();
         const {rerender} = renderHook(
-            ({active}: any) => useTimeout(action, 500, active),
-            {initialProps: {active: true}},
+            ({action}: any) => useTimeout(action, 500),
+            {
+                initialProps: {action: action1},
+            },
         );
 
         // Act
-        rerender({active: false});
+        rerender({action: action2});
         jest.advanceTimersByTime(501);
 
         // Assert
-        expect(action).not.toHaveBeenCalled();
+        expect(action2).toHaveBeenCalledTimes(1);
     });
 
-    it("should reset the timeout if 'timeoutMs' is changes", () => {
+    it("should only call setTimeout once even if action changes", () => {
         // Arrange
-        const action = jest.fn();
-
-        // Act
+        const timeoutSpy = jest.spyOn(global, "setTimeout");
+        const action1 = jest.fn();
+        const action2 = jest.fn();
         const {rerender} = renderHook(
-            ({timeoutMs}: any) => useTimeout(action, timeoutMs, true),
-            {initialProps: {timeoutMs: 500}},
+            ({action}: any) => useTimeout(action, 500),
+            {
+                initialProps: {action: action1},
+            },
         );
-        rerender({timeoutMs: 1000});
-        jest.advanceTimersByTime(501);
+        // Act
+        rerender({action: action2});
 
         // Assert
-        expect(action).not.toHaveBeenCalled();
-        jest.advanceTimersByTime(1001);
-        expect(action).toHaveBeenCalled();
+        expect(timeoutSpy).toHaveBeenCalledOnce();
     });
 
-    it("should not reset the timeout if 'action' changes", () => {
+    it("should not reset the timeout if the action changes", () => {
         // Arrange
         const action1 = jest.fn();
         const action2 = jest.fn();
-        const timeoutSpy = jest.spyOn(window, "setTimeout");
-
-        // Act
         const {rerender} = renderHook(
-            ({action}: any) => useTimeout(action, 500, true),
-            {initialProps: {action: action1}},
+            ({action}: any) => useTimeout(action, 500),
+            {
+                initialProps: {action: action1},
+            },
         );
-        // NOTE: For some reason setTimeout is called twice by the time we get
-        // here.  I've verified that it only gets called once inside the hook
-        // so something else must be calling it.
-        const callCount = timeoutSpy.mock.calls.length;
+
+        // Act
+        jest.advanceTimersByTime(250);
         rerender({action: action2});
-        jest.advanceTimersByTime(501);
+        jest.advanceTimersByTime(251);
 
         // Assert
-        expect(timeoutSpy).toHaveBeenCalledTimes(callCount);
+        expect(action1).not.toHaveBeenCalled();
+        expect(action2).toHaveBeenCalledTimes(1);
     });
 
-    it("should fire the current action if 'action' changes", () => {
+    it("should reset the timeout if the action changes and the action policy is Reset", () => {
         // Arrange
         const action1 = jest.fn();
         const action2 = jest.fn();
+        const {rerender} = renderHook(
+            ({action}: any) =>
+                useTimeout(action, 500, {actionPolicy: ActionPolicy.Reset}),
+            {
+                initialProps: {action: action1},
+            },
+        );
 
         // Act
+        jest.advanceTimersByTime(250);
+        rerender({action: action2});
+        jest.advanceTimersByTime(251);
+
+        // Assert
+        expect(action1).not.toHaveBeenCalled();
+        expect(action2).not.toHaveBeenCalled();
+    });
+
+    it("should use the new timeout duration after changing it", () => {
+        // Arrange
+        const action = jest.fn();
         const {rerender} = renderHook(
-            ({action}: any) => useTimeout(action, 500, true),
-            {initialProps: {action: action1}},
+            ({timeoutMs}: any) => useTimeout(action, timeoutMs),
+            {
+                initialProps: {timeoutMs: 500},
+            },
+        );
+        rerender({timeoutMs: 1000});
+
+        // Act
+        jest.advanceTimersByTime(1501);
+
+        // Assert
+        expect(action).toHaveBeenCalledTimes(1);
+    });
+
+    it("should restart the timeout if intervalMs changes", () => {
+        // Arrange
+        const timeoutSpy = jest.spyOn(global, "setTimeout");
+        const {rerender} = renderHook(
+            ({timeoutMs}: any) => useTimeout(() => {}, timeoutMs),
+            {
+                initialProps: {timeoutMs: 500},
+            },
         );
-        rerender({action: action2});
-        jest.advanceTimersByTime(501);
+
+        // Act
+        rerender({timeoutMs: 1000});
 
         // Assert
-        expect(action1).not.toHaveBeenCalledWith();
-        expect(action2).toHaveBeenCalledWith();
+        expect(timeoutSpy).toHaveBeenCalledWith(expect.any(Function), 500);
+        expect(timeoutSpy).toHaveBeenCalledWith(expect.any(Function), 1000);
+    });
+
+    describe("SchedulePolicy.Immediately", () => {
+        it("should call the action after the timeout expires", () => {
+            // Arrange
+            const action = jest.fn();
+            renderHook(() => useTimeout(action, 1000));
+
+            // Act
+            act(() => {
+                jest.advanceTimersByTime(1000);
+            });
+
+            // Assert
+            expect(action).toHaveBeenCalled();
+        });
+
+        it("should update isSet to false after the timeout expires", () => {
+            // Arrange
+            const action = jest.fn();
+            const {result} = renderHook(() => useTimeout(action, 1000));
+
+            // Act
+            act(() => {
+                jest.advanceTimersByTime(1001);
+            });
+
+            // Assert
+            expect(result.current.isSet).toBe(false);
+        });
+
+        it("should call the action again if 'set' is called after the action was called", () => {
+            // Arrange
+            const action = jest.fn();
+            const {result} = renderHook(() => useTimeout(action, 1000));
+
+            // Act
+            act(() => {
+                jest.advanceTimersByTime(1001);
+            });
+            act(() => {
+                result.current.set();
+            });
+            act(() => {
+                jest.advanceTimersByTime(1001);
+            });
+
+            // Assert
+            expect(action).toHaveBeenCalledTimes(2);
+        });
+
+        it("should restart the timeout if timeoutMs gets updated", () => {
+            // Arrange
+            const action = jest.fn();
+            const {rerender} = renderHook(
+                ({timeoutMs}: any) => useTimeout(action, timeoutMs),
+                {
+                    initialProps: {timeoutMs: 1000},
+                },
+            );
+
+            // Act
+            act(() => {
+                jest.advanceTimersByTime(900);
+            });
+            rerender({timeoutMs: 500});
+            act(() => {
+                jest.advanceTimersByTime(100);
+            });
+
+            // Assert
+            expect(action).not.toHaveBeenCalled();
+            act((): void => jest.advanceTimersByTime(500));
+            expect(action).toHaveBeenCalled();
+        });
+
+        it("should should timeout after the new timeoutMs if it gets updated", () => {
+            // Arrange
+            const action = jest.fn();
+            const {rerender} = renderHook(
+                ({timeoutMs}: any) => useTimeout(action, timeoutMs),
+                {
+                    initialProps: {timeoutMs: 1000},
+                },
+            );
+
+            // Act
+            rerender({timeoutMs: 500});
+            act(() => {
+                jest.advanceTimersByTime(500);
+            });
+
+            // Assert
+            expect(action).toHaveBeenCalled();
+        });
+
+        it("should call the new action after re-rendering with a new action", () => {
+            // Arrange
+            const action1 = jest.fn();
+            const action2 = jest.fn();
+            const {rerender} = renderHook(
+                ({action}: any) => useTimeout(action, 1000),
+                {
+                    initialProps: {action: action1},
+                },
+            );
+
+            // Act
+            rerender({action: action2});
+            act(() => {
+                jest.advanceTimersByTime(1000);
+            });
+
+            // Assert
+            expect(action2).toHaveBeenCalled();
+        });
+
+        it("should not call the original action after re-rendering with a new action", () => {
+            // Arrange
+            const action1 = jest.fn();
+            const action2 = jest.fn();
+            const {rerender} = renderHook(
+                ({action}: any) => useTimeout(action, 1000),
+                {
+                    initialProps: {action: action1},
+                },
+            );
+
+            // Act
+            rerender({action: action2});
+            act(() => {
+                jest.advanceTimersByTime(1000);
+            });
+
+            // Assert
+            expect(action1).not.toHaveBeenCalled();
+        });
+
+        it("should not call the action if the timeout is cleared", () => {
+            // Arrange
+            const action = jest.fn();
+            const {result} = renderHook(() => useTimeout(action, 1000));
+
+            // Act
+            act(() => {
+                result.current.clear();
+            });
+            act(() => {
+                jest.advanceTimersByTime(1000);
+            });
+
+            // Assert
+            expect(action).not.toHaveBeenCalled();
+        });
+
+        it("should call the action when the timeout is cleared when passing ClearPolicy.Resolve to clear()", () => {
+            // Arrange
+            const action = jest.fn();
+            const {result} = renderHook(() => useTimeout(action, 1000));
+
+            // Act
+            act(() => {
+                result.current.clear(ClearPolicy.Resolve);
+            });
+
+            // Assert
+            expect(action).toHaveBeenCalled();
+        });
+
+        it("should call the action on unmount when using ClearPolicy.Resolve in options", () => {
+            // Arrange
+            const action = jest.fn();
+            const {unmount} = renderHook(() =>
+                useTimeout(action, 1000, {
+                    clearPolicy: ClearPolicy.Resolve,
+                }),
+            );
+
+            // Act
+            unmount();
+
+            // Assert
+            expect(action).toHaveBeenCalled();
+        });
+
+        it("should not call the action on unmount when using the default options", () => {
+            // Arrange
+            const action = jest.fn();
+            const {unmount} = renderHook(() => useTimeout(action, 1000));
+
+            // Act
+            unmount();
+
+            // Assert
+            expect(action).not.toHaveBeenCalled();
+        });
+    });
+
+    describe("SchedulePolicy.OnDemand", () => {
+        it("should not set the timer on creation", () => {
+            // Arrange
+            const {result} = renderHook(() =>
+                useTimeout(() => {}, 1000, {
+                    schedulePolicy: SchedulePolicy.OnDemand,
+                }),
+            );
+
+            // Act
+
+            // Assert
+            expect(result.current.isSet).toBe(false);
+        });
+
+        it("should not call action after timeoutMs if the timer hasn't been set", () => {
+            // Arrange
+            const action = jest.fn();
+            renderHook(() =>
+                useTimeout(action, 1000, {
+                    schedulePolicy: SchedulePolicy.OnDemand,
+                }),
+            );
+
+            // Act
+            act(() => {
+                jest.advanceTimersByTime(1000);
+            });
+
+            // Assert
+            expect(action).not.toHaveBeenCalled();
+        });
+
+        it("should call action after timeoutMs if the timer has been set", () => {
+            // Arrange
+            const action = jest.fn();
+            const {result} = renderHook(() =>
+                useTimeout(action, 1000, {
+                    schedulePolicy: SchedulePolicy.OnDemand,
+                }),
+            );
+
+            // Act
+            act(() => {
+                result.current.set();
+            });
+            act(() => {
+                jest.advanceTimersByTime(1000);
+            });
+
+            // Assert
+            expect(action).toHaveBeenCalled();
+        });
+
+        it("should reset the timer after calling set() again", () => {
+            // Arrange
+            const action = jest.fn();
+            const {result} = renderHook(() =>
+                useTimeout(action, 750, {
+                    schedulePolicy: SchedulePolicy.OnDemand,
+                }),
+            );
+
+            // Act
+            act(() => {
+                result.current.set();
+                jest.advanceTimersByTime(501);
+                result.current.set();
+                jest.advanceTimersByTime(501);
+            });
+
+            // Assert
+            expect(action).not.toHaveBeenCalled();
+        });
+
+        it("should call the action after calling set() again", () => {
+            // Arrange
+            const action = jest.fn();
+            const {result} = renderHook(() =>
+                useTimeout(action, 500, {
+                    schedulePolicy: SchedulePolicy.OnDemand,
+                }),
+            );
+
+            // Act
+            act(() => {
+                result.current.set();
+                jest.advanceTimersByTime(501);
+            });
+            act(() => {
+                result.current.set();
+                jest.advanceTimersByTime(501);
+            });
+
+            // Assert
+            expect(action).toHaveBeenCalledTimes(2);
+        });
     });
 });

package/src/hooks/use-interval.ts

@@ -1,36 +1,101 @@
-import {useEffect} from "react";
+import {useEffect, useMemo, useRef} from "react";
+import {ClearPolicy, ActionPolicy} from "../util/policies";
 
-import {useUpdatingRef} from "./internal/use-updating-ref";
+import type {IInterval, HookOptions} from "../util/types";
+
+import Interval from "../util/interval";
 
 /**
- * A simple hook for using `setInterval`.
+ * Hook providing access to a scheduled interval.
  *
- * @param action called every `intervalMs` when `active` is true
- * @param intervalMs the duration between calls to `action`
- * @param active whether or not the interval is active
+ * @param action The action to be invoked each time the interval period has
+ * passed. By default, this will not cause the interval to restart if it
+ * changes. This makes it easier to use with inline lambda functions rather than
+ * requiring consumers to wrap their action in a `useCallback`. To change this
+ * behavior, see the `actionPolicy` option.
+ * @param intervalMs The interval period. If this changes, the interval will
+ * be reset per the `schedulePolicy` option.
+ * @param options Options for the hook.
+ * @param options.actionPolicy Determines how the action is handled when it
+ * changes. By default, the action is replaced but the interval is not reset,
+ * and the updated action will be invoked when the interval next fires.
+ * If you want to reset the interval when the action changes, use
+ * `ActionPolicy.Reset`.
+ * @param options.clearPolicy Determines how the interval is cleared when the
+ * component is unmounted or the interval is recreated. By default, the
+ * interval is cleared immediately. If you want to let the interval run to
+ * completion, use `ClearPolicy.Resolve`. This is NOT applied if the interval
+ * is cleared manually via the `clear()` method on the returned API.
+ * @param options.schedulePolicy Determines when the interval is scheduled.
+ * By default, the interval is scheduled immediately. If you want to delay
+ * scheduling the interval, use `SchedulePolicy.OnDemand`.
+ * @returns An `IInterval` API for interacting with the given interval. This
+ * API is a no-op if called when not mounted. This means that any calls prior
+ * to mounting or after unmounting will not have any effect.
  */
 export function useInterval(
     action: () => unknown,
     intervalMs: number,
-    active: boolean,
-) {
-    // We using a ref instead of a callback for `action` to avoid resetting
-    // the interval whenever the `action` changes.
-    const actionRef = useUpdatingRef(action);
+    options: HookOptions = {},
+): IInterval {
+    const {actionPolicy, clearPolicy, schedulePolicy} = options;
+    const actionProxyRef = useRef<() => unknown>(action);
+    const intervalRef = useRef<IInterval | null>(null);
 
-    useEffect(() => {
-        if (active) {
-            const intervalId = setInterval(() => {
-                actionRef.current();
-            }, intervalMs);
-
-            return () => {
-                clearInterval(intervalId);
-            };
+    // Since we are passing our proxy function to the interval instance,
+    // it's check that the action is a function will never fail. So, we have to
+    // do that check ourselves, and we do it here.
+    if (typeof action !== "function") {
+        throw new Error("Action must be a function");
+    }
+
+    // If we're rendered with an updated action, we want to update the ref
+    // so the existing interval gets the new action, and then reset the
+    // interval if our action policy calls for it.
+    if (action !== actionProxyRef.current) {
+        actionProxyRef.current = action;
+        if (actionPolicy === ActionPolicy.Reset) {
+            intervalRef.current?.set();
         }
-        // actionRef isn't actually required, but react-hooks/exhaustive-deps
-        // doesn't recognize it as a ref and thus complains if it isn't in the
-        // deps list.  It isn't a big deal though since the value ofactionRef
-        // never changes (only its contents do).
-    }, [intervalMs, active, actionRef]);
+    }
+
+    // This effect updates the interval when the intervalMs, clearPolicy,
+    // or schedulePolicy changes.
+    useEffect(() => {
+        // Make a new interval.
+        intervalRef.current = new Interval(
+            () => {
+                actionProxyRef.current?.();
+            },
+            intervalMs,
+            schedulePolicy,
+        );
+
+        // Clear the interval when the effect is cleaned up, if necessary,
+        // making sure to use the clear policy.
+        return () => {
+            intervalRef.current?.clear(clearPolicy);
+            intervalRef.current = null;
+        };
+    }, [intervalMs, clearPolicy, schedulePolicy]);
+
+    // This is the API we expose to the consumer. We expose this rather than
+    // the interval instance itself so that the API we give back is stable
+    // even if the underlying interval instance changes.
+    const externalApi = useMemo(
+        () => ({
+            set: () => {
+                intervalRef.current?.set();
+            },
+            clear: (policy?: ClearPolicy) => {
+                intervalRef.current?.clear(policy);
+            },
+            get isSet() {
+                return intervalRef.current?.isSet ?? false;
+            },
+        }),
+        [],
+    );
+
+    return externalApi;
 }