From ab59cfa715a4398d710700c4fbcdd9bb203ee98e Mon Sep 17 00:00:00 2001 From: Dimitri Benin Date: Mon, 1 Apr 2019 10:27:29 +0000 Subject: [PATCH] Refactor TypeScript definition to CommonJS compatible export (#6) --- index.d.ts | 507 ++++++++++++++++++++++++++---------------------- index.js | 1 - index.test-d.ts | 5 +- package.json | 6 +- 4 files changed, 277 insertions(+), 242 deletions(-) diff --git a/index.d.ts b/index.d.ts index fc5e30c..3d8c435 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,71 +1,74 @@ -export interface Options { - /** - * Number of concurrently pending promises. Minimum: `1`. - * - * To run the promises in series, set it to `1`. - * - * When this option is set, the first argument must be an array of promise-returning functions. - * - * @default Infinity - */ - readonly concurrency: number; -} +declare namespace PProgress { + interface Options { + /** + Number of concurrently pending promises. Minimum: `1`. + + To run the promises in series, set it to `1`. -export type PromiseFactory = () => PromiseLike; -export type ProgressNotifier = (progress: number) => void; + When this option is set, the first argument must be an array of promise-returning functions. -export default class PProgress extends Promise { + @default Infinity + */ + readonly concurrency: number; + } + + type PromiseFactory = () => PromiseLike; + type ProgressNotifier = (progress: number) => void; +} + +declare class PProgress extends Promise { /** - * The current progress percentage of the promise as a number between 0 and 1. - */ + The current progress percentage of the promise as a number between 0 and 1. + */ readonly progress: number; /** - * Convenience method to make your promise-returning or async function report progress. - * - * The function you specify will have the `progress()` function appended to its parameters. - * - * @example - * - * import PProgress from 'p-progress'; - * - * const runJob = PProgress.fn(async (name, progress) => { - * const job = new Job(name); - * - * job.on('data', data => { - * progress(data.length / job.totalSize); - * }); - * - * await job.run(); - * }); - * - * (async () => { - * const progressPromise = runJob('Gather rainbows'); - * - * progressPromise.onProgress(console.log); - * //=> 0.09 - * //=> 0.23 - * //=> 0.59 - * //=> 0.75 - * //=> 1 - * - * await progressPromise; - * })(); - */ + Convenience method to make your promise-returning or async function report progress. + + The function you specify will have the `progress()` function appended to its parameters. + + @example + ``` + import PProgress = require('p-progress'); + + const runJob = PProgress.fn(async (name, progress) => { + const job = new Job(name); + + job.on('data', data => { + progress(data.length / job.totalSize); + }); + + await job.run(); + }); + + (async () => { + const progressPromise = runJob('Gather rainbows'); + + progressPromise.onProgress(console.log); + //=> 0.09 + //=> 0.23 + //=> 0.59 + //=> 0.75 + //=> 1 + + await progressPromise; + })(); + ``` + */ static fn( - input: (progress: ProgressNotifier) => PromiseLike + input: (progress: PProgress.ProgressNotifier) => PromiseLike ): () => PProgress; static fn( input: ( parameter1: ParameterType1, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => PromiseLike ): (parameter1: ParameterType1) => PProgress; static fn( input: ( parameter1: ParameterType1, parameter2: ParameterType2, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => PromiseLike ): ( parameter1: ParameterType1, @@ -76,7 +79,7 @@ export default class PProgress extends Promise { parameter1: ParameterType1, parameter2: ParameterType2, parameter3: ParameterType3, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => PromiseLike ): ( parameter1: ParameterType1, @@ -95,7 +98,7 @@ export default class PProgress extends Promise { parameter2: ParameterType2, parameter3: ParameterType3, parameter4: ParameterType4, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => PromiseLike ): ( parameter1: ParameterType1, @@ -117,7 +120,7 @@ export default class PProgress extends Promise { parameter3: ParameterType3, parameter4: ParameterType4, parameter5: ParameterType5, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => PromiseLike ): ( parameter1: ParameterType1, @@ -142,7 +145,7 @@ export default class PProgress extends Promise { parameter4: ParameterType4, parameter5: ParameterType5, parameter6: ParameterType6, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => PromiseLike ): ( parameter1: ParameterType1, @@ -170,7 +173,7 @@ export default class PProgress extends Promise { parameter5: ParameterType5, parameter6: ParameterType6, parameter7: ParameterType7, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => PromiseLike ): ( parameter1: ParameterType1, @@ -201,7 +204,7 @@ export default class PProgress extends Promise { parameter6: ParameterType6, parameter7: ParameterType7, parameter8: ParameterType8, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => PromiseLike ): ( parameter1: ParameterType1, @@ -235,7 +238,7 @@ export default class PProgress extends Promise { parameter7: ParameterType7, parameter8: ParameterType8, parameter9: ParameterType9, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => PromiseLike ): ( parameter1: ParameterType1, @@ -272,7 +275,7 @@ export default class PProgress extends Promise { parameter8: ParameterType8, parameter9: ParameterType9, parameter10: ParameterType10, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => PromiseLike ): ( parameter1: ParameterType1, @@ -291,46 +294,47 @@ export default class PProgress extends Promise { ): (...args: unknown[]) => PProgress; /** - * Convenience method to run multiple promises and get a total progress of all of them. It counts normal promises with progress `0` when pending and progress `1` when resolved. For `PProgress` type promises, it listens to their `onProgress()` method for more fine grained progress reporting. You can mix and match normal promises and `PProgress` promises. - * - * @param promises - Array of promises or promise-returning functions, similar to [p-all](https://github.com/sindresorhus/p-all). - * - * @example - * - * import PProgress from 'p-progress'; - * import delay from 'delay'; - * - * const progressPromise = PProgress.fn(async progress => { - * progress(0.14); - * await delay(52); - * progress(0.37); - * await delay(104); - * progress(0.41); - * await delay(26); - * progress(0.93); - * await delay(55); - * }); - * - * const allProgressPromise = PProgress.all([ - * delay(103), - * progressPromise(), - * delay(55), - * delay(209) - * ]); - * - * (async () => { - * allProgressPromise.onProgress(console.log); - * //=> 0.0925 - * //=> 0.3425 - * //=> 0.5925 - * //=> 0.6025 - * //=> 0.7325 - * //=> 0.9825 - * //=> 1 - * - * await allProgressPromise; - * })(); - */ + Convenience method to run multiple promises and get a total progress of all of them. It counts normal promises with progress `0` when pending and progress `1` when resolved. For `PProgress` type promises, it listens to their `onProgress()` method for more fine grained progress reporting. You can mix and match normal promises and `PProgress` promises. + + @param promises - Array of promises or promise-returning functions, similar to [p-all](https://github.com/sindresorhus/p-all). + + @example + ``` + import PProgress = require('p-progress'); + import delay = require('delay'); + + const progressPromise = PProgress.fn(async progress => { + progress(0.14); + await delay(52); + progress(0.37); + await delay(104); + progress(0.41); + await delay(26); + progress(0.93); + await delay(55); + }); + + const allProgressPromise = PProgress.all([ + delay(103), + progressPromise(), + delay(55), + delay(209) + ]); + + (async () => { + allProgressPromise.onProgress(console.log); + //=> 0.0925 + //=> 0.3425 + //=> 0.5925 + //=> 0.6025 + //=> 0.7325 + //=> 0.9825 + //=> 1 + + await allProgressPromise; + })(); + ``` + */ static all< ValueType1, ValueType2, @@ -344,18 +348,18 @@ export default class PProgress extends Promise { ValueType10 >( promises: [ - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory ], - options: Options + options: PProgress.Options ): PProgress< [ ValueType1, @@ -382,17 +386,17 @@ export default class PProgress extends Promise { ValueType9 >( promises: [ - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory ], - options: Options + options: PProgress.Options ): PProgress< [ ValueType1, @@ -417,16 +421,16 @@ export default class PProgress extends Promise { ValueType8 >( promises: [ - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory ], - options: Options + options: PProgress.Options ): PProgress< [ ValueType1, @@ -449,15 +453,15 @@ export default class PProgress extends Promise { ValueType7 >( promises: [ - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory ], - options: Options + options: PProgress.Options ): PProgress< [ ValueType1, @@ -478,51 +482,51 @@ export default class PProgress extends Promise { ValueType6 >( promises: [ - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory ], - options: Options + options: PProgress.Options ): PProgress< [ValueType1, ValueType2, ValueType3, ValueType4, ValueType5, ValueType6] >; static all( promises: [ - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory ], - options: Options + options: PProgress.Options ): PProgress<[ValueType1, ValueType2, ValueType3, ValueType4, ValueType5]>; static all( promises: [ - PromiseFactory, - PromiseFactory, - PromiseFactory, - PromiseFactory + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory ], - options: Options + options: PProgress.Options ): PProgress<[ValueType1, ValueType2, ValueType3, ValueType4]>; static all( promises: [ - PromiseFactory, - PromiseFactory, - PromiseFactory + PProgress.PromiseFactory, + PProgress.PromiseFactory, + PProgress.PromiseFactory ], - options: Options + options: PProgress.Options ): PProgress<[ValueType1, ValueType2, ValueType3]>; static all( - promises: [PromiseFactory, PromiseFactory], - options: Options + promises: [PProgress.PromiseFactory, PProgress.PromiseFactory], + options: PProgress.Options ): PProgress<[ValueType1, ValueType2]>; static all( - promises: [PromiseFactory], - options: Options + promises: [PProgress.PromiseFactory], + options: PProgress.Options ): PProgress<[ValueType1]>; static all< ValueType1, @@ -537,16 +541,16 @@ export default class PProgress extends Promise { ValueType10 >( promises: [ - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory ] ): PProgress< [ @@ -574,15 +578,15 @@ export default class PProgress extends Promise { ValueType9 >( promises: [ - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory ] ): PProgress< [ @@ -608,14 +612,14 @@ export default class PProgress extends Promise { ValueType8 >( promises: [ - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory ] ): PProgress< [ @@ -639,13 +643,13 @@ export default class PProgress extends Promise { ValueType7 >( promises: [ - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory ] ): PProgress< [ @@ -667,81 +671,112 @@ export default class PProgress extends Promise { ValueType6 >( promises: [ - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory ] ): PProgress< [ValueType1, ValueType2, ValueType3, ValueType4, ValueType5, ValueType6] >; static all( promises: [ - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory ] ): PProgress<[ValueType1, ValueType2, ValueType3, ValueType4, ValueType5]>; static all( promises: [ - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory ] ): PProgress<[ValueType1, ValueType2, ValueType3, ValueType4]>; static all( promises: [ - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory ] ): PProgress<[ValueType1, ValueType2, ValueType3]>; static all( promises: [ - PromiseLike | PromiseFactory, - PromiseLike | PromiseFactory + PromiseLike | PProgress.PromiseFactory, + PromiseLike | PProgress.PromiseFactory ] ): PProgress<[ValueType1, ValueType2]>; static all( - promises: [PromiseLike | PromiseFactory] + promises: [PromiseLike | PProgress.PromiseFactory] ): PProgress<[ValueType1]>; static all( - promises: Iterable>, - options: Options + promises: Iterable>, + options: PProgress.Options ): PProgress; static all( promises: Iterable< - PromiseLike | PromiseFactory + PromiseLike | PProgress.PromiseFactory > ): PProgress; /** - * Same as the [`Promise` constructor](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise). - * - * @param executor - Same as the `Promise` constructor but with an appended `progress` parameter in `executor`. - */ + Same as the [`Promise` constructor](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise). + + @param executor - Same as the `Promise` constructor but with an appended `progress` parameter in `executor`. + + @example + ``` + import PProgress = require('p-progress'); + + const progressPromise = new PProgress((resolve, reject, progress) => { + const job = new Job(); + + job.on('data', data => { + progress(data.length / job.totalSize); + }); + + job.on('finish', resolve); + job.on('error', reject); + }); + + (async () => { + progressPromise.onProgress(progress => { + console.log(`${progress * 100}%`); + //=> 9% + //=> 23% + //=> 59% + //=> 75% + //=> 100% + }); + + await progressPromise; + })(); + ``` + */ constructor( /** - * @param progress - Call this with progress updates. It expects a number between 0 and 1. - * - * Multiple calls with the same number will result in only one `onProgress()` event. - * - * Progress percentage `1` is reported for you when the promise resolves. If you set it yourself, it will simply be ignored. - */ + @param progress - Call this with progress updates. It expects a number between 0 and 1. + + Multiple calls with the same number will result in only one `onProgress()` event. + + Progress percentage `1` is reported for you when the promise resolves. If you set it yourself, it will simply be ignored. + */ executor: ( - resolve: (value?: T | PromiseLike) => void, + resolve: (value?: ValueType | PromiseLike) => void, reject: (reason?: unknown) => void, - progress: ProgressNotifier + progress: PProgress.ProgressNotifier ) => void ); /** - * Accepts a function that gets `instance.progress` as an argument and is called for every progress event. - */ - onProgress(callback: ProgressNotifier): void; + Accepts a function that gets `instance.progress` as an argument and is called for every progress event. + */ + onProgress(callback: PProgress.ProgressNotifier): void; } + +export = PProgress; diff --git a/index.js b/index.js index 0d08f85..3b42437 100644 --- a/index.js +++ b/index.js @@ -126,4 +126,3 @@ class PProgress extends Promise { } module.exports = PProgress; -module.exports.default = PProgress; diff --git a/index.test-d.ts b/index.test-d.ts index 50c6ec7..e41bb9a 100644 --- a/index.test-d.ts +++ b/index.test-d.ts @@ -1,5 +1,6 @@ -import {expectType} from 'tsd-check'; -import PProgress, {ProgressNotifier} from '.'; +import {expectType} from 'tsd'; +import PProgress = require('.'); +import {ProgressNotifier} from '.'; const progressPromise = new PProgress(async (resolve, reject, progress) => { expectType<(progress: number) => void>(progress); diff --git a/package.json b/package.json index ac3fe83..425a867 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,7 @@ "node": ">=8" }, "scripts": { - "test": "xo && ava && tsd-check" + "test": "xo && ava && tsd" }, "files": [ "index.js", @@ -34,11 +34,11 @@ "p-map": "^2.0.0" }, "devDependencies": { - "ava": "^1.3.1", + "ava": "^1.4.1", "delay": "^4.1.0", "in-range": "^1.0.0", "time-span": "^3.0.0", - "tsd-check": "^0.3.0", + "tsd": "^0.7.1", "xo": "^0.24.0" } }