gauge

What is gauge?

The gauge npm package is a minimalistic progress bar module for Node.js that can display different types of progress information. It is designed to be flexible and can be used in command-line applications to provide visual feedback to users about the progress of an operation.

What are gauge's main functionalities?

Basic Progress Bar

This feature allows you to create a basic progress bar that shows the progress of an operation. The 'show' method updates the progress bar with a label and the completion percentage.

const Gauge = require('gauge');
let gauge = new Gauge();
gauge.show('processing', 0.5);

Pulse

The 'pulse' method is used to keep the progress bar active without changing the progress. It can be used to indicate that an operation is ongoing when the progress percentage cannot be determined.

const Gauge = require('gauge');
let gauge = new Gauge();
gauge.pulse('item being processed');

Set the Progress

This feature allows you to update the progress bar to a specific value. The value is a fraction between 0 and 1, where 1 represents 100% completion.

const Gauge = require('gauge');
let gauge = new Gauge();
gauge.show('loading', 0.75);

Hide the Progress Bar

The 'hide' method is used to remove the progress bar from the display. This is typically used once an operation has completed.

const Gauge = require('gauge');
let gauge = new Gauge();
gauge.hide();

Other packages similar to gauge

progress

The 'progress' package is another popular progress bar library for Node.js. It provides a simple API to create and control a progress bar and is known for its ease of use. Compared to 'gauge', it might be less flexible but is straightforward for basic progress bar needs.

cli-progress

The 'cli-progress' package offers a rich set of features to create customizable progress bars for command-line interfaces. It supports multiple bars, custom tokens, and even bar styles. It is more feature-rich compared to 'gauge' and is suitable for more complex CLI applications.

ora

While not a direct alternative to 'gauge' as it is more of a spinner than a progress bar, 'ora' is used to indicate progress in command-line applications. It provides a simple and elegant way to show that a task is in progress without displaying a percentage.

README

gauge

A nearly stateless terminal based horizontal gauge / progress bar.

var Gauge = require("gauge")

var gauge = new Gauge()

gauge.show("test", 0.20)

gauge.pulse("this")

gauge.hide()

CHANGES FROM 1.x

Gauge 2.x is breaking release, please see the changelog for details on what's changed if you were previously a user of this module.

THE GAUGE CLASS

This is the typical interface to the module– it provides a pretty fire-and-forget interface to displaying your status information.

var Gauge = require("gauge")

var gauge = new Gauge(stream, [options])

• stream – A stream that progress bar updates are to be written to. Gauge honors backpressure and will pause most writing if it is indicated.
• options – (optional) An option object.

Constructs a new gauge. Gauges are drawn on a single line, and are not drawn if the current terminal isn't a tty.

If stream is a terminal or if you pass in tty to options then we will detect terminal resizes and redraw to fit. We do this by watching for resize events on the tty. (To work around a bug in verisons of Node prior to 2.5.0, we watch for them on stdout if the tty is stderr.) Resizes to larger window sizes will be clean, but shrinking the window will always result in some cruft.

The options object can have the following properties, all of which are optional:

• updateInterval: How often gauge updates should be drawn, in miliseconds.
• fixedFramerate: Defaults to false on node 0.8, true on everything else. When this is true a timer is created to trigger once every updateInterval ms, when false, updates are printed as soon as they come in but updates more often than updateInterval are ignored. The reason 0.8 doesn't have this set to true is that it can't unref its timer and so it would stop your program from exiting– if you want to use this feature with 0.8 just make sure you call gauge.disable() before you expect your program to exit.
• theme: The theme to use as output. Defaults to something usable on your combination of OS, color and unicode support. In practice this means that Windows always gets ASCII by default, Mac almost always gets unicode, and everyone almost always gets color. Unicode is detected with has-unicode and color is detected with has-color. Theme selection is done by the internal themes module, which you can use directly.
• template: Describes what you want your gauge to look like. The default is what npm uses. Detailed documentation is later in this document.
• hideCursor: Defaults to true. If true, then the cursor will be hidden while the gauge is displayed.
• tty: The tty that you're ultimately writing to. Defaults to the same as stream. This is used for detecting the width of the terminal and resizes. The width used is tty.columns - 1. If no tty is available then a width of 79 is assumed.
• enabled: Defaults to true. If true the gauge starts enabled. If disabled then all update commands are ignored and no gauge will be printed until you call .enable().
• Plumbing: The class to use to actually generate the gauge for printing. This defaults to require('gauge/plumbing') and ordinarly you shouldn't need to override this.

gauge.show(section | status, [completed])

The first argument is either the section, the name of the current thing contributing to progress, or an object with keys like section, subsection & completed (or any others you have types for in a custom template). If you don't want to update or set any of these you can pass null and it will be ignored.

The second argument is the percent completed as a value between 0 and 1. Without it, completion is just not updated. You'll also note that completion can be passed in as part of a status object as the first argument. If both it and the completed argument are passed in, the completed argument wins.

gauge.hide()

Removes the gauge from the terminal.

gauge.pulse([subsection])

• subsection – (optional) The specific thing that triggered this pulse

Spins the spinner in the gauge to show output. If subsection is included then it will be combined with the last name passed to gauge.show.

gauge.disable()

Hides the gauge and ignores further calls to show or pulse.

gauge.enable()

Shows the gauge and resumes updating when show or pulse is called.

gauge.setTheme(theme)

Change the active theme, will be displayed with the next show or pulse

gauge.setTemplate(template)

Change the active template, will be displayed with the next show or pulse

Tracking Completion

If you have more than one thing going on that you want to track completion of, you may find the related are-we-there-yet helpful. It's change event can be wired up to the show method to get a more traditional progress bar interface.

THEMES

var theme = require('gauge/themes')

// fetch the default color unicode theme for this platform
var ourTheme = theme({hasUnicode: true, hasColor: true})

// fetch the default non-color unicode theme for osx
var ourTheme = theme({hasUnicode: true, hasColor: false, platform: 'darwin'})

// create a new theme based on the color ascii theme for this platform
// that brackets the progress bar with arrows
var ourTheme = theme.newTheme(theme(hasUnicode: false, hasColor: true}), {
  preProgressbar: '→',
  postProgressbar: '←'
})

theme(opts)

Fetches a theme object based on platform settings.

Options is an object with the following properties:

• hasUnicode - If true, fetch a unicode theme.
• hasColor - If true, fetch a color theme.
• platform (optional) - Defaults to process.platform. The platform code of the theme we want.

theme.newTheme([parent,] newTheme)

Create a new theme object based on parent. If no parent is provided then a minimal parent that defines functions for rendering the activity indicator (spinner) and progress bar will be defined.

newTheme should be a bare object– we'll start by discussing the properties defined by the default themes:

• preProgressbar - displayed prior to the progress bar, if the progress bar is displayed.
• postProgressbar - displayed after the progress bar, if the progress bar is displayed.
• progressBarTheme - The subtheme passed through to the progress bar renderer, it's an object with complete and remaining properties that are the strings you want repeated for those sections of the progress bar.
• activityIndicatorTheme - The theme for the activity indicator (spinner), this can either be a string, in which each character is a different step, or an array of strings.
• preSubsection - Displayed as a separator between the section and subsection when the latter is printed.

More generally, themes can have any value that would be a valid value when rendering templates. The properties in the theme are used when their name matches a type in the template. Their values can be:

• strings & numbers - They'll be included as is
• function (values, theme, width) - Should return what you want in your output. values is an object with values provided via gauge.show, theme is the theme specific to this item (see below) or this theme object, and width is the number of characters wide your result should be.

There are a couple of special prefixes:

• pre - Is shown prior to the property, if its displayed.
• post - Is shown after the property, if its displayed.

And one special suffix:

• Theme - Its value is passed to a function-type item as the theme.

TEMPLATES

A template is an array of objects and strings that, after being evaluated, will be turned into the gauge line. The default template is:

[
    {type: 'progressbar', length: 20},
    {type: 'activityIndicator', kerning: 1, length: 1},
    {type: 'section', kerning: 1},
    {type: 'subsection', kerning: 1}
]

The various template elements can either be plain strings, in which case they will be be included verbatum in the output, or objects with the following properties:

• type can be any of the following plus any keys you pass into gauge.show plus any keys you have on a custom theme.
  • section – What big thing you're working on now.
  • subsection – What component of that thing is currently working.
  • activityIndicator – Shows a spinner using the activityIndicatorTheme from your active theme.
  • progressbar – A progress bar representing your current completed using the progressbarTheme from your active theme.
• kerning – Number of spaces that must be between this item and other items, if this item is displayed at all.
• maxLength – The maximum length for this element. If its value is longer it will be truncated.
• minLength – The minimum length for this element. If its value is shorter it will be padded according to the align value.
• align – (Default: left) Possible values "left", "right" and "center". Works as you'd expect from word processors.
• length – Provides a single value for both minLength and maxLength. If both length and *minLength or maxLength are specifed then the latter take precedence.
• value – A literal value to use for this template item.

PLUMBING

This is the super simple, assume nothing, do no magic internals used by gauge to implement its ordinary interface.

var Plumbing = require('gauge/plumbing')
var gauge = new Plumbing(theme, template, width)

• theme: The theme to use.
• template: The template to use.
• width: How wide your gauge should be

gauge.setTheme(theme)

Change the active theme.

gauge.setTemplate(template)

Change the active template.

gauge.setWidth(width)

Change the width to render at.

gauge.hide()

Return the string necessary to hide the progress bar

gauge.hideCursor()

Return a string to hide the cursor.

gauge.showCursor()

Return a string to show the cursor.

gauge.show(status)

Using status for values, render the provided template with the theme and return a string that is suitable for printing to update the gauge.

Changelog

v2.0.0

This is a major rewrite of the internals. Externally there are fewer changes:

• On node>0.8 gauge object now prints updates at a fixed rate. This means that when you call show it may wate up to updateInterval ms before it actually prints an update. You override this behavior with the fixedFramerate option.
• The gauge object now keeps the cursor hidden as long as it's enabled and shown.
• The constructor's arguments have changed, now it takes a mandatory output stream and an optional options object. The stream no longer needs to be an ansiified stream, although it can be if you want (but we won't make use of its special features).
• Previously the gauge was disabled by default if process.stdout wasn't a tty. Now it always defaults to enabled. If you want the previous behavior set the enabled option to process.stdout.isTTY.
• The constructor's options have changed– see the docs for details.
• Themes are entirely different. If you were using a custom theme, or referring to one directly (eg via Gauge.unicode or Gauge.ascii) then you'll need to change your code. You can get the equivalent of the latter with:

  var themes = require('gauge/themes')
  var unicodeTheme = themes(true, true) // returns the color unicode theme for your platform
  

  The default themes no longer use any ambiguous width characters, so even if you choose to display those as wide your progress bar should still display correctly.
• Templates are entirely different and if you were using a custom one, you should consult the documentation to learn how to recreate it. If you were using the default, be aware that it has changed and the result looks quite a bit different.