diff --git a/types/set-interval-async/dynamic/index.d.ts b/types/set-interval-async/dynamic/index.d.ts new file mode 100644 index 0000000000..f33081ec5a --- /dev/null +++ b/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; + +/** + * 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; } diff --git a/types/set-interval-async/fixed/index.d.ts b/types/set-interval-async/fixed/index.d.ts new file mode 100644 index 0000000000..56588a61ee --- /dev/null +++ b/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; + +/** + * 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; } diff --git a/types/set-interval-async/index.d.ts b/types/set-interval-async/index.d.ts new file mode 100644 index 0000000000..d0905088ad --- /dev/null +++ b/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 +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.1 + +/// +/// +/// + +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; + +/** + * 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; } diff --git a/types/set-interval-async/legacy/index.d.ts b/types/set-interval-async/legacy/index.d.ts new file mode 100644 index 0000000000..895ba3791a --- /dev/null +++ b/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; + +/** + * 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; } diff --git a/types/set-interval-async/set-interval-async-tests.ts b/types/set-interval-async/set-interval-async-tests.ts new file mode 100644 index 0000000000..941a3f872e --- /dev/null +++ b/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(); + } + } +})(); diff --git a/types/set-interval-async/tsconfig.json b/types/set-interval-async/tsconfig.json new file mode 100644 index 0000000000..3645955968 --- /dev/null +++ b/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" + ] +} diff --git a/types/set-interval-async/tslint.json b/types/set-interval-async/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/set-interval-async/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" }