www.aleph1.co.uk Git - yaffs-website/blob - node_modules/request-progress/README.md

   1 # request-progress
   2
   3 [![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coverage Status][coveralls-image]][coveralls-url] [![Dependency status][david-dm-image]][david-dm-url] [![Dev Dependency status][david-dm-dev-image]][david-dm-dev-url]
   4
   5 [npm-url]:https://npmjs.org/package/request-progress
   6 [downloads-image]:http://img.shields.io/npm/dm/request-progress.svg
   7 [npm-image]:http://img.shields.io/npm/v/request-progress.svg
   8 [travis-url]:https://travis-ci.org/IndigoUnited/node-request-progress
   9 [travis-image]:http://img.shields.io/travis/IndigoUnited/node-request-progress.svg
  10 [coveralls-url]:https://coveralls.io/r/IndigoUnited/node-request-progress
  11 [coveralls-image]:https://img.shields.io/coveralls/IndigoUnited/node-request-progress.svg
  12 [david-dm-url]:https://david-dm.org/IndigoUnited/node-request-progress
  13 [david-dm-image]:https://img.shields.io/david/IndigoUnited/node-request-progress.svg
  14 [david-dm-dev-url]:https://david-dm.org/IndigoUnited/node-request-progress#info=devDependencies
  15 [david-dm-dev-image]:https://img.shields.io/david/dev/IndigoUnited/node-request-progress.svg
  16
  17 Tracks the download progress of a request made with [request](https://github.com/mikeal/request), giving insight of various metrics including progress percentage, download speed and time remaining.
  18
  19
  20 ## Installation
  21
  22 `$ npm install request-progress`
  23
  24
  25 ## Usage
  26
  27 ```js
  28 var fs = require('fs');
  29 var request = require('request');
  30 var progress = require('request-progress');
  31
  32 // The options argument is optional so you can omit it
  33 progress(request('http://google.com/doodle.png'), {
  34     throttle: 2000,                    // Throttle the progress event to 2000ms, defaults to 1000ms
  35     delay: 1000,                       // Only start to emit after 1000ms delay, defaults to 0ms
  36     lengthHeader: 'x-transfer-length'  // Length header to use, defaults to content-length
  37 })
  38 .on('progress', function (state) {
  39     // The state is an object that looks like this:
  40     // {
  41     //     percentage: 0.5,           // Overall percentage (between 0 to 1)
  42     //     speed: 554732,             // The download speed in bytes/sec
  43     //     size: {
  44     //         total: 90044871,       // The total payload size in bytes
  45     //         transferred: 27610959  // The transferred payload size in bytes
  46     //     },
  47     //     time: {
  48     //         elapsed: 36.235,      // The total elapsed seconds since the start (3 decimals)
  49     //         remaining: 81.403     // The remaining seconds to finish (3 decimals)
  50     //     }
  51     // }
  52     console.log('progress', state);
  53 })
  54 .on('error', function (err) {
  55     // Do something with err
  56 })
  57 .pipe(fs.createWriteStream('doodle.png'));
  58 ```
  59
  60 If the request's response does not include the `content-length` header, the values of some metrics will be `null`.
  61 Also `speed` and `time.remaining` will be `null` until it can be calculated.
  62
  63 The `state` object emitted in the `progress` event is reused to avoid creating a new object for each event.
  64 If you wish to peek the `state` object at any time, it is available in `request.progressState`.
  65
  66
  67 ## Tests
  68
  69 `$ npm test`
  70 `$ npm test-cov` to get coverage report
  71
  72
  73 ## License
  74
  75 Released under the [MIT License](http://www.opensource.org/licenses/mit-license.php).