@khanacademy/wonder-blocks-timing 5.0.1 → 6.0.0

package/src/util/interval.ts

@@ -1,102 +0,0 @@
-import {SchedulePolicy, ClearPolicy} from "./policies";
-
-import type {IInterval} from "./types";
-
-/**
- * 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}
- */
-export default class Interval implements IInterval {
-    _intervalId: ReturnType<typeof setInterval> | null | undefined;
-    _action: () => unknown;
-    _intervalMs: number;
-
-    /**
-     * Creates an interval that will invoke the given action after
-     * the given period. The interval does not start until set is called.
-     *
-     * @param action The action to be invoked each time the
-     * interval period has passed.
-     * @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`.
-     * @memberof Interval
-     */
-    constructor(
-        action: () => unknown,
-        intervalMs: number,
-        schedulePolicy: SchedulePolicy = SchedulePolicy.Immediately,
-    ) {
-        if (typeof action !== "function") {
-            throw new Error("Action must be a function");
-        }
-
-        if (intervalMs < 1) {
-            throw new Error("Interval period must be >= 1");
-        }
-
-        this._action = action;
-        this._intervalMs = intervalMs;
-
-        if (schedulePolicy === SchedulePolicy.Immediately) {
-            this.set();
-        }
-    }
-
-    /**
-     * Determine if the interval is active or not.
-     *
-     * @returns true if the interval is active, otherwise false.
-     * @memberof Interval
-     */
-    get isSet(): boolean {
-        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(): void {
-        if (this.isSet) {
-            this.clear(ClearPolicy.Cancel);
-        }
-        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 [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 Interval
-     */
-    clear(policy: ClearPolicy = ClearPolicy.Cancel): void {
-        const intervalId = this._intervalId;
-        this._intervalId = null;
-        if (intervalId == null) {
-            return;
-        }
-        clearInterval(intervalId);
-        if (policy === ClearPolicy.Resolve) {
-            this._action();
-        }
-    }
-}

package/src/util/policies.ts

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

package/src/util/timeout.ts

@@ -1,108 +0,0 @@
-import {SchedulePolicy, ClearPolicy} from "./policies";
-
-import type {ITimeout} from "./types";
-
-/**
- * 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}
- */
-export default class Timeout implements ITimeout {
-    _timeoutId: ReturnType<typeof setTimeout> | null | undefined;
-    _action: () => unknown;
-    _timeoutMs: number;
-
-    /**
-     * Creates a timeout that will invoke the given action after
-     * the given period. The timeout does not start until set is called.
-     *
-     * @param action The action to be invoked when the timeout
-     * period has passed.
-     * @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`.
-     * @memberof Timeout
-     */
-    constructor(
-        action: () => unknown,
-        timeoutMs: number,
-        schedulePolicy: SchedulePolicy = SchedulePolicy.Immediately,
-    ) {
-        if (typeof action !== "function") {
-            throw new Error("Action must be a function");
-        }
-
-        if (timeoutMs < 0) {
-            throw new Error("Timeout period must be >= 0");
-        }
-
-        this._action = action;
-        this._timeoutMs = timeoutMs;
-
-        if (schedulePolicy === SchedulePolicy.Immediately) {
-            this.set();
-        }
-    }
-
-    /**
-     * Determine if the timeout is set or not.
-     *
-     * @returns true if the timeout is set (aka pending), otherwise
-     * false.
-     * @memberof Timeout
-     */
-    get isSet(): boolean {
-        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(): void {
-        if (this.isSet) {
-            this.clear(ClearPolicy.Cancel);
-        }
-        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 [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 = ClearPolicy.Cancel): void {
-        const timeoutId = this._timeoutId;
-        this._timeoutId = null;
-        if (timeoutId == null) {
-            return;
-        }
-        clearTimeout(timeoutId);
-        if (policy === ClearPolicy.Resolve) {
-            this._action();
-        }
-    }
-}

package/src/util/types.ts

@@ -1,256 +0,0 @@
-import * as Policies from "./policies";
-
-/**
- * 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
- * @interface ITimeout
- */
-export interface ITimeout {
-    /**
-     * Determine if the timeout is set or not.
-     *
-     * @returns {boolean} true if the timeout is set (aka pending), otherwise
-     * false.
-     * @memberof ITimeout
-     */
-    get isSet(): boolean;
-    /**
-     * Set the timeout.
-     *
-     * If the timeout is pending, this cancels that pending timeout and
-     * starts the timeout afresh. If the timeout is not pending, this
-     * starts the timeout.
-     *
-     * @memberof ITimeout
-     */
-    set(): void;
-    /**
-     * Clear the set timeout.
-     *
-     * If the timeout is pending, this cancels that pending timeout. If no
-     * timeout is pending, this does nothing.
-     *
-     * @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?: Policies.ClearPolicy): void;
-}
-
-/**
- * Encapsulates everything associated with calling setInterval/clearInterval,
- * and managing the lifecycle of that interval, including the ability to resolve
- * or cancel an active interval.
- *
- * @export
- * @interface IInterval
- */
-export interface IInterval {
-    /**
-     * Determine if the interval is active or not.
-     *
-     * @returns {boolean} true if the interval is active, otherwise false.
-     * @memberof IInterval
-     */
-    get isSet(): boolean;
-    /**
-     * Set the interval.
-     *
-     * If the interval is active, this cancels that interval and restarts it
-     * afresh. If the interval is not active, this starts the interval.
-     *
-     * @memberof IInterval
-     */
-    set(): void;
-    /**
-     * Clear the active interval.
-     *
-     * If the interval is active, this cancels that interval. If the interval
-     * is not active, this does nothing.
-     *
-     * @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?: Policies.ClearPolicy): void;
-}
-
-/**
- * Encapsulates everything associated with calling requestAnimationFrame/
- * cancelAnimationFrame, and managing the lifecycle of that request, including
- * the ability to resolve or cancel a pending request.
- *
- * @export
- * @interface IAnimationFrame
- */
-export interface IAnimationFrame {
-    /**
-     * Determine if the request is set or not.
-     *
-     * @returns {boolean} true if the request is set (aka pending), otherwise
-     * false.
-     * @memberof IAnimationFrame
-     */
-    get isSet(): boolean;
-    /**
-     * Set the request.
-     *
-     * If the request is pending, this cancels that pending request and
-     * starts a request afresh. If the request is not pending, this
-     * starts the request.
-     *
-     * @memberof IAnimationFrame
-     */
-    set(): void;
-    /**
-     * Clear the set request.
-     *
-     * If the request is pending, this cancels that pending request. If no
-     * request is pending, this does nothing.
-     *
-     * @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?: Policies.ClearPolicy): void;
-}
-
-/**
- * Options for the scheduling APIs.
- */
-export type Options = {
-    schedulePolicy?: Policies.SchedulePolicy;
-    clearPolicy?: Policies.ClearPolicy;
-};
-
-/**
- * Options for the hook variants of our scheduling APIs.
- */
-export type HookOptions = Options & {
-    actionPolicy?: Policies.ActionPolicy;
-};
-
-/**
- * Provides means to request timeouts, intervals, and animation frames, with
- * additional support for clearing all requested actions.
- *
- * This interface describes a replacement for the `setTimeout`/`clearTimeout`,
- * `setInterval`/`clearInterval` and `requestAnimationFrame`/`cancelAnimationFrame`
- * APIs that supports the ability to easily clear all pending actions.
- *
- * @export
- * @interface IScheduleActions
- */
-export interface IScheduleActions {
-    /**
-     * Request a timeout.
-     *
-     * A timeout will wait for a given period and then invoke a given action.
-     *
-     * @param {() => void} action The action to be invoked when the timeout
-     * period is reached.
-     * @param {number} period The timeout period in milliseconds. The action
-     * will be invoked after this period has passed since the timeout was set.
-     * This value must be greater than or equal to zero.
-     * @param {boolean} [autoSchedule] Whether or not to set the timeout as soon
-     * as this call is made, or wait until `set` is explicitly called. Defaults
-     * to `true`.
-     * @param {boolean} [resolveOnClear] Whether or not the associated action
-     * will be invoked if it is still pending at the point the timeout is
-     * cleared. Defaults to `false`.
-     * @returns {ITimeout} A interface for manipulating the created timeout.
-     * @memberof IScheduleActions
-     */
-    timeout(action: () => unknown, period: number, options?: Options): ITimeout;
-    /**
-     * Request an interval.
-     *
-     * An interval will invoke a given action each time the given period has
-     * passed until the interval is cleared.
-     *
-     * @param {() => void} action The action to be invoked when the interval
-     * period occurs.
-     * @param {number} period The interval period in milliseconds. The action
-     * will be invoked each time this period has passed since the interval was
-     * set or last occurred.
-     * This value must be greater than zero.
-     * @param {boolean} [autoSchedule] Whether or not to set the interval as soon
-     * as this call is made, or wait until `set` is explicitly called. Defaults
-     * to `true`.
-     * @param {boolean} [resolveOnClear] Whether or not the associated action
-     * will be invoked at the point the interval is cleared if the interval
-     * is running at that time. Defaults to `false`.
-     * @returns {IInterval} An interface for manipulating the created interval.
-     * @memberof IScheduleActions
-     */
-    interval(
-        action: () => unknown,
-        period: number,
-        options?: Options,
-    ): IInterval;
-    /**
-     * Request an animation frame.
-     *
-     * An animation frame request tells the browser that you wish to perform an
-     * animation and requests that the browser call a specified function to
-     * update an animation before the next repaint.
-     *
-     * @param {(time: DOMHighResTimeStamp) => void} action The action to be invoked before the repaint.
-     * @param {boolean} [autoSchedule] Whether or not to make the request as soon
-     * as this call is made, or wait until `set` is explicitly called. Defaults
-     * to `true`.
-     * @param {boolean} [resolveOnClear] Whether or not the associated action
-     * will be invoked at the point the request is cleared if it has not yet
-     * executed. Defaults to `false`.
-     * @returns {IAnimationFrame} An interface for manipulating the created
-     * request.
-     * @memberof IScheduleActions
-     */
-    animationFrame(
-        action: (time: DOMHighResTimeStamp) => void,
-        options?: Options,
-    ): IAnimationFrame;
-    /**
-     * Clears all timeouts, intervals, and animation frame requests that were
-     * made with this scheduler.
-     *
-     * @memberof IScheduleActions
-     */
-    clearAll(): void;
-}
-
-/**
- * A props object type that can be spread into the a componenet wrapped with
- * the `withActionScheduler` higher order component.
- */
-export type WithActionSchedulerProps = Readonly<{
-    /**
-     * An instance of the `IScheduleActions` API to use for scheduling
-     * intervals, timeouts, and animation frame requests.
-     */
-    schedule: IScheduleActions;
-}>;
-
-export type WithoutActionScheduler<TProps extends object> = Omit<
-    TProps,
-    "schedule"
->;
-
-/**
- * Extends the given props with props that the `withActionScheduler` higher
- * order component will inject.
- */
-export type WithActionScheduler<TOwnProps extends object> = TOwnProps &
-    WithActionSchedulerProps;

package/src/util/types.typestest.tsx

@@ -1,72 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-/**
- * This file ensures that our TypeScript types are working right.
- */
-import * as React from "react";
-import withActionScheduler from "../components/with-action-scheduler";
-
-import type {WithActionSchedulerProps} from "./types";
-
-/**
- * Test WithActionScheduler and withActionScheduler usage.
- */
-/**
- * Case 1: Correct usage
- * Given a react component with action scheduler props, we receive an
- * abstract component of `OwnProps1`.
- */
-type Props1 = {
-    test: string;
-} & WithActionSchedulerProps;
-
-const InnerComponent1 = (props: Props1): React.ReactElement => (
-    <>{props.test}</>
-);
-
-const HOCComponent1 = withActionScheduler(InnerComponent1);
-
-/**
- * Case 2: Incorrect Usage
- * The withActionScheduler call is returning a component of type OwnProps2; the
- * variable assigned however is incorrectly specified as Props2.
- */
-type Props2 = {
-    test: string;
-} & WithActionSchedulerProps;
-
-const InnerComponent2 = (props: Props2): React.ReactElement => (
-    <>{props.test}</>
-);
-
-/**
- * Cannot assign `withActionScheduler(...)` to `HOCComponent2` because property
- * `schedule` is missing in `OwnProps2` [1] but exists in `WithActionScheduler`
- * [2] in type argument  `Config` [3].
- *
- * $ExpectError
- */
-const HOCComponent2 = withActionScheduler(InnerComponent2);
-
-/**
- * Case 3: Incorrect Usage
- * The withActionScheduler call is being passed a component that isn't set up
- * to be used with it as it doesn't have all the props necessary.
- */
-type Props3 = {
-    test: string;
-} & WithActionSchedulerProps;
-
-const InnerComponent3 = (props: Props3): React.ReactElement => (
-    <>{props.test}</>
-);
-
-const HOCComponent3 = withActionScheduler(
-    /**
-     * Cannot call `withActionScheduler` with `InnerComponent3` bound to
-     * `Component` because property `schedule` is missing in `OwnProps3` [1]
-     * but exists in  `WithActionScheduler` [2] in type argument  `Config` [3].
-     *
-     * $ExpectError
-     */
-    InnerComponent3,
-);

package/tsconfig-build.json

@@ -1,9 +0,0 @@
-{
-    "exclude": ["dist"],
-    "extends": "../tsconfig-shared.json",
-    "compilerOptions": {
-        "outDir": "./dist",
-        "rootDir": "src"
-    },
-    "references": []
-}