@khanacademy/wonder-blocks-timing 4.0.1 → 5.0.0

package/src/hooks/use-timeout.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 {ITimeout, HookOptions} from "../util/types";
+
+import Timeout from "../util/timeout";
 
 /**
- * A simple hook for using `setTimeout`.
+ * Hook providing access to a scheduled timeout.
  *
- * @param action called after `timeoutMs` when `active` is true
- * @param timeoutMs the duration after which `action` is called
- * @param active whether or not the interval is active
+ * @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,
-    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 = {},
+): ITimeout {
+    const {actionPolicy, clearPolicy, schedulePolicy} = options;
+    const actionProxyRef = useRef<() => unknown>(action);
+    const timeoutRef = useRef<ITimeout | null>(null);
 
-    useEffect(() => {
-        if (active) {
-            const timeoutId = setTimeout(() => {
-                actionRef.current();
-            }, timeoutMs);
-
-            return () => {
-                clearTimeout(timeoutId);
-            };
+    // 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();
         }
-        // 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).
-    }, [timeoutMs, active, actionRef]);
+    }
+
+    // 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,13 +1,3 @@
-import type {
-    IAnimationFrame,
-    IInterval,
-    IScheduleActions,
-    ITimeout,
-    WithActionScheduler,
-    WithActionSchedulerProps,
-    WithoutActionScheduler,
-} from "./util/types";
-
 export type {
     IAnimationFrame,
     IInterval,
@@ -16,12 +6,12 @@ export type {
     WithActionScheduler,
     WithActionSchedulerProps,
     WithoutActionScheduler,
-};
+    HookOptions,
+    Options,
+} from "./util/types";
 
-export {SchedulePolicy, ClearPolicy} from "./util/policies";
+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";
-export {useScheduledInterval} from "./hooks/use-scheduled-interval";
-export {useScheduledTimeout} from "./hooks/use-scheduled-timeout";

package/src/util/__tests__/animation-frame.test.ts

@@ -9,8 +9,7 @@ describe("AnimationFrame", () => {
         // it here and map it to timeouts, that way we can use the fake timer
         // API to test our animation frame things.
         jest.spyOn(global, "requestAnimationFrame").mockImplementation(
-            // @ts-expect-error [FEI-5019] - TS2345 - Argument of type '(fn: any, ...args: any) => NodeJS.Timeout' is not assignable to parameter of type '(callback: FrameRequestCallback) => number'.
-            (fn: any, ...args: any) => setTimeout(fn, 0),
+            (fn: any, ...args: any) => setTimeout(fn, 0) as any,
         );
         jest.spyOn(global, "cancelAnimationFrame").mockImplementation(
             (id: any, ...args: any) => clearTimeout(id),
@@ -46,13 +45,14 @@ describe("AnimationFrame", () => {
 
         it("requests an animation frame when schedule policy is SchedulePolicy.Immediately", () => {
             // Arrange
+            const spy = jest.spyOn(global, "requestAnimationFrame");
 
             // Act
             // eslint-disable-next-line no-new
             new AnimationFrame(() => {}, SchedulePolicy.Immediately);
 
             // Assert
-            expect(requestAnimationFrame).toHaveBeenCalledTimes(1);
+            expect(spy).toHaveBeenCalledTimes(1);
         });
     });
 
@@ -98,27 +98,25 @@ describe("AnimationFrame", () => {
     describe("#set", () => {
         it("should call requestAnimationFrame", () => {
             // Arrange
+            const spy = jest.spyOn(global, "requestAnimationFrame");
             const animationFrame = new AnimationFrame(() => {});
 
             // Act
             animationFrame.set();
 
             // Assert
-            expect(requestAnimationFrame).toHaveBeenNthCalledWith(
-                1,
-                expect.any(Function),
-            );
+            expect(spy).toHaveBeenNthCalledWith(1, expect.any(Function));
         });
 
         it("should invoke requestAnimationFrame to call the given action", () => {
             // Arrange
+            const spy = jest.spyOn(global, "requestAnimationFrame");
             const action = jest.fn();
             const animationFrame = new AnimationFrame((time: any) =>
                 action(time),
             );
             animationFrame.set();
-            // @ts-expect-error [FEI-5019] - TS2339 - Property 'mock' does not exist on type '(callback: FrameRequestCallback) => number'.
-            const scheduledAction = requestAnimationFrame.mock.calls[0][0];
+            const scheduledAction = spy.mock.calls[0][0];
 
             // Act
             scheduledAction(2001);
@@ -144,6 +142,7 @@ describe("AnimationFrame", () => {
 
         it("should set the timeout again if it has already executed", () => {
             // Arrange
+            const spy = jest.spyOn(global, "requestAnimationFrame");
             const action = jest.fn();
             const animationFrame = new AnimationFrame(
                 action,
@@ -156,7 +155,7 @@ describe("AnimationFrame", () => {
             animationFrame.set();
 
             // Assert
-            expect(requestAnimationFrame).toHaveBeenCalledTimes(2);
+            expect(spy).toHaveBeenCalledTimes(2);
         });
     });
 

package/src/util/animation-frame.ts

@@ -1,9 +1,6 @@
-import {
-    SchedulePolicy as SchedulePolicies,
-    ClearPolicy as ClearPolicies,
-} from "./policies";
+import {SchedulePolicy, ClearPolicy} from "./policies";
 
-import type {IAnimationFrame, SchedulePolicy, ClearPolicy} from "./types";
+import type {IAnimationFrame} from "./types";
 
 /**
  * Encapsulates everything associated with calling requestAnimationFrame/
@@ -22,8 +19,8 @@ export default class AnimationFrame implements IAnimationFrame {
      * Creates an animation frame request that will invoke the given action.
      * The request is not made until set is called.
      *
-     * @param {(time: DOMHighResTimeStamp) => mixed} action The action to be invoked.
-     * @param {SchedulePolicy} [schedulePolicy] When SchedulePolicy.Immediately,
+     * @param  action The action to be invoked.
+     * @param [schedulePolicy] When SchedulePolicy.Immediately,
      * the interval is set immediately on instantiation; otherwise, `set` must be
      * called to set the interval.
      * Defaults to `SchedulePolicy.Immediately`.
@@ -31,7 +28,7 @@ export default class AnimationFrame implements IAnimationFrame {
      */
     constructor(
         action: (time: DOMHighResTimeStamp) => unknown,
-        schedulePolicy: SchedulePolicy = SchedulePolicies.Immediately,
+        schedulePolicy: SchedulePolicy = SchedulePolicy.Immediately,
     ) {
         if (typeof action !== "function") {
             throw new Error("Action must be a function");
@@ -39,7 +36,7 @@ export default class AnimationFrame implements IAnimationFrame {
 
         this._action = action;
 
-        if (schedulePolicy === SchedulePolicies.Immediately) {
+        if (schedulePolicy === SchedulePolicy.Immediately) {
             this.set();
         }
     }
@@ -66,10 +63,10 @@ export default class AnimationFrame implements IAnimationFrame {
      */
     set(): void {
         if (this.isSet) {
-            this.clear(ClearPolicies.Cancel);
+            this.clear(ClearPolicy.Cancel);
         }
         this._animationFrameId = requestAnimationFrame((time) =>
-            this.clear(ClearPolicies.Resolve, time),
+            this.clear(ClearPolicy.Resolve, time),
         );
     }
 
@@ -79,19 +76,18 @@ export default class AnimationFrame implements IAnimationFrame {
      * If the request is pending, this cancels that pending request without
      * invoking the action. If no request is pending, this does nothing.
      *
-     * @param {ClearPolicy} [policy] When ClearPolicy.Resolve, if the request
+     * @param [policy] When ClearPolicy.Resolve, if the request
      * was set when called, the request action is invoked after cancelling
      * the request; otherwise, the pending action is cancelled.
      * Defaults to `ClearPolicy.Cancel`.
-     * @param {DOMHighResTimeStamp} [time] Timestamp to pass to the action when
+     * @param [time] Timestamp to pass to the action when
      * ClearPolicy.Resolve is specified. Ignored when ClearPolicy.Cancel is
      * specified.
      *
-     * @returns {void}
      * @memberof AnimationFrame
      */
     clear(
-        policy: ClearPolicy = ClearPolicies.Cancel,
+        policy: ClearPolicy = ClearPolicy.Cancel,
         time?: DOMHighResTimeStamp,
     ): void {
         const animationFrameId = this._animationFrameId;
@@ -100,7 +96,7 @@ export default class AnimationFrame implements IAnimationFrame {
             return;
         }
         cancelAnimationFrame(animationFrameId);
-        if (policy === ClearPolicies.Resolve) {
+        if (policy === ClearPolicy.Resolve) {
             this._action(time || performance.now());
         }
     }

package/src/util/interval.ts

@@ -1,9 +1,6 @@
-import {
-    SchedulePolicy as SchedulePolicies,
-    ClearPolicy as ClearPolicies,
-} from "./policies";
+import {SchedulePolicy, ClearPolicy} from "./policies";
 
-import type {IInterval, SchedulePolicy, ClearPolicy} from "./types";
+import type {IInterval} from "./types";
 
 /**
  * Encapsulates everything associated with calling setInterval/clearInterval,
@@ -15,7 +12,7 @@ import type {IInterval, SchedulePolicy, ClearPolicy} from "./types";
  * @implements {IInterval}
  */
 export default class Interval implements IInterval {
-    _intervalId: number | null | undefined;
+    _intervalId: ReturnType<typeof setInterval> | null | undefined;
     _action: () => unknown;
     _intervalMs: number;
 
@@ -23,10 +20,10 @@ export default class Interval implements IInterval {
      * Creates an interval that will invoke the given action after
      * the given period. The interval does not start until set is called.
      *
-     * @param {() => mixed} action The action to be invoked each time the
+     * @param action The action to be invoked each time the
      * interval period has passed.
-     * @param {number} intervalMs The interval period.
-     * @param {SchedulePolicy} [schedulePolicy] When SchedulePolicy.Immediately,
+     * @param intervalMs The interval period.
+     * @param [schedulePolicy] When SchedulePolicy.Immediately,
      * the interval is set immediately on instantiation; otherwise, `set` must be
      * called to set the interval.
      * Defaults to `SchedulePolicy.Immediately`.
@@ -35,7 +32,7 @@ export default class Interval implements IInterval {
     constructor(
         action: () => unknown,
         intervalMs: number,
-        schedulePolicy: SchedulePolicy = SchedulePolicies.Immediately,
+        schedulePolicy: SchedulePolicy = SchedulePolicy.Immediately,
     ) {
         if (typeof action !== "function") {
             throw new Error("Action must be a function");
@@ -48,7 +45,7 @@ export default class Interval implements IInterval {
         this._action = action;
         this._intervalMs = intervalMs;
 
-        if (schedulePolicy === SchedulePolicies.Immediately) {
+        if (schedulePolicy === SchedulePolicy.Immediately) {
             this.set();
         }
     }
@@ -56,7 +53,7 @@ export default class Interval implements IInterval {
     /**
      * Determine if the interval is active or not.
      *
-     * @returns {boolean} true if the interval is active, otherwise false.
+     * @returns true if the interval is active, otherwise false.
      * @memberof Interval
      */
     get isSet(): boolean {
@@ -73,9 +70,8 @@ export default class Interval implements IInterval {
      */
     set(): void {
         if (this.isSet) {
-            this.clear(ClearPolicies.Cancel);
+            this.clear(ClearPolicy.Cancel);
         }
-        // @ts-expect-error [FEI-5019] - TS2322 - Type 'Timer' is not assignable to type 'number'.
         this._intervalId = setInterval(() => this._action(), this._intervalMs);
     }
 
@@ -85,22 +81,21 @@ export default class Interval implements IInterval {
      * If the interval is active, this cancels that interval. If no interval is
      * pending, this does nothing.
      *
-     * @param {ClearPolicy} [policy] When ClearPolicy.Resolve, if the request
+     * @param [policy] When ClearPolicy.Resolve, if the request
      * was set when called, the request action is invoked after cancelling
      * the request; otherwise, the pending action is cancelled.
      * Defaults to `ClearPolicy.Cancel`.
      *
-     * @returns {void}
      * @memberof Interval
      */
-    clear(policy: ClearPolicy = ClearPolicies.Cancel): void {
+    clear(policy: ClearPolicy = ClearPolicy.Cancel): void {
         const intervalId = this._intervalId;
         this._intervalId = null;
         if (intervalId == null) {
             return;
         }
         clearInterval(intervalId);
-        if (policy === ClearPolicies.Resolve) {
+        if (policy === ClearPolicy.Resolve) {
             this._action();
         }
     }

package/src/util/policies.ts

@@ -1,9 +1,14 @@
-export const SchedulePolicy = {
-    Immediately: "schedule-immediately",
-    OnDemand: "schedule-on-demand",
-} as const;
+export enum SchedulePolicy {
+    Immediately = "schedule-immediately",
+    OnDemand = "schedule-on-demand",
+}
 
-export const ClearPolicy = {
-    Resolve: "resolve-on-clear",
-    Cancel: "cancel-on-clear",
-} as const;
+export enum ClearPolicy {
+    Resolve = "resolve-on-clear",
+    Cancel = "cancel-on-clear",
+}
+
+export enum ActionPolicy {
+    Reset = "reset",
+    Passive = "passive",
+}

package/src/util/timeout.ts

@@ -1,9 +1,6 @@
-import {
-    SchedulePolicy as SchedulePolicies,
-    ClearPolicy as ClearPolicies,
-} from "./policies";
+import {SchedulePolicy, ClearPolicy} from "./policies";
 
-import type {ITimeout, SchedulePolicy, ClearPolicy} from "./types";
+import type {ITimeout} from "./types";
 
 /**
  * Encapsulates everything associated with calling setTimeout/clearTimeout, and
@@ -15,7 +12,7 @@ import type {ITimeout, SchedulePolicy, ClearPolicy} from "./types";
  * @implements {ITimeout}
  */
 export default class Timeout implements ITimeout {
-    _timeoutId: number | null | undefined;
+    _timeoutId: ReturnType<typeof setTimeout> | null | undefined;
     _action: () => unknown;
     _timeoutMs: number;
 
@@ -23,10 +20,10 @@ export default class Timeout implements ITimeout {
      * Creates a timeout that will invoke the given action after
      * the given period. The timeout does not start until set is called.
      *
-     * @param {() => mixed} action The action to be invoked when the timeout
+     * @param action The action to be invoked when the timeout
      * period has passed.
-     * @param {number} timeoutMs The timeout period.
-     * @param {SchedulePolicy} [schedulePolicy] When SchedulePolicy.Immediately,
+     * @param timeoutMs The timeout period.
+     * @param [schedulePolicy] When SchedulePolicy.Immediately,
      * the timer is set immediately on instantiation; otherwise, `set` must be
      * called to set the timeout.
      * Defaults to `SchedulePolicy.Immediately`.
@@ -35,7 +32,7 @@ export default class Timeout implements ITimeout {
     constructor(
         action: () => unknown,
         timeoutMs: number,
-        schedulePolicy: SchedulePolicy = SchedulePolicies.Immediately,
+        schedulePolicy: SchedulePolicy = SchedulePolicy.Immediately,
     ) {
         if (typeof action !== "function") {
             throw new Error("Action must be a function");
@@ -48,7 +45,7 @@ export default class Timeout implements ITimeout {
         this._action = action;
         this._timeoutMs = timeoutMs;
 
-        if (schedulePolicy === SchedulePolicies.Immediately) {
+        if (schedulePolicy === SchedulePolicy.Immediately) {
             this.set();
         }
     }
@@ -56,7 +53,7 @@ export default class Timeout implements ITimeout {
     /**
      * Determine if the timeout is set or not.
      *
-     * @returns {boolean} true if the timeout is set (aka pending), otherwise
+     * @returns true if the timeout is set (aka pending), otherwise
      * false.
      * @memberof Timeout
      */
@@ -75,11 +72,10 @@ export default class Timeout implements ITimeout {
      */
     set(): void {
         if (this.isSet) {
-            this.clear(ClearPolicies.Cancel);
+            this.clear(ClearPolicy.Cancel);
         }
-        // @ts-expect-error [FEI-5019] - TS2322 - Type 'Timeout' is not assignable to type 'number'.
         this._timeoutId = setTimeout(
-            () => this.clear(ClearPolicies.Resolve),
+            () => this.clear(ClearPolicy.Resolve),
             this._timeoutMs,
         );
     }
@@ -90,7 +86,7 @@ export default class Timeout implements ITimeout {
      * If the timeout is pending, this cancels that pending timeout without
      * invoking the action. If no timeout is pending, this does nothing.
      *
-     * @param {ClearPolicy} [policy] When ClearPolicy.Resolve, if the request
+     * @param [policy] When ClearPolicy.Resolve, if the request
      * was set when called, the request action is invoked after cancelling
      * the request; otherwise, the pending action is cancelled.
      * Defaults to `ClearPolicy.Cancel`.
@@ -98,14 +94,14 @@ export default class Timeout implements ITimeout {
      * @returns {void}
      * @memberof Timeout
      */
-    clear(policy: ClearPolicy = ClearPolicies.Cancel): void {
+    clear(policy: ClearPolicy = ClearPolicy.Cancel): void {
         const timeoutId = this._timeoutId;
         this._timeoutId = null;
         if (timeoutId == null) {
             return;
         }
         clearTimeout(timeoutId);
-        if (policy === ClearPolicies.Resolve) {
+        if (policy === ClearPolicy.Resolve) {
             this._action();
         }
     }

package/src/util/types.ts

@@ -1,6 +1,4 @@
-export type SchedulePolicy = "schedule-immediately" | "schedule-on-demand";
-
-export type ClearPolicy = "resolve-on-clear" | "cancel-on-clear";
+import * as Policies from "./policies";
 
 /**
  * Encapsulates everything associated with calling setTimeout/clearTimeout, and
@@ -35,14 +33,14 @@ export interface ITimeout {
      * If the timeout is pending, this cancels that pending timeout. If no
      * timeout is pending, this does nothing.
      *
-     * @param {ClearPolicy} [policy] When ClearPolicy.Resolve, if the request
+     * @param [policy] When ClearPolicy.Resolve, if the request
      * was set when called, the request action is invoked after cancelling
      * the request; otherwise, the pending action is cancelled.
      * Defaults to `ClearPolicy.Cancel`.
      *
      * @memberof ITimeout
      */
-    clear(policy?: ClearPolicy): void;
+    clear(policy?: Policies.ClearPolicy): void;
 }
 
 /**
@@ -76,14 +74,14 @@ export interface IInterval {
      * If the interval is active, this cancels that interval. If the interval
      * is not active, this does nothing.
      *
-     * @param {ClearPolicy} [policy] When ClearPolicy.Resolve, if the request
+     * @param [policy] When ClearPolicy.Resolve, if the request
      * was set when called, the request action is invoked after cancelling
      * the request; otherwise, the pending action is cancelled.
      * Defaults to `ClearPolicy.Cancel`.
      *
      * @memberof IInterval
      */
-    clear(policy?: ClearPolicy): void;
+    clear(policy?: Policies.ClearPolicy): void;
 }
 
 /**
@@ -119,19 +117,29 @@ export interface IAnimationFrame {
      * If the request is pending, this cancels that pending request. If no
      * request is pending, this does nothing.
      *
-     * @param {ClearPolicy} [policy] When ClearPolicy.Resolve, if the request
+     * @param [policy] When ClearPolicy.Resolve, if the request
      * was set when called, the request action is invoked after cancelling
      * the request; otherwise, the pending action is cancelled.
      * Defaults to `ClearPolicy.Cancel`.
      *
      * @memberof IAnimationFrame
      */
-    clear(policy?: ClearPolicy): void;
+    clear(policy?: Policies.ClearPolicy): void;
 }
 
+/**
+ * Options for the scheduling APIs.
+ */
 export type Options = {
-    schedulePolicy?: SchedulePolicy;
-    clearPolicy?: ClearPolicy;
+    schedulePolicy?: Policies.SchedulePolicy;
+    clearPolicy?: Policies.ClearPolicy;
+};
+
+/**
+ * Options for the hook variants of our scheduling APIs.
+ */
+export type HookOptions = Options & {
+    actionPolicy?: Policies.ActionPolicy;
 };
 
 /**

package/tsconfig-build.json

@@ -3,9 +3,7 @@
     "extends": "../tsconfig-shared.json",
     "compilerOptions": {
         "outDir": "./dist",
-        "rootDir": "src",
+        "rootDir": "src"
     },
-    "references": [
-        {"path": "../wonder-blocks-button/tsconfig-build.json"},
-    ]
+    "references": []
 }