Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/deno-library/progress

ProgressBar in terminal for deno
https://github.com/deno-library/progress

deno progress-bar

Last synced: about 2 months ago
JSON representation

ProgressBar in terminal for deno

Awesome Lists containing this project

README

        

# ProgressBar

ProgressBar in terminal for deno

[![JSR Version](https://jsr.io/badges/@deno-library/progress)](https://jsr.io/@deno-library/progress)
[![deno.land/x/progress](https://deno.land/badge/progress/version)](https://deno.land/x/progress)
[![LICENSE](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/deno-library/progress/blob/main/LICENSE)

![logo](screenshots/logo.png)

## Changelog

[changelog](./changelog.md)

## Usage

### Multiple progress bars

#### example

```ts
import { MultiProgressBar } from "jsr:@deno-library/progress";
import { delay } from "jsr:@std/async";

// or JSR (with version)
// import { MultiProgressBar } from "jsr:@deno-library/[email protected]";
// import { delay } from "jsr:@std/[email protected]";

// or JSR (no prefix, run `deno add @deno-library/progress` and `deno add @std/async`)
// import { MultiProgressBar } from "@deno-library/progress";
// import { delay } from "@std/async";

// or
// import { MultiProgressBar } from "https://deno.land/x/[email protected]/mod.ts";
// import { delay } from "https://deno.land/[email protected]/async/delay.ts";

const title = "download files";
const total = 100;

const bars = new MultiProgressBar({
title,
// clear: true,
complete: "=",
incomplete: "-",
display: "[:bar] :text :percent :time :completed/:total",
});

let completed1 = 0;
let completed2 = 0;

async function download() {
while (completed1 <= total || completed2 <= total) {
completed1 += 1;
completed2 += 2;
await bars.render([
{
completed: completed1,
total,
text: "file1",
complete: "*",
incomplete: ".",
},
{ completed: completed2, total, text: "file2" },
]);

await delay(50);
}
}

await download();
```

#### interface

```ts
interface constructorOptions {
title?: string;
width?: number;
complete?: string;
incomplete?: string;
clear?: boolean;
interval?: number;
display?: string;
prettyTime?: boolean;
output?: typeof Deno.stdout | typeof Deno.stderr;
}

interface renderOptions {
completed: number;
text?: string;
total?: number;
complete?: string;
incomplete?: string;
prettyTimeOptions?: prettyTimeOptions;
}

/**
* prettyTime options
* @param withSpaces Whether to use spaces to separate times, `1d2h3m5s` or `1d 2h 3m 5s`, default false
* @param toFixedVal value pass to toFixed for seconds, default 1
* @param longFormat Whether to use a long format, default false, `1d2h3m5s` or `1days 2hours 3minutes 5seconds`
*/
interface prettyTimeOptions {
withSpaces?: boolean;
toFixedVal?: number;
longFormat?: boolean;
}

class MultiProgressBar {
/**
* Title, total, complete, incomplete, can also be set or changed in the render method
*
* @param title Progress bar title, default: ''
* @param width the displayed width of the progress, default: 50
* @param complete completion character, default: colors.bgGreen(' '), can use any string
* @param incomplete incomplete character, default: colors.bgWhite(' '), can use any string
* @param clear clear the bar on completion, default: false
* @param interval minimum time between updates in milliseconds, default: 16
* @param display What is displayed and display order, default: ':bar :text :percent :time :completed/:total'
* @param prettyTime Whether to pretty print time and eta
* @param output Output stream, can be Deno.stdout or Deno.stderr, default is Deno.stdout
*/
constructor(options: ConstructorOptions);

/**
* "render" the progress bar
*
* @param bars progress bars
* @param bars.completed` completed value
* @param bars.total optional, total number of ticks to complete, default: 100
* @param bars.text optional, text displayed per ProgressBar, default: ''
* @param bars.complete optional, completion character
* @param bars.incomplete optional, incomplete character
* @param bars.prettyTimeOptions optional, prettyTime options
*/
render(bars: Array): Promise;

/**
* console: interrupt the progress bar and write a message above it
*
* @param message The message to write
*/
console(message: string): Promise;

/**
* end: end a progress bar.
* No need to call in most cases, unless you want to end before 100%
*/
end(): Promise;
}
```

#### display

What is displayed and display order, default: ':bar :text :percent :time
:completed/:total'

- `:bar` the progress bar itself
- `:text` text displayed per ProgressBar
- `:percent` completion percentage
- `:time` time elapsed in seconds
- `:eta` estimated completion time in seconds
- `:total` total number of ticks to complete
- `:completed` completed value

### Single progress bar

#### simple example

```ts
import ProgressBar from "jsr:@deno-library/progress";
import { delay } from "jsr:@std/async";

// or JSR (with version)
// import ProgressBar from "jsr:@deno-library/[email protected]";
// import { delay } from "jsr:@std/[email protected]";

// or JSR (no prefix, run `deno add @deno-library/progress` and `deno add @std/async`)
// import ProgressBar from "@deno-library/progress";
// import { delay } from "@std/async";

// or
// import ProgressBar from "https://deno.land/x/[email protected]/mod.ts";
// import { delay } from "@std/async/delay";

const title = "downloading:";
const total = 100;
const progress = new ProgressBar({
title,
total,
});
let completed = 0;
async function download() {
while (completed <= total) {
await progress.render(completed++);

await delay(50);
}
}
await download();
```

#### complex example

```ts
import ProgressBar from "jsr:@deno-library/progress";
import { delay } from "jsr:@std/async";

// or JSR (with version)
// import ProgressBar from "jsr:@deno-library/[email protected]";
// import { delay } from "jsr:@std/[email protected]";

// or JSR (no prefix, run `deno add @deno-library/progress` and `deno add @std/async`)
// import ProgressBar from "@deno-library/progress";
// import { delay } from "@std/async";

// or
// import ProgressBar from "https://deno.land/x/[email protected]/mod.ts";
// import { delay } from "@std/async/delay";

const total = 100;
const progress = new ProgressBar({
total,
complete: "=",
incomplete: "-",
display: ":completed/:total hello :time [:bar] :percent",
// or =>
// display: ':bar'
// display: ':bar :time'
// display: '[:bar]'
// display: 'hello :bar world'
// ...
});
let completed = 0;
async function download() {
while (completed <= total) {
await progress.render(completed++);

await delay(50);
}
}
await download();
```

More examples in the `examples` folder.

#### interface

```ts
interface ConstructorOptions {
title?: string,
total?: number,
width?: number,
complete?: string,
preciseBar?: string[],
incomplete?: string,
clear?: boolean,
interval?: number,
display?: string
prettyTime?: boolean;
output?: typeof Deno.stdout | typeof Deno.stderr;
}

interface renderOptions {
title?: string,
total?: number,
text?: string;
complete?: string,
preciseBar?: string[],
incomplete?: string,
prettyTimeOptions?: prettyTimeOptions;
}

/**
* prettyTime options
* @param withSpaces Whether to use spaces to separate times, `1d2h3m5s` or `1d 2h 3m 5s`, default false
* @param toFixedVal value pass to toFixed for seconds, default 1
* @param longFormat Whether to use a long format, default false, `1d2h3m5s` or `1days 2hours 3minutes 5seconds`
*/
interface prettyTimeOptions {
withSpaces?: boolean;
toFixedVal?: number;
longFormat?: boolean;
}

class ProgressBar {
/**
* Title, total, complete, incomplete, can also be set or changed in the render method
*
* @param title progress bar title, default: ''
* @param total total number of ticks to complete
* @param width the displayed width of the progress, default: 50
* @param complete completion character, default: colors.bgGreen(' '), can use any string
* @param preciseBar in between character, default: [colors.bgGreen(' ')], can use any string array
* @param incomplete incomplete character, default: colors.bgWhite(' '), can use any string
* @param clear clear the bar on completion, default: false
* @param interval minimum time between updates in milliseconds, default: 16
* @param display What is displayed and display order, default: ':title :percent :bar :time :completed/:total'
* @param prettyTime Whether to pretty print time and eta
* @param output Output stream, can be Deno.stdout or Deno.stderr, default is Deno.stdout
*/
constructor(options: ConstructorOptions): void;

/**
* render: render the progress bar
*
* @param completed completed value
* @param options optional parameters
* @param options.title optional, progress bar title
* @param options.text optional, custom text, default: ''
* @param options.total optional, total number of ticks to complete, default: 100
* @param options.complete optional, completion character, If you want to change at a certain moment. For example, it turns red at 20%
* @param options.incomplete optional, incomplete character, If you want to change at a certain moment. For example, it turns red at 20%
* @param options.prettyTimeOptions optional, prettyTime options
*/
render(completed: number, options? renderOptions): Promise;

/**
* console: interrupt the progress bar and write a message above it
*
* @param message The message to write
*/
console(message: string): Promise;

/**
* end: end a progress bar.
* No need to call in most cases, unless you want to end before 100%
*/
end(): Promise;
}
```

#### display

What is displayed and display order, default: ':title :percent :bar :time
:completed/:total'

- `:title` progress bar title
- `:percent` completion percentage
- `:bar` the progress bar itself
- `:time` time elapsed in seconds
- `:eta` estimated completion time in seconds
- `:completed` completed value
- `:total` total number of ticks to complete

## Screenshots

Standard use

![normal](./screenshots/title.gif)

Multi-line progress bar output in terminal

![normal](./screenshots/multi.gif)

Change how the order and look of elements

![console](./screenshots/display.gif)

Change character color

![console](./screenshots/changeColor.gif)

Change background color

![console](./screenshots/changeBgColor.gif)

Color that changes with progress

![console](./screenshots/colorProgression.gif)

Precise bar with more intermediate states

![console](./screenshots/preciseBar.gif)

Wider bar

![console](./screenshots/width.gif)

Clear the bar once finished

![clear](./screenshots/clear.gif)

Backward progress

![backward](./screenshots/backward.gif)

Log some messages

![console](./screenshots/console.gif)

Log some messages next to the bar

![console](./screenshots/info.gif)

More screenshots in the `screenshots` folder.