[set-interval-async] Add types for set-interval-async (#37535)

* [set-interval-async] Add types for set-interval-async

* Add reference directives.

types/set-interval-async/dynamic/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Attempts to execute the given handler at regular intervals, while preventing
+ * multiple concurrent executions. The handler will never be executed concurrently
+ * more than once in any given moment. If the running time of any execution exceeds
+ * the desired interval, the following execution will be scheduled as soon as
+ * possible; ie. immediately after the previous execution concludes.
+ *
+ * @param handler - Handler function to be executed in intervals. May be asynchronous.
+ * @param interval - Interval in milliseconds. Must be at least 10 ms.
+ * @param args - Any number of arguments to pass on to the handler.
+ */
+export function setIntervalAsync(
+  handler: (...args: any[]) => any,
+  interval: number,
+  ...args: any[]
+): SetIntervalAsyncTimer;
+
+/**
+ * Stops an execution cycle started by setIntervalAsync.
+ * Any ongoing function executions will run until completion,
+ * but all future ones will be cancelled.
+ *
+ * @param timer
+ */
+export function clearIntervalAsync(timer: SetIntervalAsyncTimer): Promise<void>;
+
+/**
+ * Error thrown by setIntervalAsync when invalid arguments are provided.
+ */
+export class SetIntervalAsyncError extends Error { constructor(); }
+
+/**
+ * Timer object returned by setIntervalAsync.
+ * Can be used together with clearIntervalAsync to stop execution.
+ */
+export interface SetIntervalAsyncTimer { id: number; }

types/set-interval-async/fixed/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Executes the given handler at fixed intervals, while preventing
+ * multiple concurrent executions. The handler will never be executed
+ * concurrently more than once in any given moment, providing a fixed
+ * time interval between the end of a given execution and the start of
+ * the following one.
+ *
+ * @param handler - Handler function to be executed in intervals. May be asynchronous.
+ * @param interval - Interval in milliseconds. Must be at least 10 ms.
+ * @param args - Any number of arguments to pass on to the handler.
+ */
+export function setIntervalAsync(
+  handler: (...args: any[]) => any,
+  interval: number,
+  ...args: any[]
+): SetIntervalAsyncTimer;
+
+/**
+ * Stops an execution cycle started by setIntervalAsync.
+ * Any ongoing function executions will run until completion,
+ * but all future ones will be cancelled.
+ *
+ * @param timer
+ */
+export function clearIntervalAsync(timer: SetIntervalAsyncTimer): Promise<void>;
+
+/**
+ * Error thrown by setIntervalAsync when invalid arguments are provided.
+ */
+export class SetIntervalAsyncError extends Error { constructor(); }
+
+/**
+ * Timer object returned by setIntervalAsync.
+ * Can be used together with clearIntervalAsync to stop execution.
+ */
+export interface SetIntervalAsyncTimer { id: number; }

types/set-interval-async/index.d.ts

@@ -0,0 +1,90 @@
+// Type definitions for set-interval-async 1.0
+// Project: https://github.com/ealmansi/set-interval-async
+// Definitions by: Emilio Almansi <https://github.com/ealmansi>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 2.1
+
+/// <reference path="./dynamic/index.d.ts" />
+/// <reference path="./fixed/index.d.ts" />
+/// <reference path="./legacy/index.d.ts" />
+
+export as namespace SetIntervalAsync;
+
+export namespace dynamic {
+    /**
+     * Attempts to execute the given handler at regular intervals, while preventing
+     * multiple concurrent executions. The handler will never be executed concurrently
+     * more than once in any given moment. If the running time of any execution exceeds
+     * the desired interval, the following execution will be scheduled as soon as
+     * possible; ie. immediately after the previous execution concludes.
+     *
+     * @param handler - Handler function to be executed in intervals. May be asynchronous.
+     * @param interval - Interval in milliseconds. Must be at least 10 ms.
+     * @param args - Any number of arguments to pass on to the handler.
+     */
+    function setIntervalAsync(
+        handler: (...args: any[]) => any,
+        interval: number,
+        ...args: any[]
+    ): SetIntervalAsyncTimer;
+}
+
+export namespace fixed {
+    /**
+     * Executes the given handler at fixed intervals, while preventing
+     * multiple concurrent executions. The handler will never be executed
+     * concurrently more than once in any given moment, providing a fixed
+     * time interval between the end of a given execution and the start of
+     * the following one.
+     *
+     * @param handler - Handler function to be executed in intervals. May be asynchronous.
+     * @param interval - Interval in milliseconds. Must be at least 10 ms.
+     * @param args - Any number of arguments to pass on to the handler.
+     */
+    function setIntervalAsync(
+        handler: (...args: any[]) => any,
+        interval: number,
+        ...args: any[]
+    ): SetIntervalAsyncTimer;
+}
+
+export namespace legacy {
+    /**
+     * Executes the given handler at fixed intervals; ie. the start time
+     * between consecutive executions is always a fixed amount of time.
+     * If a given execution takes longer than the given time interval to
+     * complete, then the handler will be invoked again without waiting
+     * for the previous one to finish. In this scenario, multiple concurrent
+     * executions can and will ocurr, so this function should only be used
+     * when the given handler is reentrancy-safe.
+     *
+     * @param handler - Handler function to be executed in intervals. May be asynchronous.
+     * @param interval - Interval in milliseconds. Must be at least 10 ms.
+     * @param args - Any number of arguments to pass on to the handler.
+     */
+    function setIntervalAsync(
+        handler: (...args: any[]) => any,
+        interval: number,
+        ...args: any[]
+    ): SetIntervalAsyncTimer;
+}
+
+/**
+ * Stops an execution cycle started by setIntervalAsync.
+ * Any ongoing function executions will run until completion,
+ * but all future ones will be cancelled.
+ *
+ * @param timer
+ */
+export function clearIntervalAsync(timer: SetIntervalAsyncTimer): Promise<void>;
+
+/**
+ * Error thrown by setIntervalAsync when invalid arguments are provided.
+ */
+export class SetIntervalAsyncError extends Error { constructor(); }
+
+/**
+ * Timer object returned by setIntervalAsync.
+ * Can be used together with clearIntervalAsync to stop execution.
+ */
+export interface SetIntervalAsyncTimer { id: number; }

types/set-interval-async/legacy/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Executes the given handler at fixed intervals; ie. the start time
+ * between consecutive executions is always a fixed amount of time.
+ * If a given execution takes longer than the given time interval to
+ * complete, then the handler will be invoked again without waiting
+ * for the previous one to finish. In this scenario, multiple concurrent
+ * executions can and will ocurr, so this function should only be used
+ * when the given handler is reentrancy-safe.
+ *
+ * @param handler - Handler function to be executed in intervals. May be asynchronous.
+ * @param interval - Interval in milliseconds. Must be at least 10 ms.
+ * @param args - Any number of arguments to pass on to the handler.
+ */
+export function setIntervalAsync(
+  handler: (...args: any[]) => any,
+  interval: number,
+  ...args: any[]
+): SetIntervalAsyncTimer;
+
+/**
+ * Stops an execution cycle started by setIntervalAsync.
+ * Any ongoing function executions will run until completion,
+ * but all future ones will be cancelled.
+ *
+ * @param timer
+ */
+export function clearIntervalAsync(timer: SetIntervalAsyncTimer): Promise<void>;
+
+/**
+ * Error thrown by setIntervalAsync when invalid arguments are provided.
+ */
+export class SetIntervalAsyncError extends Error { constructor(); }
+
+/**
+ * Timer object returned by setIntervalAsync.
+ * Can be used together with clearIntervalAsync to stop execution.
+ */
+export interface SetIntervalAsyncTimer { id: number; }

types/set-interval-async/set-interval-async-tests.ts

@@ -0,0 +1,107 @@
+import {
+  setIntervalAsync as setIntervalAsyncD1,
+  clearIntervalAsync as clearIntervalAsyncD1,
+  SetIntervalAsyncError as SetIntervalAsyncErrorD1
+} from 'set-interval-async/dynamic';
+
+import {
+  setIntervalAsync as setIntervalAsyncF1,
+  clearIntervalAsync as clearIntervalAsyncF1,
+  SetIntervalAsyncError as SetIntervalAsyncErrorF1
+} from 'set-interval-async/fixed';
+
+import {
+  setIntervalAsync as setIntervalAsyncL1,
+  clearIntervalAsync as clearIntervalAsyncL1,
+  SetIntervalAsyncError as SetIntervalAsyncErrorL1
+} from 'set-interval-async/legacy';
+
+import {
+  dynamic,
+  fixed,
+  legacy,
+  clearIntervalAsync,
+  SetIntervalAsyncError,
+  SetIntervalAsyncTimer
+} from 'set-interval-async';
+const { setIntervalAsync: setIntervalAsyncD2 } = dynamic;
+const { setIntervalAsync: setIntervalAsyncF2 } = fixed;
+const { setIntervalAsync: setIntervalAsyncL2 } = legacy;
+
+const handler = (...args: any[]) => args[0];
+const asyncHandler = async (...args: any[]) => args[0];
+const interval = 10;
+const args: any[] = ['', 0, {}, null];
+let timer: SetIntervalAsyncTimer;
+
+(async () => {
+  timer = setIntervalAsyncD1(handler, interval, ...args);
+  await clearIntervalAsyncD1(timer);
+  timer = setIntervalAsyncD1(asyncHandler, interval, ...args);
+  await clearIntervalAsyncD1(timer);
+  try {
+    setIntervalAsyncD1(asyncHandler, 0);
+  } catch (err) {
+    if (err instanceof SetIntervalAsyncErrorD1) {
+      // As expected.
+    } else {
+      throw new SetIntervalAsyncErrorD1();
+    }
+  }
+})();
+
+(async () => {
+  timer = setIntervalAsyncF1(handler, interval, ...args);
+  await clearIntervalAsyncF1(timer);
+  timer = setIntervalAsyncF1(asyncHandler, interval, ...args);
+  await clearIntervalAsyncF1(timer);
+  try {
+    setIntervalAsyncF1(asyncHandler, 0);
+  } catch (err) {
+    if (err instanceof SetIntervalAsyncErrorF1) {
+      // As expected.
+    } else {
+      throw new SetIntervalAsyncErrorF1();
+    }
+  }
+})();
+
+(async () => {
+  timer = setIntervalAsyncL1(handler, interval, ...args);
+  await clearIntervalAsyncL1(timer);
+  timer = setIntervalAsyncL1(asyncHandler, interval, ...args);
+  await clearIntervalAsyncL1(timer);
+  try {
+    setIntervalAsyncL1(asyncHandler, 0);
+  } catch (err) {
+    if (err instanceof SetIntervalAsyncErrorL1) {
+      // As expected.
+    } else {
+      throw new SetIntervalAsyncErrorL1();
+    }
+  }
+})();
+
+(async () => {
+  timer = setIntervalAsyncD2(handler, interval, ...args);
+  await clearIntervalAsync(timer);
+  timer = setIntervalAsyncD2(asyncHandler, interval, ...args);
+  await clearIntervalAsync(timer);
+  timer = setIntervalAsyncF2(handler, interval, ...args);
+  await clearIntervalAsync(timer);
+  timer = setIntervalAsyncF2(asyncHandler, interval, ...args);
+  await clearIntervalAsync(timer);
+  timer = setIntervalAsyncL2(handler, interval, ...args);
+  await clearIntervalAsync(timer);
+  timer = setIntervalAsyncL2(asyncHandler, interval, ...args);
+  await clearIntervalAsync(timer);
+  try {
+    setIntervalAsyncD2(asyncHandler, 0);
+  } catch (err) {
+    if (err instanceof SetIntervalAsyncError) {
+      // As expected.
+    } else {
+      throw new SetIntervalAsyncError();
+    }
+  }
+})();

types/set-interval-async/tsconfig.json

@@ -0,0 +1,23 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictFunctionTypes": true,
+        "strictNullChecks": true,
+        "baseUrl": "../",
+        "typeRoots": [
+            "../"
+        ],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "set-interval-async-tests.ts"
+    ]
+}

types/set-interval-async/tslint.json

@@ -0,0 +1 @@
+{ "extends": "dtslint/dt.json" }