@khanacademy/wonder-blocks-timing 2.0.2 → 2.0.3

package/dist/es/index.js

@@ -1,5 +1,5 @@
 import _extends from '@babel/runtime/helpers/extends';
-import { Component, forwardRef, createElement } from 'react';
+import { Component, forwardRef, createElement, useState, useRef, useEffect, useCallback } from 'react';
 
 const SchedulePolicy = {
   Immediately: "schedule-immediately",
@@ -430,4 +430,58 @@ function withActionScheduler(WrappedComponent) {
   }))));
 }
 
-export { ClearPolicy, SchedulePolicy, withActionScheduler };
+function useTimeout(action, timeoutMs, options) {
+  var _options$schedulePoli;
+
+  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);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  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
+
+
+    setIsSet(false);
+  }, [options == null ? void 0 : options.clearPolicy]);
+  const set = useCallback(() => {
+    if (isSet) {
+      clear();
+    } // This will cause the useEffect below to re-run
+
+
+    setIsSet(true);
+  }, [clear, isSet]);
+  useEffect(() => {
+    if (isSet && mountedRef.current) {
+      const timeout = window.setTimeout(() => {
+        actionRef.current();
+        setIsSet(false);
+      }, timeoutMs);
+      return () => {
+        window.clearTimeout(timeout);
+
+        if (!mountedRef.current) {
+          clear();
+        }
+      };
+    }
+  }, [clear, isSet, timeoutMs]);
+  return {
+    isSet,
+    set,
+    clear
+  };
+}
+
+export { ClearPolicy, SchedulePolicy, useTimeout, withActionScheduler };

package/dist/index.js

@@ -82,7 +82,7 @@ module.exports =
 /******/
 /******/
 /******/ 	// Load entry module and return exports
-/******/ 	return __webpack_require__(__webpack_require__.s = 8);
+/******/ 	return __webpack_require__(__webpack_require__.s = 9);
 /******/ })
 /************************************************************************/
 /******/ ([
@@ -115,7 +115,7 @@ module.exports = require("react");
 /* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "a", function() { return withActionScheduler; });
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(1);
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0___default = /*#__PURE__*/__webpack_require__.n(react__WEBPACK_IMPORTED_MODULE_0__);
-/* harmony import */ var _action_scheduler_provider_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(3);
+/* harmony import */ var _action_scheduler_provider_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(4);
 function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
 
 
@@ -141,11 +141,76 @@ function withActionScheduler(WrappedComponent) {
 /* 3 */
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
+"use strict";
+/* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "a", function() { return useTimeout; });
+/* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(1);
+/* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0___default = /*#__PURE__*/__webpack_require__.n(react__WEBPACK_IMPORTED_MODULE_0__);
+/* harmony import */ var _util_policies_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(0);
+
+
+function useTimeout(action, timeoutMs, options) {
+  var _options$schedulePoli;
+
+  const schedulePolicy = (_options$schedulePoli = options == null ? void 0 : options.schedulePolicy) != null ? _options$schedulePoli : _util_policies_js__WEBPACK_IMPORTED_MODULE_1__[/* SchedulePolicy */ "b"].Immediately;
+  const [isSet, setIsSet] = Object(react__WEBPACK_IMPORTED_MODULE_0__["useState"])(schedulePolicy === _util_policies_js__WEBPACK_IMPORTED_MODULE_1__[/* SchedulePolicy */ "b"].Immediately);
+  const actionRef = Object(react__WEBPACK_IMPORTED_MODULE_0__["useRef"])(action);
+  const mountedRef = Object(react__WEBPACK_IMPORTED_MODULE_0__["useRef"])(false);
+  Object(react__WEBPACK_IMPORTED_MODULE_0__["useEffect"])(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  Object(react__WEBPACK_IMPORTED_MODULE_0__["useEffect"])(() => {
+    actionRef.current = action;
+  }, [action]);
+  const clear = Object(react__WEBPACK_IMPORTED_MODULE_0__["useCallback"])(policy => {
+    if ((policy != null ? policy : options == null ? void 0 : options.clearPolicy) === _util_policies_js__WEBPACK_IMPORTED_MODULE_1__[/* ClearPolicy */ "a"].Resolve) {
+      actionRef.current();
+    } // This will cause the useEffect below to re-run
+
+
+    setIsSet(false);
+  }, [options == null ? void 0 : options.clearPolicy]);
+  const set = Object(react__WEBPACK_IMPORTED_MODULE_0__["useCallback"])(() => {
+    if (isSet) {
+      clear();
+    } // This will cause the useEffect below to re-run
+
+
+    setIsSet(true);
+  }, [clear, isSet]);
+  Object(react__WEBPACK_IMPORTED_MODULE_0__["useEffect"])(() => {
+    if (isSet && mountedRef.current) {
+      const timeout = window.setTimeout(() => {
+        actionRef.current();
+        setIsSet(false);
+      }, timeoutMs);
+      return () => {
+        window.clearTimeout(timeout);
+
+        if (!mountedRef.current) {
+          clear();
+        }
+      };
+    }
+  }, [clear, isSet, timeoutMs]);
+  return {
+    isSet,
+    set,
+    clear
+  };
+}
+
+/***/ }),
+/* 4 */
+/***/ (function(module, __webpack_exports__, __webpack_require__) {
+
 "use strict";
 /* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "a", function() { return ActionSchedulerProvider; });
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(1);
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0___default = /*#__PURE__*/__webpack_require__.n(react__WEBPACK_IMPORTED_MODULE_0__);
-/* harmony import */ var _util_action_scheduler_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(4);
+/* harmony import */ var _util_action_scheduler_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(5);
 
 
 
@@ -179,14 +244,14 @@ class ActionSchedulerProvider extends react__WEBPACK_IMPORTED_MODULE_0__["Compon
 }
 
 /***/ }),
-/* 4 */
+/* 5 */
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
 /* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "a", function() { return ActionScheduler; });
-/* harmony import */ var _timeout_js__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(5);
-/* harmony import */ var _interval_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6);
-/* harmony import */ var _animation_frame_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(7);
+/* harmony import */ var _timeout_js__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(6);
+/* harmony import */ var _interval_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(7);
+/* harmony import */ var _animation_frame_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(8);
 
 
 
@@ -267,7 +332,7 @@ ActionScheduler.NoopAction = {
 };
 
 /***/ }),
-/* 5 */
+/* 6 */
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -378,7 +443,7 @@ class Timeout {
 }
 
 /***/ }),
-/* 6 */
+/* 7 */
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -487,7 +552,7 @@ class Interval {
 }
 
 /***/ }),
-/* 7 */
+/* 8 */
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -594,7 +659,7 @@ class AnimationFrame {
 }
 
 /***/ }),
-/* 8 */
+/* 9 */
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
@@ -607,6 +672,10 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _components_with_action_scheduler_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(2);
 /* harmony reexport (safe) */ __webpack_require__.d(__webpack_exports__, "withActionScheduler", function() { return _components_with_action_scheduler_js__WEBPACK_IMPORTED_MODULE_1__["a"]; });
 
+/* harmony import */ var _hooks_use_timeout_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(3);
+/* harmony reexport (safe) */ __webpack_require__.d(__webpack_exports__, "useTimeout", function() { return _hooks_use_timeout_js__WEBPACK_IMPORTED_MODULE_2__["a"]; });
+
+
 
 
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@khanacademy/wonder-blocks-timing",
   "private": false,
-  "version": "2.0.2",
+  "version": "2.0.3",
   "design": "v1",
   "publishConfig": {
     "access": "public"
@@ -17,9 +17,9 @@
     "react": "16.14.0"
   },
   "devDependencies": {
-    "wb-dev-build-settings": "^0.1.2"
+    "wb-dev-build-settings": "^0.2.0"
   },
   "author": "",
   "license": "MIT",
-  "gitHead": "b6193f70c73e70fbaf76bc688dc69a47fb1d0ef3"
+  "gitHead": "9ebea88533e702011165072f090a377e02fa3f0f"
 }

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

@@ -0,0 +1,336 @@
+// @flow
+import {renderHook, act} from "@testing-library/react-hooks";
+import {SchedulePolicy, ClearPolicy} from "../../util/policies.js";
+
+import {useTimeout} from "../use-timeout.js";
+
+describe("useTimeout", () => {
+    beforeEach(() => {
+        jest.useFakeTimers();
+    });
+
+    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);
+    });
+
+    describe("SchedulePolicies.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(1000);
+            });
+
+            // 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);
+                result.current.set();
+                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}) => useTimeout(action, timeoutMs),
+                {
+                    initialProps: {timeoutMs: 1000},
+                },
+            );
+
+            // Act
+            act(() => {
+                jest.advanceTimersByTime(900);
+            });
+            rerender({timeoutMs: 500});
+            act(() => {
+                jest.advanceTimersByTime(100);
+            });
+
+            // Assert
+            expect(action).not.toHaveBeenCalled();
+            act(() => 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}) => 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}) => 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}) => 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();
+                jest.advanceTimersByTime(1000);
+            });
+
+            // Assert
+            expect(action).not.toHaveBeenCalled();
+        });
+
+        it("should call the action when the timeout is cleared when passing ClearPolicies.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 when the timeout is cleared when using ClearPolicies.Resolve in options", () => {
+            // Arrange
+            const action = jest.fn();
+            const {result} = renderHook(() =>
+                useTimeout(action, 1000, {clearPolicy: ClearPolicy.Resolve}),
+            );
+
+            // Act
+            act(() => {
+                result.current.clear();
+            });
+
+            // Assert
+            expect(action).toHaveBeenCalled();
+        });
+
+        it("should call the action on unmount when using ClearPolicies.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("SchedulePolicies.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();
+                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, 1000, {
+                    schedulePolicy: SchedulePolicy.OnDemand,
+                }),
+            );
+
+            // Act
+            act(() => {
+                result.current.set();
+                jest.advanceTimersByTime(500);
+                result.current.set();
+                jest.advanceTimersByTime(500);
+            });
+
+            // Assert
+            expect(action).not.toHaveBeenCalled();
+        });
+
+        it("should call the action after calling set() again", () => {
+            // Arrange
+            const action = jest.fn();
+            const {result} = renderHook(() =>
+                useTimeout(action, 1000, {
+                    schedulePolicy: SchedulePolicy.OnDemand,
+                }),
+            );
+
+            // Act
+            act(() => {
+                result.current.set();
+                jest.advanceTimersByTime(500);
+                result.current.set();
+                jest.advanceTimersByTime(1000);
+            });
+
+            // Assert
+            expect(action).toHaveBeenCalled();
+        });
+    });
+});

package/src/hooks/use-timeout.js

@@ -0,0 +1,70 @@
+// @flow
+import {useEffect, useState, useCallback, useRef} from "react";
+
+import {
+    SchedulePolicy as SchedulePolicies,
+    ClearPolicy as ClearPolicies,
+} from "../util/policies.js";
+import type {ITimeout, ClearPolicy, Options} from "../util/types.js";
+
+export function useTimeout(
+    action: () => mixed,
+    timeoutMs: number,
+    options?: Options,
+): ITimeout {
+    const schedulePolicy =
+        options?.schedulePolicy ?? SchedulePolicies.Immediately;
+    const [isSet, setIsSet] = useState(
+        schedulePolicy === SchedulePolicies.Immediately,
+    );
+    const actionRef = useRef(action);
+    const mountedRef = useRef(false);
+
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+
+    useEffect(() => {
+        actionRef.current = action;
+    }, [action]);
+
+    const clear = useCallback(
+        (policy?: ClearPolicy) => {
+            if ((policy ?? options?.clearPolicy) === ClearPolicies.Resolve) {
+                actionRef.current();
+            }
+            // This will cause the useEffect below to re-run
+            setIsSet(false);
+        },
+        [options?.clearPolicy],
+    );
+
+    const set = useCallback(() => {
+        if (isSet) {
+            clear();
+        }
+        // This will cause the useEffect below to re-run
+        setIsSet(true);
+    }, [clear, isSet]);
+
+    useEffect(() => {
+        if (isSet && mountedRef.current) {
+            const timeout = window.setTimeout(() => {
+                actionRef.current();
+                setIsSet(false);
+            }, timeoutMs);
+
+            return () => {
+                window.clearTimeout(timeout);
+                if (!mountedRef.current) {
+                    clear();
+                }
+            };
+        }
+    }, [clear, isSet, timeoutMs]);
+
+    return {isSet, set, clear};
+}

package/src/hooks/use-timeout.stories.mdx

@@ -0,0 +1,152 @@
+import {Meta, Story, Source, Canvas} from "@storybook/addon-docs";
+
+import {Body, HeadingSmall} from "@khanacademy/wonder-blocks-typography";
+import {View} from "@khanacademy/wonder-blocks-core";
+import Button from "@khanacademy/wonder-blocks-button";
+
+import {ClearPolicy, SchedulePolicy} from "../util/policies.js";
+import {useTimeout} from "./use-timeout.js";
+
+<Meta
+    title="Timing/useTimeout"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# `useTimeout`
+
+`useTimeout` is a hook that provides a convenient API for setting and clearing
+a timeout. It is defined as follows:
+
+```ts
+function useTimeout(
+    action: () => mixed,
+    timeoutMs: number,
+    options?: {|
+        schedulePolicy?: "schedule-immediately" | "schedule-on-demand",
+        clearPolicy?: "resolve-on-clear" | "cancel-on-clear",
+    |},
+): ITimeout;
+
+interface ITimeout {
+    get isSet(): boolean;
+    set(): void;
+    clear(policy?: ClearPolicy): void;
+}
+```
+
+By default the timeout will be set immediately up creation. The `options` parameter can
+be used to control when when the timeout is schedule and whether or not `action` should be
+called when the timeout is cleared.
+
+Notes:
+
+-   Because `clear` takes a param, it's import that you don't pass it directly to an event handler,
+    e.g. `<Button onClick={clear} />` will not work as expected.
+-   Calling `set` after the timeout has expired will restart the timeout.
+-   Updating the second paramter, `timeoutMs`, will also restart the timeout.
+-   When the component using this hooks is unmounted, the timeout will automatically be cleared.
+-   Calling `set` after the timeout is set but before it expires means that the timeout will be
+    reset and will call `action`, `timeoutMs` after the most recent call to `set` was made.
+
+export const Immediately = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const callback = React.useCallback(() => {
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    const {isSet, set, clear} = useTimeout(callback, 1000);
+    return (
+        <View>
+            <View>isSet = {isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={set}>Set timeout</Button>
+                <Button onClick={clear}>Clear timeout</Button>
+            </View>
+        </View>
+    );
+};
+
+<Canvas>
+    <Story name="Immediately">
+        <Immediately />
+    </Story>
+</Canvas>
+
+```jsx
+const Immediately = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const callback = React.useCallback(() => {
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    const {isSet, set, clear} = useTimeout(callback, 1000);
+    return (
+        <View>
+            <View>isSet = {isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={() => set()}>Set timeout</Button>
+                <Button onClick={() => clear()}>Clear timeout</Button>
+            </View>
+        </View>
+    );
+};
+```
+
+export const OnDemandAndResolveOnClear = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const callback = React.useCallback(() => {
+        console.log("action called");
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    const {isSet, set, clear} = useTimeout(callback, 1000, {
+        clearPolicy: ClearPolicy.Resolve,
+        schedulePolicy: SchedulePolicy.OnDemand,
+    });
+    return (
+        <View>
+            <View>isSet = {isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={() => set()}>Set timeout</Button>
+                <Button onClick={() => clear()}>Clear timeout</Button>
+            </View>
+        </View>
+    );
+};
+
+<Canvas>
+    <Story name="OnDemandAndResolveOnClear">
+        <OnDemandAndResolveOnClear />
+    </Story>
+</Canvas>
+
+```jsx
+const OnDemandAndResolveOnClear = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const callback = React.useCallback(() => {
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    const {isSet, set, clear} = useTimeout(
+        callback,
+        1000,
+        {
+            clearPolicy: ClearPolicy.Resolve,
+            schedulePolicy: SchedulePolicy.OnDemand,
+        },
+    );
+    return (
+        <View>
+            <View>isSet = {isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={() => set()}>Set timeout</Button>
+                <Button onClick={() => clear()}>Clear timeout</Button>
+            </View>
+        </View>
+    );
+};
+```

package/src/index.js

@@ -21,3 +21,4 @@ export type {
 
 export {SchedulePolicy, ClearPolicy} from "./util/policies.js";
 export {default as withActionScheduler} from "./components/with-action-scheduler.js";
+export {useTimeout} from "./hooks/use-timeout.js";

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

@@ -9,14 +9,12 @@ describe("AnimationFrame", () => {
         // Jest doesn't fake out the animation frame API, so we're going to do
         // 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((fn, ...args) => setTimeout(fn, 0));
-        jest.spyOn(
-            global,
-            "cancelAnimationFrame",
-        ).mockImplementation((id, ...args) => clearTimeout(id));
+        jest.spyOn(global, "requestAnimationFrame").mockImplementation(
+            (fn, ...args) => setTimeout(fn, 0),
+        );
+        jest.spyOn(global, "cancelAnimationFrame").mockImplementation(
+            (id, ...args) => clearTimeout(id),
+        );
     });
 
     afterEach(() => {

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

@@ -7,6 +7,10 @@ describe("Interval", () => {
         jest.useFakeTimers();
     });
 
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
     describe("constructor", () => {
         it("creates instance", () => {
             // Arrange
@@ -44,13 +48,14 @@ describe("Interval", () => {
 
         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, SchedulePolicy.Immediately);
 
             // Assert
-            expect(setInterval).toHaveBeenCalledTimes(1);
+            expect(intervalSpy).toHaveBeenCalledTimes(1);
         });
     });
 
@@ -99,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,
@@ -114,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();
@@ -131,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);
@@ -149,7 +166,7 @@ describe("Interval", () => {
             interval.set();
 
             // Act
-            jest.runTimersToTime(1501);
+            jest.advanceTimersByTime(1501);
 
             // Assert
             expect(action).toHaveBeenCalledTimes(3);
@@ -165,7 +182,7 @@ describe("Interval", () => {
 
             // Act
             interval.clear();
-            jest.runTimersToTime(501);
+            jest.advanceTimersByTime(501);
 
             // Assert
             expect(action).not.toHaveBeenCalled();
@@ -179,7 +196,7 @@ describe("Interval", () => {
 
             // Act
             interval.clear(ClearPolicy.Resolve);
-            jest.runTimersToTime(501);
+            jest.advanceTimersByTime(501);
 
             // Assert
             expect(action).toHaveBeenCalledTimes(1);
@@ -196,7 +213,7 @@ describe("Interval", () => {
 
             // Act
             interval.clear(ClearPolicy.Cancel);
-            jest.runTimersToTime(501);
+            jest.advanceTimersByTime(501);
 
             // Assert
             expect(action).not.toHaveBeenCalled();
@@ -209,7 +226,7 @@ describe("Interval", () => {
 
             // Act
             interval.clear(ClearPolicy.Resolve);
-            jest.runTimersToTime(501);
+            jest.advanceTimersByTime(501);
 
             // Assert
             expect(action).not.toHaveBeenCalled();

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

@@ -7,6 +7,10 @@ describe("Timeout", () => {
         jest.useFakeTimers();
     });
 
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
     describe("constructor", () => {
         it("creates instance", () => {
             // Arrange
@@ -44,13 +48,14 @@ describe("Timeout", () => {
 
         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, SchedulePolicy.Immediately);
 
             // Assert
-            expect(setTimeout).toHaveBeenCalledTimes(1);
+            expect(timeoutSpy).toHaveBeenCalledTimes(1);
         });
     });
 
@@ -95,13 +100,14 @@ describe("Timeout", () => {
     describe("#set", () => {
         it("should call setTimeout", () => {
             // Arrange
+            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,
@@ -110,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();
@@ -140,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, SchedulePolicy.OnDemand);
             timeout.set();
-            jest.runOnlyPendingTimers();
+            jest.runAllTimers();
 
             // Act
             timeout.set();
 
             // Assert
-            expect(setTimeout).toHaveBeenCalledTimes(2);
+            expect(timeoutSpy).toHaveBeenCalledTimes(2);
         });
     });