status-bar

status-bar

A status bar for file transfers

Example

var statusBar = require ("status-bar");

var bar = statusBar.create ({
  //Total file size
  total: size,
  //Writing frequency
  frequency: 200,
  //Writing function
  write: function (){
    //Print the status bar as you like
    process.stdout.write (filename + " " + this.stats.size + " " +
        this.stats.speed + " " + this.stats.eta + " [" + this.stats.progress +
        "] " + this.stats.percentage);
    process.stdout.cursorTo (0);
  }
});

//Update the status bar when you send or receive a chunk of a file
.on ("some-event", function (chunk){
  //You can pass any object that contains a length property or a simple number
  bar.update (chunk);
});

//Or simply pipe() things to it!
stream.pipe (bar);

//It will print something like this
//a-file                  17.8 MiB   23.6M/s 00:13 [#·······················]   6%

Why you should try this module

• It doesn't print anything, it just formats the data and you decide how you want to print the status bar. Other modules similar to this use the readline module which is very unstable and may cause problems if you are already using a readline instance.
• You decide how to arrange the elements of the status bar. Because each element has a fixed length 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                  17.8 MiB   23.6M/s 00:13 [#·······················]   6%
  

  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 write = function (){
    process.stdout.write (filename + " " + this.stats.size + " " +
        this.stats.speed + " " + this.stats.eta + " [" +
        this.stats.progress + "] " + this.stats.percentage);
    process.stdout.cursorTo (0);
  };
  

• git clone:

  Receiving objects: 18% (56655992/311833402), 54.0 MiB | 26.7M/s
  

  var write = function (){
    process.stdout.write ("Receiving objects: " + this.stats.percentage.trim () +
        " (" + this.stats.current + "/" + this.stats.total + "), " +
        this.stats.size.trim () + " | " + this.stats.speed.trim ());
    process.stdout.cursorTo (0);
  };
  

Functions

• module.create(options) : StatusBar

Objects

• StatusBar

---

module.create(options) : StatusBar

Returns a new StatusBar instance.

Options:

• total - Number
  The total size of a file. This option is required.
• barComplete - String
  The character that shows completion progress. Default is #.
• barIncomplete - String
  The character that shows the remaining progress. Default is ·.
• barLength - Number
  The length of the progress bar. Default is 24.
• frequency - Number
  The writing frequency. If you don't configure a write function, this option is ignored. By default there's no value, so each time you call to update(), the status bar is printed. This is the most accurate behaviour but it slows down the file transfer very much. I recommend to render the status bar every 200ms, remember that a status bar is purely informational.
• write - Function
  Function that is called when the status bar needs to be printed.
• finish - Function
  Function that is called when the file transfer has finished.

---

StatusBar

Methods

• StatusBar#clearInterval() : undefined
• StatusBar#update(chunk) : undefined

Properties

• StatusBar#stats

---

StatusBar#clearInterval() : undefined

When you need to cancel the status bar rendering because the file transfer has been aborted due to an error or any other reason, call to this function to clear the timer. This is only needed when the frequency option is configured.

---

StatusBar#update(chunk) : undefined

Updates the status bar. The chunk can be any object with a length property or a simple number.

---

StatusBar#stats

stats is an object that contains the current state of the status bar. It is updated each time you update() the status bar. All the following properties are strings and most of them have a fixed length.

• current - String
  The current file size. Length: variable. Example:

  1234
  

• eta - String
  The estimated remaining time. Length: 5. Example (min:sec):

  01:45
  

• percentage - String
  The completion percentage. Length: 4. Example:

  100%
  

• progress - String
  A progress bar with the current file completion. Length: configured with the barLength option. Example:

  ##########··············
  

• size - String
  The current formatted size of the file that is being received/sent. Length: 10. Example:

    12.5 MiB
  

• speed - String
  The current file transfer speed. Length: 9. Example:

     5.3M/s
  

• total - String
  The total file size. Length: variable. Example:

  5678