@khanacademy/wonder-blocks-timing 5.0.1 → 5.0.2

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

@@ -1,489 +0,0 @@
-import {renderHook, act} from "@testing-library/react-hooks";
-import {SchedulePolicy, ClearPolicy, ActionPolicy} from "../../util/policies";
-
-import {useTimeout} from "../use-timeout";
-
-describe("useTimeout", () => {
-    beforeEach(() => {
-        jest.useFakeTimers();
-    });
-
-    afterEach(() => {
-        jest.restoreAllMocks();
-    });
-
-    it("throws if the action is not a function", () => {
-        // Arrange
-
-        // Act
-        const {result} = renderHook(() => useTimeout(null as any, 1000));
-
-        // Assert
-        expect(result.error).toEqual(Error("Action must be a function"));
-    });
-
-    it("throws if the period is less than 0", () => {
-        // Arrange
-
-        // Act
-        const {result} = renderHook(() => useTimeout(() => {}, -1));
-
-        // Assert
-        expect(result.error).toEqual(Error("Timeout period must be >= 0"));
-    });
-
-    it("should return an ITimeout", () => {
-        // Arrange
-        const {result} = renderHook(() => useTimeout(() => {}, 1000));
-
-        // Act
-
-        // Assert
-        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 call the action before unmounting", () => {
-        // Arrange
-        const action = jest.fn();
-        const {unmount} = renderHook(() =>
-            useTimeout(action, 1000, {
-                clearPolicy: ClearPolicy.Resolve,
-            }),
-        );
-
-        // Act
-        act(() => {
-            unmount();
-        });
-
-        // Assert
-        expect(action).toHaveBeenCalled();
-    });
-
-    it("should call the current action", () => {
-        // Arrange
-        const action1 = jest.fn();
-        const action2 = jest.fn();
-        const {rerender} = renderHook(
-            ({action}: any) => useTimeout(action, 500),
-            {
-                initialProps: {action: action1},
-            },
-        );
-
-        // Act
-        rerender({action: action2});
-        jest.advanceTimersByTime(501);
-
-        // Assert
-        expect(action2).toHaveBeenCalledTimes(1);
-    });
-
-    it("should only call setTimeout once even if action changes", () => {
-        // Arrange
-        const timeoutSpy = jest.spyOn(global, "setTimeout");
-        const action1 = jest.fn();
-        const action2 = jest.fn();
-        const {rerender} = renderHook(
-            ({action}: any) => useTimeout(action, 500),
-            {
-                initialProps: {action: action1},
-            },
-        );
-        // Act
-        rerender({action: action2});
-
-        // Assert
-        expect(timeoutSpy).toHaveBeenCalledOnce();
-    });
-
-    it("should not reset the timeout if the action changes", () => {
-        // Arrange
-        const action1 = jest.fn();
-        const action2 = jest.fn();
-        const {rerender} = renderHook(
-            ({action}: any) => useTimeout(action, 500),
-            {
-                initialProps: {action: action1},
-            },
-        );
-
-        // Act
-        jest.advanceTimersByTime(250);
-        rerender({action: action2});
-        jest.advanceTimersByTime(251);
-
-        // Assert
-        expect(action1).not.toHaveBeenCalled();
-        expect(action2).toHaveBeenCalledTimes(1);
-    });
-
-    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(
-            ({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},
-            },
-        );
-
-        // Act
-        rerender({timeoutMs: 1000});
-
-        // Assert
-        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,101 +0,0 @@
-import {useEffect, useMemo, useRef} from "react";
-import {ClearPolicy, ActionPolicy} from "../util/policies";
-
-import type {IInterval, HookOptions} from "../util/types";
-
-import Interval from "../util/interval";
-
-/**
- * Hook providing access to a scheduled interval.
- *
- * @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,
-    options: HookOptions = {},
-): IInterval {
-    const {actionPolicy, clearPolicy, schedulePolicy} = options;
-    const actionProxyRef = useRef<() => unknown>(action);
-    const intervalRef = useRef<IInterval | null>(null);
-
-    // 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();
-        }
-    }
-
-    // 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;
-}

package/src/hooks/use-timeout.ts

@@ -1,101 +0,0 @@
-import {useEffect, useMemo, useRef} from "react";
-import {ClearPolicy, ActionPolicy} from "../util/policies";
-
-import type {ITimeout, HookOptions} from "../util/types";
-
-import Timeout from "../util/timeout";
-
-/**
- * Hook providing access to a scheduled timeout.
- *
- * @param action The action to be invoked when the timeout period has
- * passed. By default, this will not cause the timeout 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 timeoutMs The timeout period. If this changes, the timeout 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 timeout is not reset,
- * and the updated action will be invoked when the timeout next fires.
- * If you want to reset the timeout when the action changes, use
- * `ActionPolicy.Reset`.
- * @param options.clearPolicy Determines how the timeout is cleared when the
- * component is unmounted or the timeout is recreated. By default, the
- * timeout is cleared immediately. If you want to let the timeout run to
- * completion, use `ClearPolicy.Resolve`. This is NOT applied if the timeout
- * is cleared manually via the `clear()` method on the returned API.
- * @param options.schedulePolicy Determines when the timeout is scheduled.
- * By default, the timeout is scheduled immediately. If you want to delay
- * scheduling the timeout, use `SchedulePolicy.OnDemand`.
- * @returns An `ITimeout` API for interacting with the given timeout. 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 useTimeout(
-    action: () => unknown,
-    timeoutMs: number,
-    options: HookOptions = {},
-): ITimeout {
-    const {actionPolicy, clearPolicy, schedulePolicy} = options;
-    const actionProxyRef = useRef<() => unknown>(action);
-    const timeoutRef = useRef<ITimeout | null>(null);
-
-    // Since we are passing our proxy function to the timeout 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 timeout gets the new action, and then reset the
-    // timeout if our action policy calls for it.
-    if (action !== actionProxyRef.current) {
-        actionProxyRef.current = action;
-        if (actionPolicy === ActionPolicy.Reset) {
-            timeoutRef.current?.set();
-        }
-    }
-
-    // This effect updates the timeout when the timeoutMs, clearPolicy,
-    // or schedulePolicy changes.
-    useEffect(() => {
-        // Make a new timeout.
-        timeoutRef.current = new Timeout(
-            () => {
-                actionProxyRef.current?.();
-            },
-            timeoutMs,
-            schedulePolicy,
-        );
-
-        // Clear the interval when the effect is cleaned up, if necessary,
-        // making sure to use the clear policy.
-        return () => {
-            timeoutRef.current?.clear(clearPolicy);
-            timeoutRef.current = null;
-        };
-    }, [timeoutMs, 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: () => {
-                timeoutRef.current?.set();
-            },
-            clear: (policy?: ClearPolicy) => {
-                timeoutRef.current?.clear(policy);
-            },
-            get isSet() {
-                return timeoutRef.current?.isSet ?? false;
-            },
-        }),
-        [],
-    );
-
-    return externalApi;
-}

package/src/index.ts

@@ -1,17 +0,0 @@
-export type {
-    IAnimationFrame,
-    IInterval,
-    IScheduleActions,
-    ITimeout,
-    WithActionScheduler,
-    WithActionSchedulerProps,
-    WithoutActionScheduler,
-    HookOptions,
-    Options,
-} from "./util/types";
-
-export {SchedulePolicy, ClearPolicy, ActionPolicy} from "./util/policies";
-export {default as ActionSchedulerProvider} from "./components/action-scheduler-provider";
-export {default as withActionScheduler} from "./components/with-action-scheduler";
-export {useInterval} from "./hooks/use-interval";
-export {useTimeout} from "./hooks/use-timeout";