Installation

$ npm install ku-progress-bar

Simple bar

constprogress=newProgress({total: 1000});constbar=newBar(progress);progress.increment(300);bar.renderBars();

✗ ts-node ./src/examples/simple-start.ts[============----------------------------] 30% ETA: 71s speed: 10/s duration: 30s 300/1000

Presets

import{Bar,BarItem,presets,Progress}from'../';import*aschalkfrom'chalk';constbar=newBar();constprogress=newProgress({total: 100});bar.add(newBarItem(progress,{options: presets.braille,}));bar.start();

✗ ts-node ./src/examples/presets.example.ts classic [============----------------------------] 31% ETA: 7s speed: 10/s duration: 3s 31/100 shades [████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 31% ETA: 7s speed: 10/s duration: 3s 31/100 rect [■■■■■■■■■■■■ ] 31% ETA: 7s speed: 10/s duration: 3s 31/100 braille [⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀] 31% ETA: 7s speed: 10/s duration: 3s 31/100

Multi bars

constbar=newBar();for(leti=0;i<7;i++){bar.addProgress(newProgress({total: 1000}).increment(Math.floor(Math.random()*1000)),);}bar.render();

Composite Progress bar

exportconstbar=newBar().start();constprogresses=[newProgress({total: 1000,start: 300}),newProgress({total: 1000}),];bar.add(newBarItem(progresses,{options: presets.shades,formatters: {bars: newBarsFormatter([chalk.green,chalk.yellowBright]),},},),);

#Multi Bar

Parameters of the BarItem class:

1. progresses (IProgress | IProgress[]): An object or an array of objects of type IProgress representing the progress.

2. params (IParams | undefined): Additional parameters to customize the appearance and behavior of the progress bar.

   • template (string | function | undefined): Template for displaying the progress bar.
   • options (Partial<IBarOptions> | undefined): Configuration settings for displaying the progress bar.
   • formatters (IFormatters | undefined): Formatting functions for each progress.
   • dataProviders (IDataProviders | undefined): Functions to provide additional data.

Template Format:

src/examples/spinner.example.ts

bar.add(newBarItem(progress,{template:
'[{bar}] {spinner} {percentage} ETA: {eta} speed: {speed} duration: {duration} {value}/{total} (task: {task})',dataProviders: {spinner: ()=>spinner.next().value,},}),);// orbar.add(newBarItem<never,{spinner: ()=>string}>(progress,{template: ({ bar, percentage, eta, speed, duration, value, total, spinner})=>{consttask=progress.getPayload().task;return`[${bar}] ${spinner}${percentage} ETA: ${eta} speed: ${speed} duration: ${duration}${value}/${total} (task: ${task})`;},dataProviders: {spinner: ()=>spinner.next().value,},}),);

In the BarItem class, the template represents a string template that defines how the progress bar will be displayed. In this template, you can use various placeholders that will substitute actual progress values into the resulting string.

Let's review some key placeholders you can use in the template:

• {bar}: Placeholder for inserting the progress bar.
• {percentage}: Placeholder for inserting the progress percentage.
• {eta}: Placeholder for inserting the estimated time of arrival (ETA).
• {etaHumanReadable}: Placeholder for inserting the estimated time (ETA). (2h47m30s)
• {speed}: Placeholder for inserting the progress speed.
• {value}: Placeholder for inserting the current value.
• {total}: Placeholder for inserting the total value.

These placeholders are replaced with the actual progress values during the generation of the progress bar string.

For example, if you use the template "{bar} {percentage}%", during the generation of the progress bar, you'll see a string that displays the progress bar and the progress percentage.

You can also use more complex templates that incorporate a combination of placeholders and additional text to achieve a specific look and informativeness for the progress bar.

For instance, a template "[{bar}] Progress: {percentage}%, ETA: {eta}" will display the progress bar, progress percentage, and the estimated time of arrival.

Additionally, if you pass a custom payload to Progress, it is also possible to use it in the template by using the same approach: {payload_object_key_name}.

Moreover, you can pass a dataProviders object as a parameter to BarItem. For example:

constdataProviders={customData: (progress,progresses)=>renderCustomData(progress,progresses),// other data providers};

You can then use it in the template like this:

Custom Data: {[customData]}

This allows for dynamic and customizable progress bar templates based on the provided data and payload.

example

constbar=newBar();constprogress=newProgress({total: 100},{task: 'users creating...'});function*Spinner(chars: string[],delay=500): Generator<string>{let[index,char,lastUpdate]=[0,' ',0];while(true){if(Date.now()-lastUpdate>delay){index=index+1>=chars.length ? 0 : index+1;char=chars.length ? chars[index] : '';lastUpdate=Date.now();}yieldchar;}}constspinner=Spinner(['\\','|','/','-']);bar.add(newBarItem(progress,{template: '[{bar}] {spinner} {percentage} ETA: {eta} speed: {speed} duration: {duration} {value}/{total} (task: {task})',dataProviders: {spinner: ()=>spinner.next().value,},}))progress.increment(1,{task: 'permission granting...'});constinterval=setInterval(()=>{if(progress.getProgress()>=1){clearInterval(interval);}progress.increment();},50)bar.start();

[=====================-------------------] / 53% ETA: 2s speed: 19/s duration: 3s 53/100 (task: permission granting...)

IBarOptions Interface:

The IBarOptions interface defines the configuration options for customizing the appearance of a progress bar.

Properties:

1. completeChar (string):

   • The character used to represent the completed portion of the progress bar.

2. resumeChar (string):

   • The character used to represent the remaining portion of the progress bar that needs to be filled.

3. width (number):

   • The total width of the progress bar, indicating the number of characters to use for the entire progress representation.

4. glue (string):

   • A string used to separate multiple progress bars if displayed together.

Example Usage:

constoptions: IBarOptions={completeChar: '=',resumeChar: '-',width: 40,glue: ' ',};

Using tags

It is possible use tags in templates and formatters

constprogress=newProgress({total: 100});progresses.push(progress);bar.add(newBarItem([progress,newProgress({total: 100,start: 50,tag: 'red'})],{template:
'[{bars}] {percentage} ETA: {eta} speed: {speed} duration: {duration} {red:value} {value}/{total}',tagDelimiter: ':',formatters: {'red:bar': str=>chalk.red(str),bar: str=>chalk.green(str),},},),);

Spinners example

src/examples/spinner.example.ts

Some random examples

src/examples/random.bar.example.ts