164 lines
3.4 KiB
Markdown
164 lines
3.4 KiB
Markdown
# progress-stream
|
|
|
|
Read the progress of a stream. Supports speed and eta.
|
|
|
|
Gets the lengths of the stream automatically if you're using the request or http module. You can also pass the length on initiation. Progress-stream will also check to see if the stream already have a length property.
|
|
|
|
npm install progress-stream
|
|
|
|
## Usage
|
|
|
|
This example copies a large file, and prints out the percentage, speed and remaining every 100ms.
|
|
|
|
```js
|
|
var progress = require('progress-stream');
|
|
var fs = require('fs');
|
|
|
|
var stat = fs.statSync(filename);
|
|
var str = progress({
|
|
length: stat.size,
|
|
time: 100
|
|
});
|
|
|
|
str.on('progress', function(progress) {
|
|
console.log(progress);
|
|
|
|
/*
|
|
{
|
|
percentage: 9.05,
|
|
transferred: 949624,
|
|
length: 10485760,
|
|
remaining: 9536136,
|
|
eta: 42,
|
|
runtime: 3,
|
|
delta: 295396,
|
|
speed: 949624
|
|
}
|
|
*/
|
|
});
|
|
|
|
fs.createReadStream(filename)
|
|
.pipe(str)
|
|
.pipe(fs.createWriteStream(output));
|
|
```
|
|
|
|
## Methods
|
|
|
|
### progress([options], [onprogress])
|
|
|
|
You can instantiate in two ways:
|
|
|
|
``` js
|
|
var str = progress({time:100});
|
|
str.on('progress', function(progress) { ... });
|
|
```
|
|
|
|
or inline the progress listener
|
|
|
|
``` js
|
|
var str = progress({time:100}, function(progress) { ... });
|
|
```
|
|
|
|
## Properties
|
|
|
|
### .progress
|
|
|
|
You can get the progress from the progress property.
|
|
|
|
``` js
|
|
var str = progress({time:100});
|
|
|
|
console.log(str.progress);
|
|
|
|
/*
|
|
{
|
|
percentage: 9.05,
|
|
transferred: 949624,
|
|
length: 10485760,
|
|
remaining: 9536136,
|
|
eta: 10,
|
|
runtime: 0,
|
|
delta: 295396,
|
|
speed: 949624
|
|
}
|
|
*/
|
|
```
|
|
|
|
## Events
|
|
|
|
### on('progress', function(progress) { ... })
|
|
|
|
``` js
|
|
var str = progress({time:100});
|
|
str.on('progress', function(progress) { ... });
|
|
```
|
|
|
|
## Options
|
|
|
|
### time(integer)
|
|
|
|
Sets how often progress events is emitted. If omitted then defaults to emit every time a chunk is received.
|
|
|
|
### speed(integer)
|
|
|
|
Sets how long the speedometer needs to calculate the speed. Defaults to 5 sec.
|
|
|
|
### length(integer)
|
|
|
|
If you already know the length of the stream, then you can set it. Defaults to 0.
|
|
|
|
### drain(boolean)
|
|
|
|
In case you don't want to include a readstream after progress-stream, set to true to drain automatically. Defaults to false.
|
|
|
|
### transferred(integer)
|
|
|
|
If you want to set how much data have previous been downloaded. Useful for a resumed download.
|
|
|
|
## Examples
|
|
|
|
### Using the request module
|
|
|
|
This example uses request to download a 100 MB file, and writes out the percentage every second.
|
|
|
|
You can also find an example in `test/request.js`.
|
|
|
|
``` js
|
|
var progress = require('progress-stream');
|
|
var req = require('request');
|
|
var fs = require('fs');
|
|
|
|
var str = progress({
|
|
time: 1000
|
|
});
|
|
|
|
str.on('progress', function(progress) {
|
|
console.log(Math.round(progress.percentage)+'%');
|
|
});
|
|
|
|
req('http://cachefly.cachefly.net/100mb.test', { headers: { 'user-agent': 'test' }})
|
|
.pipe(str)
|
|
.pipe(fs.createWriteStream('test.data'));
|
|
```
|
|
|
|
### Using the http module
|
|
|
|
In `test/http.js` it's shown how to do it with the http module.
|
|
|
|
|
|
## Methods
|
|
|
|
|
|
### `setLength(newLength)`
|
|
|
|
Sometimes, you don't know how big a stream is right away (e.g. multipart file uploads). You might find out after a few chunks have already passed through the stream, seconds or even minutes later. In this case, you can use the `setLength` method to recalculate the relevant tracked progress data.
|
|
|
|
```js
|
|
var str = progress({});
|
|
someFickleStreamInstance.pipe(str).pipe(fs.createWriteStream('test.data'));
|
|
|
|
someFickleStreamInstance.on('conviction', function nowIKnowMyLength (actualLength) {
|
|
str.setLength(actualLength);
|
|
});
|
|
```
|