@khanacademy/wonder-blocks-timing 2.0.3 → 2.1.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @khanacademy/wonder-blocks-timing
+
+## 2.1.1
+
+### Patch Changes
+
+-   91cb727c: Remove file extensions from imports
+
+## 2.1.0
+
+### Minor Changes
+
+-   029b4810: Adds `useInterval()` hook that mimics the behavior of `ActionScheduler`'s
+    `interval()` method.
+-   c57cd770: Rename `useInterval` and `useTimeout` to `useScheduledInterval`
+    and `useScheduledTimeout` respectively.
+-   29766c8e: Add `useInterval` and `useTimeout` hooks to provide an API for
+    using intervals and timeouts.

package/dist/es/index.js

@@ -1,5 +1,6 @@
 import _extends from '@babel/runtime/helpers/extends';
-import { Component, forwardRef, createElement, useState, useRef, useEffect, useCallback } from 'react';
+import * as React from 'react';
+import { useRef, useEffect, useState, useCallback } from 'react';
 
 const SchedulePolicy = {
   Immediately: "schedule-immediately",
@@ -10,29 +11,7 @@ const ClearPolicy = {
   Cancel: "cancel-on-clear"
 };
 
-/**
- * Encapsulates everything associated with calling setTimeout/clearTimeout, and
- * managing the lifecycle of that timer, including the ability to resolve or
- * cancel a pending timeout action.
- *
- * @export
- * @class Timeout
- * @implements {ITimeout}
- */
 class Timeout {
-  /**
-   * 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
-   * period has passed.
-   * @param {number} timeoutMs The timeout period.
-   * @param {SchedulePolicy} [schedulePolicy] When SchedulePolicy.Immediately,
-   * the timer is set immediately on instantiation; otherwise, `set` must be
-   * called to set the timeout.
-   * Defaults to `SchedulePolicy.Immediately`.
-   * @memberof Timeout
-   */
   constructor(action, timeoutMs, schedulePolicy = SchedulePolicy.Immediately) {
     if (typeof action !== "function") {
       throw new Error("Action must be a function");
@@ -49,28 +28,10 @@ class Timeout {
       this.set();
     }
   }
-  /**
-   * Determine if the timeout is set or not.
-   *
-   * @returns {boolean} true if the timeout is set (aka pending), otherwise
-   * false.
-   * @memberof Timeout
-   */
-
 
   get isSet() {
     return this._timeoutId != null;
   }
-  /**
-   * Set the timeout.
-   *
-   * If the timeout is pending, this cancels that pending timeout and
-   * sets the timeout afresh. If the timeout is not pending, this
-   * sets a new timeout.
-   *
-   * @memberof Timeout
-   */
-
 
   set() {
     if (this.isSet) {
@@ -79,21 +40,6 @@ class Timeout {
 
     this._timeoutId = setTimeout(() => this.clear(ClearPolicy.Resolve), this._timeoutMs);
   }
-  /**
-   * Clear the set timeout.
-   *
-   * 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
-   * 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 Timeout
-   */
-
 
   clear(policy = ClearPolicy.Cancel) {
     const timeoutId = this._timeoutId;
@@ -112,29 +58,7 @@ class Timeout {
 
 }
 
-/**
- * Encapsulates everything associated with calling setInterval/clearInterval,
- * and managing the lifecycle of that interval. This includes the ability to
- * cancel the interval, and knowing if the interval is active.
- *
- * @export
- * @class Interval
- * @implements {IInterval}
- */
 class Interval {
-  /**
-   * 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
-   * interval period has passed.
-   * @param {number} intervalMs The interval period.
-   * @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, intervalMs, schedulePolicy = SchedulePolicy.Immediately) {
     if (typeof action !== "function") {
       throw new Error("Action must be a function");
@@ -151,26 +75,10 @@ class Interval {
       this.set();
     }
   }
-  /**
-   * Determine if the interval is active or not.
-   *
-   * @returns {boolean} true if the interval is active, otherwise false.
-   * @memberof Interval
-   */
-
 
   get isSet() {
     return this._intervalId != null;
   }
-  /**
-   * Activate the interval.
-   *
-   * If the interval is active, this cancels that interval and starts the
-   * interval afresh. If the interval is not active, this starts it.
-   *
-   * @memberof Interval
-   */
-
 
   set() {
     if (this.isSet) {
@@ -179,21 +87,6 @@ class Interval {
 
     this._intervalId = setInterval(() => this._action(), this._intervalMs);
   }
-  /**
-   * Clear the active interval.
-   *
-   * 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
-   * 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.Cancel) {
     const intervalId = this._intervalId;
@@ -212,27 +105,7 @@ class Interval {
 
 }
 
-/**
- * Encapsulates everything associated with calling requestAnimationFrame/
- * cancelAnimationFrame, and managing the lifecycle of that request, including
- * the ability to resolve or cancel a pending request action.
- *
- * @export
- * @class AnimationFrame
- * @implements {IAnimationFrame}
- */
 class AnimationFrame {
-  /**
-   * Creates an animation frame request that will invoke the given action.
-   * The request is not made until set is called.
-   *
-   * @param {DOMHighResTimeStamp => mixed} action The action to be invoked.
-   * @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, schedulePolicy = SchedulePolicy.Immediately) {
     if (typeof action !== "function") {
       throw new Error("Action must be a function");
@@ -244,28 +117,10 @@ class AnimationFrame {
       this.set();
     }
   }
-  /**
-   * Determine if the request is pending or not.
-   *
-   * @returns {boolean} true if the request is pending, otherwise
-   * false.
-   * @memberof AnimationFrame
-   */
-
 
   get isSet() {
     return this._animationFrameId != null;
   }
-  /**
-   * Make the animation frame request.
-   *
-   * If the request is pending, this cancels that pending request and
-   * makes the request afresh. If the request is not pending, this
-   * makes a new request.
-   *
-   * @memberof AnimationFrame
-   */
-
 
   set() {
     if (this.isSet) {
@@ -274,24 +129,6 @@ class AnimationFrame {
 
     this._animationFrameId = requestAnimationFrame(time => this.clear(ClearPolicy.Resolve, time));
   }
-  /**
-   * Clear the pending request.
-   *
-   * 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
-   * 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(policy = ClearPolicy.Cancel, time) {
     const animationFrameId = this._animationFrameId;
@@ -310,12 +147,6 @@ class AnimationFrame {
 
 }
 
-/**
- * Implements the `IScheduleActions` API to provide timeout, interval, and
- * animation frame support. This is not intended for direct use, but instead
- * is to be used solely by the `ActionSchedulerProvider` to provide an
- * `IScheduleActions` instance.
- */
 class ActionScheduler {
   constructor() {
     this._disabled = false;
@@ -363,11 +194,6 @@ class ActionScheduler {
     this._registeredActions = [];
     registered.forEach(clearFn => clearFn());
   }
-  /**
-   * Prevents this scheduler from creating any additional actions.
-   * This also clears any pending actions.
-   */
-
 
   disable() {
     this._disabled = true;
@@ -385,17 +211,7 @@ ActionScheduler.NoopAction = {
   clear: () => {}
 };
 
-/**
- * A provider component that passes our action scheduling API to its children
- * and ensures that all scheduled actions are cleared on unmount.
- *
- * ```jsx
- * <ActionSchedulerProvider>
- *     {schedule => this.renderThingThatNeedsTimers(schedule)}
- * </ActionSchedulerProvider>
- * ```
- */
-class ActionSchedulerProvider extends Component {
+class ActionSchedulerProvider extends React.Component {
   constructor(...args) {
     super(...args);
     this._actionScheduler = new ActionScheduler();
@@ -414,69 +230,130 @@ class ActionSchedulerProvider extends Component {
 
 }
 
-/**
- * A higher order component that attaches the given component to an
- * `IScheduleActions` instance. Any actions scheduled will automatically be
- * cleared on unmount.
- *
- * @template TOwnProps The own props of the component being rendered, without
- * the additional action scheduler prop. To attach the additional prop to
- * these props use the `WithActionScheduler` type.
- */
 function withActionScheduler(WrappedComponent) {
-  return /*#__PURE__*/forwardRef((props, ref) => /*#__PURE__*/createElement(ActionSchedulerProvider, null, schedule => /*#__PURE__*/createElement(WrappedComponent, _extends({}, props, {
+  return React.forwardRef((props, ref) => React.createElement(ActionSchedulerProvider, null, schedule => React.createElement(WrappedComponent, _extends({}, props, {
     ref: ref,
     schedule: schedule
   }))));
 }
 
-function useTimeout(action, timeoutMs, options) {
+const useUpdatingRef = value => {
+  const ref = useRef(value);
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref;
+};
+
+function useInterval(action, intervalMs, active) {
+  const actionRef = useUpdatingRef(action);
+  useEffect(() => {
+    if (active) {
+      const intervalId = setInterval(() => {
+        actionRef.current();
+      }, intervalMs);
+      return () => {
+        clearInterval(intervalId);
+      };
+    }
+  }, [intervalMs, active, actionRef]);
+}
+
+function useTimeout(action, timeoutMs, active) {
+  const actionRef = useUpdatingRef(action);
+  useEffect(() => {
+    if (active) {
+      const timeoutId = setTimeout(() => {
+        actionRef.current();
+      }, timeoutMs);
+      return () => {
+        clearTimeout(timeoutId);
+      };
+    }
+  }, [timeoutMs, active, actionRef]);
+}
+
+function useScheduledInterval(action, intervalMs, options) {
   var _options$schedulePoli;
 
+  if (typeof action !== "function") {
+    throw new Error("Action must be a function");
+  }
+
+  if (intervalMs < 1) {
+    throw new Error("Interval period must be >= 1");
+  }
+
   const schedulePolicy = (_options$schedulePoli = options == null ? void 0 : options.schedulePolicy) != null ? _options$schedulePoli : SchedulePolicy.Immediately;
   const [isSet, setIsSet] = useState(schedulePolicy === SchedulePolicy.Immediately);
-  const actionRef = useRef(action);
-  const mountedRef = useRef(false);
+  const set = useCallback(() => setIsSet(true), []);
+  const actionRef = useUpdatingRef(action);
+  const clear = useCallback(policy => {
+    var _policy;
+
+    policy = (_policy = policy) != null ? _policy : options == null ? void 0 : options.clearPolicy;
+
+    if (isSet && policy === ClearPolicy.Resolve) {
+      actionRef.current();
+    }
+
+    setIsSet(false);
+  }, [actionRef, isSet, options == null ? void 0 : options.clearPolicy]);
+  const runOnUnmountRef = useUpdatingRef(isSet && (options == null ? void 0 : options.clearPolicy) === ClearPolicy.Resolve);
   useEffect(() => {
-    mountedRef.current = true;
     return () => {
-      mountedRef.current = false;
+      if (runOnUnmountRef.current) {
+        actionRef.current();
+      }
     };
   }, []);
-  useEffect(() => {
-    actionRef.current = action;
-  }, [action]);
-  const clear = useCallback(policy => {
-    if ((policy != null ? policy : options == null ? void 0 : options.clearPolicy) === ClearPolicy.Resolve) {
-      actionRef.current();
-    } // This will cause the useEffect below to re-run
+  useInterval(action, intervalMs, isSet);
+  return {
+    isSet,
+    set,
+    clear
+  };
+}
 
+function useScheduledTimeout(action, timeoutMs, options) {
+  var _options$schedulePoli;
+
+  if (typeof action !== "function") {
+    throw new Error("Action must be a function");
+  }
 
+  if (timeoutMs < 0) {
+    throw new Error("Timeout period must be >= 0");
+  }
+
+  const schedulePolicy = (_options$schedulePoli = options == null ? void 0 : options.schedulePolicy) != null ? _options$schedulePoli : SchedulePolicy.Immediately;
+  const [isSet, setIsSet] = useState(schedulePolicy === SchedulePolicy.Immediately);
+  const set = useCallback(() => setIsSet(true), []);
+  const wrappedAction = useCallback(() => {
     setIsSet(false);
-  }, [options == null ? void 0 : options.clearPolicy]);
-  const set = useCallback(() => {
-    if (isSet) {
-      clear();
-    } // This will cause the useEffect below to re-run
+    action();
+  }, [action]);
+  const actionRef = useUpdatingRef(wrappedAction);
+  const clear = useCallback(policy => {
+    var _policy;
 
+    policy = (_policy = policy) != null ? _policy : options == null ? void 0 : options.clearPolicy;
 
-    setIsSet(true);
-  }, [clear, isSet]);
+    if (isSet && policy === ClearPolicy.Resolve) {
+      actionRef.current();
+    }
+
+    setIsSet(false);
+  }, [actionRef, isSet, options == null ? void 0 : options.clearPolicy]);
+  const runOnUnmountRef = useUpdatingRef(isSet && (options == null ? void 0 : options.clearPolicy) === ClearPolicy.Resolve);
   useEffect(() => {
-    if (isSet && mountedRef.current) {
-      const timeout = window.setTimeout(() => {
+    return () => {
+      if (runOnUnmountRef.current) {
         actionRef.current();
-        setIsSet(false);
-      }, timeoutMs);
-      return () => {
-        window.clearTimeout(timeout);
-
-        if (!mountedRef.current) {
-          clear();
-        }
-      };
-    }
-  }, [clear, isSet, timeoutMs]);
+      }
+    };
+  }, []);
+  useTimeout(wrappedAction, timeoutMs, isSet);
   return {
     isSet,
     set,
@@ -484,4 +361,4 @@ function useTimeout(action, timeoutMs, options) {
   };
 }
 
-export { ClearPolicy, SchedulePolicy, useTimeout, withActionScheduler };
+export { ClearPolicy, SchedulePolicy, useInterval, useScheduledInterval, useScheduledTimeout, useTimeout, withActionScheduler };