ascii-bar

• How to use
• Configuration
  • Template String
  • Options
  • Spinner
• API Methods and properties
  • Methods
  • Properties

Why is it cool?

• 🚀 Extreme lightweight (<50kB) and zero dependencies
• ⭕ Fancy Spinners (automatic ascii fallback for windows)
• 🎨 Colors and Emoji support (if your terminal can display this)
• 🖋️ Intuitive styling via templateString
• ⏰ Calculation and pretty printing of overall progress time and time to finish
• 🔧 Extreme customizable (configure output stream, timing calculation, spinner behavior,...)
• 📖 Typescript types and documentation

How to use

Installation

    npm install ascii-bar

Basic Usage

    const AsciiBar = require('ascii-bar').default;

    const bar = new AsciiBar();

    //in your long during task
    bar.update(numberOfDoneThings,someInfoAboutCurrentTask);

Using with import

    import AsciiBar from 'ascii-bar'

For more examples see examples folder.

Configuration

Template string

The templateString has the greatest influence on the appearance. It allows you to define which elements your status bar contains and how they are arranged. To use a special templateString use it as a parameter in the constructor:

    const bar = new AsciiBar('#spinner #percent #bar Overall time: #overall ##blue #message');

You can use and mix the following placeholders and modificators:

| Placeholder | Description | Example | |-------------|-------------------------------------|---------------------| | #bar | The visualized progress bar | [>>>>>>>>------] | | #count | Count of done tasks and total tasks | [12/42] | | #percent | Percentage of done tasks | 30% | | #overall | Estimated overall time | 1h 12m | | #elapsed | Elapsed time | 1d 2h 34m | | #ttf | Estimated time to finish | 34m 13s | | #message | Information about the current task | Uploading dummy.txt | | #spinner | A spinner | ⠼ | | ##default | Reset text formatting | default text | | ##green | green text | green text | | ##blue | blue text | blue text | | ##red | red text | red text | | ##yellow | yellow text | yellow text | | ##bright | bright text | bright blue text | | ##dim | dimmed text | dimmed green text |

Options

You can also use a configuration object in the constructor:

    const bar = new AsciiBar({
        undoneSymbol: "-",
        doneSymbol: ">",
        width: 20,
        formatString: '#percent #bar',
        total: 100,
        enableSpinner: false,
        lastUpdateForTiming: false,
        autoStop : true,
        print: true,
        start: 0,
        startDate: new Date().getTime(),
        stream: process.stdout,
        hideCursor: false,
    });

For more detailed explanation off all these options have a look at the AsciiBar.d.ts

Spinner

Use a spinner

To use a spinner simply set the enableSpinner option to true. Also use the #spinner placeholder in your template string.

Minimal example:

    const bar = new AsciiBar({
        formatString: '#spinner #percent #bar',
        enableSpinner: true
    });

Modify spinner

You can also set a custom spinner
For more spinner inspiration see cli-spinners

    bar.spinner = {
        interval: 100,
        frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
    }   

API Methods and properties

Methods

    /**
     * update the progress. This will trigger re-rendering the progressbar
     * @param current - the new absolute progress value
     * @param message - [optional] update the message displayed at the #message placeholder
     */
    bar.update(current: number, message?: string)

     /**
     * Creates the progressbar string with all configured settings
     * @returns a string representating the progressbar
     */
    bar.renderLine(): string 

    /**
     * Stop the progressbar
     * This will stop the spinner and change it's symbol to a checkmark (if not disabled)
     * Message will be changed to a string describing the elapsed time (if not disabled)
     * This function will be triggered automatically if the progressbar reaches 100% (if not disabled)
     * @param withInfo - wether to auto-update the progressbar's spinner and message after stopping
     */
    bar.stop(withInfo = true) 

Properties

All of this properties can be changed (even while the progressbar is running).

E.g. to set a new message text do:

    bar.message = "SomeNewText";

    /**
     * Format of the displayed progressbar
     */
    public formatString = '#percent #bar';

    /**
    * Number of steps to finish progress
    */
    public total = 100;

    /**
     * Startdate to calculate elapsed time (in milliseconds)
     */
    public startDate = new Date().getTime();

    /**
     * Which time span to use for timing calculation - If you are unsure always use false here!
     */
    public lastUpdateForTiming = false;

    /**
     * Width of the progress bar (only the #bar part)
     */
    public width = 20;

    /**
    * Symbol for the done progress in the #bar part
    */
    public doneSymbol = ">";

    /**
    * Symbol for the undone progress in the #bar part
    */
    public undoneSymbol = "-";

    /**
    * Wether to print to configured stream or not
    */
    public print = true;

    /**
     * A spinner object describing how the spinner looks like
     * Change this for another spinner
     */
    public spinner = defaultSpinner;

    /**
     * The message displayed at the #message placeholder
     */
    public message = "";

    /**
    * wether to call progressbar's stop() function automatically if the progress reaches 100%
    */
    public autoStop = true;

      /**
     * wether to hide the terminal's cursor while displaying the progress bar
     * cursor will be re-enabled by the bar.stop() function
     * @default false
     */
    hideCursor?: boolean;