Nuclear Pumpkin Mocha

    status-bar
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/status-bar package

    2.0.3 • Public • Published

    status-bar

    A status bar for file transfers

    npm david

    Example

    var path = require('path');
    var http = require('http');
    var statusBar = require('status-bar');
     
    var url = 'http://nodejs.org/dist/latest/node.exe';
    var bar;
     
    http.get(url, function (res) {
      bar = statusBar.create({ total: res.headers['content-length'] })
          .on('render', function (stats) {
            process.stdout.write(
                path.basename(url) + ' ' +
                this.format.storage(stats.currentSize) + ' ' +
                this.format.speed(stats.speed) + ' ' +
                this.format.time(stats.elapsedTime) + ' ' +
                this.format.time(stats.remainingTime) + ' [' +
                this.format.progressBar(stats.percentage) + '' +
                this.format.percentage(stats.percentage));
            process.stdout.cursorTo(0);
          });
      
      res.pipe(bar);
    }).on('error', function (err) {
      if (bar) bar.cancel();
      console.error(err);
    });
     
    /*
    It will print something like this:
     
    node.exe    2.8 MiB  617.5K/s 00:06 00:07 [############············]  51%
    */

    Why you should try this module

    • It doesn't print anything, it just calculates and returns raw data and provides default formatting functions.
    • The status bar can be displayed wherever you want, it is simply a string, so you can render it in the console, in HTML (probably with your own progress bar) via websockets or NW.js, etc.
    • You decide how to format and arrange the elements. The default formatting functions have a fixed length, so you can format the status bar very easily.
    • It is very easy to use. Just pipe() things to it!

    Render function examples

    • pacman from Arch Linux:

      a-file                  21.8 MiB   67.9M/s 00:03 [#####···················]  22%
      
      var statusBar = require('status-bar');
       
      var formatFilename = function (filename) {
        //80 - 59
        var filenameMaxLength = 21;
        if (filename.length > filenameMaxLength) {
          filename = filename.slice(0, filenameMaxLength - 3) + '...';
        } else {
          var remaining = filenameMaxLength - filename.length;
          while (remaining--) {
            filename += ' ';
          }
        }
        return filename;
      };
       
      filename = formatFilename(filename);
       
      var bar = statusBar.create({ total: ... })
          .on('render', function (stats) {
            process.stdout.write(filename + ' ' + 
                this.format.storage(stats.currentSize) + ' ' +
                this.format.speed(stats.speed) + ' ' +
                this.format.time(stats.remainingTime) + ' [' +
                this.format.progressBar(stats.percentage) + '' +
                this.format.percentage(stats.percentage));
            process.stdout.cursorTo(0);
          });
          
      readableStream.pipe(bar);
    • git clone:

      Receiving objects: 18% (56655992/311833402), 54.0 MiB | 26.7M/s
      
      var statusBar = require('status-bar');
       
      var bar = statusBar.create({ total: ...})
          .on('render', function (stats) {
            process.stdout.write('Receiving objects: ' +
                this.format.percentage(stats.percentage).trim() +
                ' (' + stats.currentSize + '/' + stats.totalSize + '), ' +
                this.format.storage(stats.currentSize).trim() + ' | ' +
                this.format.speed(stats.speed).trim());
            process.stdout.cursorTo(0);
          });
       
      readableStream.pipe(bar);

    Functions

    Objects


    module.create(options) : StatusBar

    Returns a new StatusBar instance.

    Options:

    • frequency - Number
      The rendering frequency in milliseconds. It must be a positive value. Default is 200.
    • progressBarComplete - String
      The character that shows completion progress. Default is #.
    • progressBarIncomplete - String
      The character that shows the remaining progress. Default is ·.
    • progressBarLength - Number
      The length of the progress bar. Default is 24.
    • total - Number
      The total size of the file. This option is required.

    StatusBar

    The StatusBar object inherits from a writable stream.

    Events

    Methods

    Properties


    finish

    Arguments: none.

    Emitted when the transfer finishes.

    hangup

    Arguments: none.

    Emitted when the transfer hangs up (3 seconds without receiving data). Can be emitted multiple times.

    render

    Arguments: stats.

    Emitted when the status bar needs to be rendered. All the properties of the stats object contain raw data so you need to format them. You can use the default formatting functions.

    Stats:

    • currentSize - Number
      The current size in bytes.
    • remainingSize - Number
      The remaining size in bytes.
    • totalSize - Number
      The total size in bytes.
    • percentage - Number
      The progress percentage (current/total size). A number between 0 and 1.
    • speed - Number
      The current speed in bytes per second.
    • elapsedTime - Number
      The elapsed time in seconds.
    • remainingTime - Number
      The estimated remaining time in seconds. If the remaining time cannot be estimated because the status bar needs at least 2 chunks of data or because the transfer it's hung up, it returns undefined.

    StatusBar#cancel() : undefined

    When you need to cancel the rendering of the status bar because the transfer has been aborted due to an error or any other reason, call to this function to clear the internal timers.


    StatusBar#format : Formatter

    Returns a Formatter instance.


    Formatter

    Methods


    Formatter#percentage(percentage) : String

    The percentage must be a number between 0 and 1. Result string length: 4.

    console.log(this.format.percentage(0.5));
    /*
    50%
     */

    Formatter#progressBar(percentage) : String

    The percentage must be a number between 0 and 1. Result string length: the length configured with the option progressBarLength.

    console.log(this.format.progressBar(0.06));
    /*
    #·······················
     */

    Formatter#speed(bytesPerSecond[, decimals]) : String

    By default it shows 1 decimal. Result string length: 8 + #decimals.

    console.log(this.format.speed(30098226));
    /*
      30.1M/s
     */

    Formatter#storage(bytes[, decimals]) : String

    By default it shows 1 decimal. Result string length: 9 + #decimals.

    console.log(this.format.storage(38546744));
    /*
      36.8 MiB
     */

    Formatter#time(seconds) : String

    Result string length: 5 (min:sec). If seconds is undefined it prints --:--.

    console.log(this.format.time(63));
    /*
    01:03
     */

    Install

    npm i status-bar

    DownloadsWeekly Downloads

    139

    Version

    2.0.3

    License

    MIT

    Last publish

    Collaborators

    • gagle