p-progress

p-progress

Create a promise that reports progress

Useful for reporting progress to the user during long-running async operations.

Install

$ npm install p-progress

Usage

const PProgress = require('p-progress');

(async () => {
	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);
	});

	progressPromise.onProgress(progress => {
		console.log(`${progress * 100}%`);
		//=> 9%
		//=> 23%
		//=> 59%
		//=> 75%
		//=> 100%
	});

	await progressPromise;
})();

API

instance = new PProgress(executor)

Same as the Promise constructor, but with an appended progress parameter in executor.

PProgress is a subclass of Promise.

progress(percentage)

Type: Function

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.

Calling with a number lower than previously will be ignored.

Progress percentage 1 is reported for you when the promise resolves. If you set it yourself, it will simply be ignored.

instance.progress

Type: number

The current progress percentage of the promise as a number between 0 and 1.

instance.onProgress(function)

Accepts a function that gets instance.progress as an argument and is called for every progress event.

PProgress.fn(function)

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.

const 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;
})();

PProgress.all(promises, options?)

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.

const PProgress = require('p-progress');
const 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;
})();

promises

Type: Promise[]

Array of promises or promise-returning functions, similar to p-all.

options

Type: object

concurrency

Type: number
Default: Infinity
Minimum: 1

Number of concurrently pending promises.

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.

Related

• p-cancelable - Create a promise that can be canceled
• More…