https://github.com/deno-library/progress
ProgressBar in terminal for deno
https://github.com/deno-library/progress
deno progress-bar
Last synced: 5 months ago
JSON representation
ProgressBar in terminal for deno
- Host: GitHub
- URL: https://github.com/deno-library/progress
- Owner: deno-library
- License: mit
- Created: 2020-05-28T10:44:45.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-04-02T04:27:50.000Z (about 1 year ago)
- Last Synced: 2024-10-28T12:15:42.669Z (7 months ago)
- Topics: deno, progress-bar
- Language: TypeScript
- Size: 2.15 MB
- Stars: 60
- Watchers: 2
- Forks: 9
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
# ProgressBar
ProgressBar in terminal for deno
[](https://jsr.io/@deno-library/progress)
[](https://deno.land/x/progress)
[](https://github.com/deno-library/progress/blob/main/LICENSE)
## 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
Multi-line progress bar output in terminal
Change how the order and look of elements
Change character color
Change background color
Color that changes with progress
Precise bar with more intermediate states
Wider bar
Clear the bar once finished
Backward progress
Log some messages
Log some messages next to the bar
More screenshots in the `screenshots` folder.