ascii-bar
Version:
A zero dependency ascii progress bar with spinner, colors and typescript support
239 lines (183 loc) • 7.36 kB
Markdown
# ascii-bar
- [How to use](#how-to-use)
- [Configuration](#configuration)
- [Template String](#template-string)
- [Options](#options)
- [Spinner](#spinner)
- [API Methods and properties](#api-methods-and-properties)
- [Methods](#methods)
- [Properties](#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
````shell
npm install ascii-bar
````
#### Basic Usage
````javascript
const AsciiBar = require('ascii-bar').default;
const bar = new AsciiBar();
//in your long during task
bar.update(numberOfDoneThings,someInfoAboutCurrentTask);
````
#### Using with `import`
````javascript
import AsciiBar from 'ascii-bar'
````
For more examples see [examples folder](https://github.com/superjojo140/ascii-bar/tree/main/example).
## 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:
````javascript
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 | <span style="color:green;">green text</span> |
| ##blue | blue text | <span style="color:blue;">blue text </span> |
| ##red | red text | <span style="color:red;">red text </span> |
| ##yellow | yellow text | <span style="color:yellow;">yellow text </span> |
| ##bright | bright text | <span style="color:lightblue;">bright blue text </span> |
| ##dim | dimmed text | <span style="color:darkgreen;">dimmed green text </span> |
### Options
You can also use a configuration object in the constructor:
````javascript
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](dist/AsciiBar.d.ts#L91)
### 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:
````javascript
const bar = new AsciiBar({
formatString: '#spinner #percent #bar',
enableSpinner: true
});
````
#### Modify spinner
You can also set a [custom spinner](dist/AsciiBar.d.ts#L164)
For more spinner inspiration see [cli-spinners](https://www.npmjs.com/package/cli-spinners)
````javascript
bar.spinner = {
interval: 100,
frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
}
````
## API Methods and properties
### Methods
````javascript
/**
* 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:
````javascript
bar.message = "SomeNewText";
````
````javascript
/**
* 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;
````