Skip to content
Create a promise that reports progress
TypeScript JavaScript
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Create funding.yml May 28, 2019
.editorconfig Init Sep 11, 2017
.gitattributes Minor tweaks Jul 11, 2018
.gitignore Init Sep 11, 2017
.npmrc Init Sep 11, 2017
.travis.yml Meta tweaks Aug 18, 2019
example.js Init Sep 11, 2017
index.d.ts Meta tweaks Feb 21, 2020
index.js Do not throw if a progress is less than last value (#9) Feb 21, 2020
index.test-d.ts Refactor TypeScript definition to CommonJS compatible export (#6) Apr 1, 2019
license Meta tweaks Feb 21, 2020
package.json 0.4.2 Feb 21, 2020
readme.md Meta tweaks Feb 21, 2020
test.js Meta tweaks Aug 18, 2019

readme.md

p-progress Build Status

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');

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

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

You can’t perform that action at this time.