@khanacademy/wonder-blocks-timing 1.2.3 → 2.0.3

package/src/util/__tests__/interval.test.js

@@ -1,11 +1,16 @@
 // @flow
 import Interval from "../interval.js";
+import {SchedulePolicy, ClearPolicy} from "../policies.js";
 
 describe("Interval", () => {
     beforeEach(() => {
         jest.useFakeTimers();
     });
 
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
     describe("constructor", () => {
         it("creates instance", () => {
             // Arrange
@@ -41,22 +46,27 @@ describe("Interval", () => {
             );
         });
 
-        it("sets an interval when autoSchedule is true", () => {
+        it("sets an interval when schedule policy is SchedulePolicy.Immediately", () => {
             // Arrange
+            const intervalSpy = jest.spyOn(global, "setInterval");
 
             // Act
             // eslint-disable-next-line no-new
-            new Interval(() => {}, 1000, true);
+            new Interval(() => {}, 1000, SchedulePolicy.Immediately);
 
             // Assert
-            expect(setInterval).toHaveBeenCalledTimes(1);
+            expect(intervalSpy).toHaveBeenCalledTimes(1);
         });
     });
 
     describe("isSet", () => {
         it("is false when the interval has not been set", () => {
             // Arrange
-            const interval = new Interval(() => {}, 1000, false);
+            const interval = new Interval(
+                () => {},
+                1000,
+                SchedulePolicy.OnDemand,
+            );
 
             // Act
             const result = interval.isSet;
@@ -94,13 +104,18 @@ describe("Interval", () => {
     describe("#set", () => {
         it("should call setInterval", () => {
             // Arrange
-            const interval = new Interval(() => {}, 500);
+            const intervalSpy = jest.spyOn(global, "setInterval");
+            const interval = new Interval(
+                () => {},
+                500,
+                SchedulePolicy.OnDemand,
+            );
 
             // Act
             interval.set();
 
             // Assert
-            expect(setInterval).toHaveBeenNthCalledWith(
+            expect(intervalSpy).toHaveBeenNthCalledWith(
                 1,
                 expect.any(Function),
                 500,
@@ -109,12 +124,15 @@ describe("Interval", () => {
 
         it("should invoke setInterval to call the given action", () => {
             // Arrange
+            const intervalSpy = jest.spyOn(global, "setInterval");
             const action = jest.fn();
-            const interval = new Interval(() => action(), 500);
+            const interval = new Interval(
+                () => action(),
+                500,
+                SchedulePolicy.OnDemand,
+            );
             interval.set();
-            // Flow doesn't know we added jest mocks to this
-            // $FlowFixMe[prop-missing]
-            const scheduledAction = setInterval.mock.calls[0][0];
+            const scheduledAction = intervalSpy.mock.calls[0][0];
 
             // Act
             scheduledAction();
@@ -126,12 +144,16 @@ describe("Interval", () => {
         it("should clear the active interval", () => {
             // Arrange
             const action = jest.fn();
-            const interval = new Interval(() => action(), 500);
+            const interval = new Interval(
+                () => action(),
+                500,
+                SchedulePolicy.OnDemand,
+            );
             interval.set();
 
             // Act
             interval.set();
-            jest.runTimersToTime(501);
+            jest.advanceTimersByTime(501);
 
             // Assert
             expect(action).toHaveBeenCalledTimes(1);
@@ -144,7 +166,7 @@ describe("Interval", () => {
             interval.set();
 
             // Act
-            jest.runTimersToTime(1501);
+            jest.advanceTimersByTime(1501);
 
             // Assert
             expect(action).toHaveBeenCalledTimes(3);
@@ -160,47 +182,51 @@ describe("Interval", () => {
 
             // Act
             interval.clear();
-            jest.runTimersToTime(501);
+            jest.advanceTimersByTime(501);
 
             // Assert
             expect(action).not.toHaveBeenCalled();
         });
 
-        it("should invoke the action if resolve is true", () => {
+        it("should invoke the action if clear policy is ClearPolicy.Resolve", () => {
             // Arrange
             const action = jest.fn();
             const interval = new Interval(action, 500);
             interval.set();
 
             // Act
-            interval.clear(true);
-            jest.runTimersToTime(501);
+            interval.clear(ClearPolicy.Resolve);
+            jest.advanceTimersByTime(501);
 
             // Assert
             expect(action).toHaveBeenCalledTimes(1);
         });
 
-        it("should not invoke the action if resolve is false", () => {
+        it("should not invoke the action if clear policy is ClearPolicy.Cancel", () => {
             // Arrange
             const action = jest.fn();
-            const interval = new Interval(action, 500, true);
+            const interval = new Interval(
+                action,
+                500,
+                SchedulePolicy.Immediately,
+            );
 
             // Act
-            interval.clear(false);
-            jest.runTimersToTime(501);
+            interval.clear(ClearPolicy.Cancel);
+            jest.advanceTimersByTime(501);
 
             // Assert
             expect(action).not.toHaveBeenCalled();
         });
 
-        it("should not invoke the action if interval is inactive", () => {
+        it("should not invoke the action if interval is inactive and clear policy is ClearPolicy.Resolve", () => {
             // Arrange
             const action = jest.fn();
-            const interval = new Interval(action, 500, false);
+            const interval = new Interval(action, 500, SchedulePolicy.OnDemand);
 
             // Act
-            interval.clear(true);
-            jest.runTimersToTime(501);
+            interval.clear(ClearPolicy.Resolve);
+            jest.advanceTimersByTime(501);
 
             // Assert
             expect(action).not.toHaveBeenCalled();

package/src/util/__tests__/timeout.test.js

@@ -1,11 +1,16 @@
 // @flow
 import Timeout from "../timeout.js";
+import {SchedulePolicy, ClearPolicy} from "../policies.js";
 
 describe("Timeout", () => {
     beforeEach(() => {
         jest.useFakeTimers();
     });
 
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
     describe("constructor", () => {
         it("creates instance", () => {
             // Arrange
@@ -41,22 +46,23 @@ describe("Timeout", () => {
             );
         });
 
-        it("sets a timeout when autoSchedule is true", () => {
+        it("sets a timeout when schedule policy is SchedulePolicy.Immediately", () => {
             // Arrange
+            const timeoutSpy = jest.spyOn(global, "setTimeout");
 
             // Act
             // eslint-disable-next-line no-new
-            new Timeout(() => {}, 0, true);
+            new Timeout(() => {}, 0, SchedulePolicy.Immediately);
 
             // Assert
-            expect(setTimeout).toHaveBeenCalledTimes(1);
+            expect(timeoutSpy).toHaveBeenCalledTimes(1);
         });
     });
 
     describe("isSet", () => {
         it("is false when the timeout has not been set", () => {
             // Arrange
-            const timeout = new Timeout(() => {}, 0, false);
+            const timeout = new Timeout(() => {}, 0, SchedulePolicy.OnDemand);
 
             // Act
             const result = timeout.isSet;
@@ -94,13 +100,14 @@ describe("Timeout", () => {
     describe("#set", () => {
         it("should call setTimeout", () => {
             // Arrange
-            const timeout = new Timeout(() => {}, 500, false);
+            const timeoutSpy = jest.spyOn(global, "setTimeout");
+            const timeout = new Timeout(() => {}, 500, SchedulePolicy.OnDemand);
 
             // Act
             timeout.set();
 
             // Assert
-            expect(setTimeout).toHaveBeenNthCalledWith(
+            expect(timeoutSpy).toHaveBeenNthCalledWith(
                 1,
                 expect.any(Function),
                 500,
@@ -109,12 +116,15 @@ describe("Timeout", () => {
 
         it("should invoke setTimeout to call the given action", () => {
             // Arrange
+            const timeoutSpy = jest.spyOn(global, "setTimeout");
             const action = jest.fn();
-            const timeout = new Timeout(() => action(), 500);
+            const timeout = new Timeout(
+                () => action(),
+                500,
+                SchedulePolicy.OnDemand,
+            );
             timeout.set();
-            // Flow doesn't know we added jest mocks to this
-            // $FlowFixMe[prop-missing]
-            const scheduledAction = setTimeout.mock.calls[0][0];
+            const scheduledAction = timeoutSpy.mock.calls[0][0];
 
             // Act
             scheduledAction();
@@ -139,16 +149,17 @@ describe("Timeout", () => {
 
         it("should set the timeout again if it has already executed", () => {
             // Arrange
+            const timeoutSpy = jest.spyOn(global, "setTimeout");
             const action = jest.fn();
-            const timeout = new Timeout(action, 500, false);
+            const timeout = new Timeout(action, 500, SchedulePolicy.OnDemand);
             timeout.set();
-            jest.runOnlyPendingTimers();
+            jest.runAllTimers();
 
             // Act
             timeout.set();
 
             // Assert
-            expect(setTimeout).toHaveBeenCalledTimes(2);
+            expect(timeoutSpy).toHaveBeenCalledTimes(2);
         });
     });
 
@@ -167,27 +178,31 @@ describe("Timeout", () => {
             expect(action).not.toHaveBeenCalled();
         });
 
-        it("should invoke the action if resolve is true", () => {
+        it("should invoke the action if clear policy is ClearPolicy.Resolve", () => {
             // Arrange
             const action = jest.fn();
             const timeout = new Timeout(action, 500);
             timeout.set();
 
             // Act
-            timeout.clear(true);
+            timeout.clear(ClearPolicy.Resolve);
             jest.runOnlyPendingTimers();
 
             // Assert
             expect(action).toHaveBeenCalledTimes(1);
         });
 
-        it("should not invoke the action if resolve is false", () => {
+        it("should not invoke the action if clear policy is ClearPolicy.Cancel", () => {
             // Arrange
             const action = jest.fn();
-            const timeout = new Timeout(action, 500, true);
+            const timeout = new Timeout(
+                action,
+                500,
+                SchedulePolicy.Immediately,
+            );
 
             // Act
-            timeout.clear(false);
+            timeout.clear(ClearPolicy.Cancel);
             jest.runOnlyPendingTimers();
 
             // Assert
@@ -197,10 +212,10 @@ describe("Timeout", () => {
         it("should not invoke the action if timeout is not pending", () => {
             // Arrange
             const action = jest.fn();
-            const timeout = new Timeout(action, 500, false);
+            const timeout = new Timeout(action, 500, SchedulePolicy.OnDemand);
 
             // Act
-            timeout.clear(true);
+            timeout.clear(ClearPolicy.Resolve);
             jest.runOnlyPendingTimers();
 
             // Assert

package/src/util/action-scheduler.js

@@ -8,6 +8,7 @@ import type {
     IInterval,
     ITimeout,
     IScheduleActions,
+    Options,
 } from "./types.js";
 
 /**
@@ -17,38 +18,53 @@ import type {
  * `IScheduleActions` instance.
  */
 export default class ActionScheduler implements IScheduleActions {
+    _disabled: boolean = false;
     _registeredActions: Array<() => void> = [];
+    static +NoopAction: ITimeout & IAnimationFrame & IInterval = {
+        set: () => {},
+        get isSet() {
+            return false;
+        },
+        clear: () => {},
+    };
 
-    timeout(
-        action: () => mixed,
-        period: number,
-        autoSchedule?: boolean,
-        resolveOnClear?: boolean,
-    ): ITimeout {
-        const timeout = new Timeout(action, period, autoSchedule);
-        this._registeredActions.push(() => timeout.clear(resolveOnClear));
+    timeout(action: () => mixed, period: number, options?: Options): ITimeout {
+        if (this._disabled) {
+            return ActionScheduler.NoopAction;
+        }
+        const timeout = new Timeout(action, period, options?.schedulePolicy);
+        this._registeredActions.push(() => timeout.clear(options?.clearPolicy));
         return timeout;
     }
 
     interval(
         action: () => mixed,
         period: number,
-        autoSchedule?: boolean,
-        resolveOnClear?: boolean,
+        options?: Options,
     ): IInterval {
-        const interval = new Interval(action, period, autoSchedule);
-        this._registeredActions.push(() => interval.clear(resolveOnClear));
+        if (this._disabled) {
+            return ActionScheduler.NoopAction;
+        }
+        const interval = new Interval(action, period, options?.schedulePolicy);
+        this._registeredActions.push(() =>
+            interval.clear(options?.clearPolicy),
+        );
         return interval;
     }
 
     animationFrame(
         action: (DOMHighResTimeStamp) => void,
-        autoSchedule?: boolean,
-        resolveOnClear?: boolean,
+        options?: Options,
     ): IAnimationFrame {
-        const animationFrame = new AnimationFrame(action, autoSchedule);
+        if (this._disabled) {
+            return ActionScheduler.NoopAction;
+        }
+        const animationFrame = new AnimationFrame(
+            action,
+            options?.schedulePolicy,
+        );
         this._registeredActions.push(() =>
-            animationFrame.clear(resolveOnClear),
+            animationFrame.clear(options?.clearPolicy),
         );
         return animationFrame;
     }
@@ -58,4 +74,13 @@ export default class ActionScheduler implements IScheduleActions {
         this._registeredActions = [];
         registered.forEach((clearFn) => clearFn());
     }
+
+    /**
+     * Prevents this scheduler from creating any additional actions.
+     * This also clears any pending actions.
+     */
+    disable(): void {
+        this._disabled = true;
+        this.clearAll();
+    }
 }

package/src/util/animation-frame.js

@@ -1,5 +1,10 @@
 // @flow
-import type {IAnimationFrame} from "./types.js";
+import {
+    SchedulePolicy as SchedulePolicies,
+    ClearPolicy as ClearPolicies,
+} from "./policies.js";
+
+import type {IAnimationFrame, SchedulePolicy, ClearPolicy} from "./types.js";
 
 /**
  * Encapsulates everything associated with calling requestAnimationFrame/
@@ -19,14 +24,15 @@ export default class AnimationFrame implements IAnimationFrame {
      * The request is not made until set is called.
      *
      * @param {DOMHighResTimeStamp => mixed} action The action to be invoked.
-     * @param {boolean} [autoSchedule] When true, the request is made immediately on
-     * instanstiation; otherwise, `set` must be called to make the request.
-     * Defaults to `true`.
+     * @param {SchedulePolicy} [schedulePolicy] When SchedulePolicy.Immediately,
+     * the interval is set immediately on instantiation; otherwise, `set` must be
+     * called to set the interval.
+     * Defaults to `SchedulePolicy.Immediately`.
      * @memberof AnimationFrame
      */
     constructor(
         action: (DOMHighResTimeStamp) => mixed,
-        autoSchedule?: boolean,
+        schedulePolicy: SchedulePolicy = SchedulePolicies.Immediately,
     ) {
         if (typeof action !== "function") {
             throw new Error("Action must be a function");
@@ -34,7 +40,7 @@ export default class AnimationFrame implements IAnimationFrame {
 
         this._action = action;
 
-        if (autoSchedule || autoSchedule == null) {
+        if (schedulePolicy === SchedulePolicies.Immediately) {
             this.set();
         }
     }
@@ -61,10 +67,10 @@ export default class AnimationFrame implements IAnimationFrame {
      */
     set(): void {
         if (this.isSet) {
-            this.clear(false);
+            this.clear(ClearPolicies.Cancel);
         }
         this._animationFrameId = requestAnimationFrame((time) =>
-            this.clear(true, time),
+            this.clear(ClearPolicies.Resolve, time),
         );
     }
 
@@ -74,21 +80,28 @@ 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 {boolean} [resolve] When true, if the request was pending when
-     * called, the request action is invoked after cancelling the timeout.
-     * Defaults to false.
+     * @param {ClearPolicy} [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
+     * ClearPolicy.Resolve is specified. Ignored when ClearPolicy.Cancel is
+     * specified.
      *
      * @returns {void}
      * @memberof AnimationFrame
      */
-    clear(resolve?: boolean, time?: DOMHighResTimeStamp): void {
+    clear(
+        policy: ClearPolicy = ClearPolicies.Cancel,
+        time?: DOMHighResTimeStamp,
+    ): void {
         const animationFrameId = this._animationFrameId;
         this._animationFrameId = null;
         if (animationFrameId == null) {
             return;
         }
         cancelAnimationFrame(animationFrameId);
-        if (resolve) {
+        if (policy === ClearPolicies.Resolve) {
             this._action(time || performance.now());
         }
     }

package/src/util/interval.js

@@ -1,5 +1,10 @@
 // @flow
-import type {IInterval} from "./types.js";
+import {
+    SchedulePolicy as SchedulePolicies,
+    ClearPolicy as ClearPolicies,
+} from "./policies.js";
+
+import type {IInterval, SchedulePolicy, ClearPolicy} from "./types.js";
 
 /**
  * Encapsulates everything associated with calling setInterval/clearInterval,
@@ -22,16 +27,16 @@ export default class Interval implements IInterval {
      * @param {() => mixed} action The action to be invoked each time the
      * interval period has passed.
      * @param {number} intervalMs The interval period.
-     * @param {boolean} [autoSchedule] When true, the interval is activated
-     * immediately on instanstiation; otherwise, `set` must be called to
-     * activate the interval.
-     * Defaults to `true`.
+     * @param {SchedulePolicy} [schedulePolicy] When SchedulePolicy.Immediately,
+     * the interval is set immediately on instantiation; otherwise, `set` must be
+     * called to set the interval.
+     * Defaults to `SchedulePolicy.Immediately`.
      * @memberof Interval
      */
     constructor(
         action: () => mixed,
         intervalMs: number,
-        autoSchedule?: boolean,
+        schedulePolicy: SchedulePolicy = SchedulePolicies.Immediately,
     ) {
         if (typeof action !== "function") {
             throw new Error("Action must be a function");
@@ -44,7 +49,7 @@ export default class Interval implements IInterval {
         this._action = action;
         this._intervalMs = intervalMs;
 
-        if (autoSchedule || autoSchedule == null) {
+        if (schedulePolicy === SchedulePolicies.Immediately) {
             this.set();
         }
     }
@@ -69,7 +74,7 @@ export default class Interval implements IInterval {
      */
     set(): void {
         if (this.isSet) {
-            this.clear(false);
+            this.clear(ClearPolicies.Cancel);
         }
         this._intervalId = setInterval(() => this._action(), this._intervalMs);
     }
@@ -80,21 +85,22 @@ export default class Interval implements IInterval {
      * If the interval is active, this cancels that interval. If no interval is
      * pending, this does nothing.
      *
-     * @param {boolean} [resolve] When true, if the interval was active when
-     * called, the interval action is invoked after cancellation. Defaults to
-     * false.
+     * @param {ClearPolicy} [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(resolve?: boolean): void {
+    clear(policy: ClearPolicy = ClearPolicies.Cancel): void {
         const intervalId = this._intervalId;
         this._intervalId = null;
         if (intervalId == null) {
             return;
         }
         clearInterval(intervalId);
-        if (resolve) {
+        if (policy === ClearPolicies.Resolve) {
             this._action();
         }
     }

package/src/util/policies.js

@@ -0,0 +1,10 @@
+// @flow
+export const SchedulePolicy = {
+    Immediately: "schedule-immediately",
+    OnDemand: "schedule-on-demand",
+};
+
+export const ClearPolicy = {
+    Resolve: "resolve-on-clear",
+    Cancel: "cancel-on-clear",
+};