feat(cli): Intro createProgressBar() & new ProgressBarStream()

[BlackAsLight]

Closes: #6374

This pull request introduces a function called createProgressBar and a class called ProgressBarStream. They write and update a progress to the writable stream passed to them. The methods have quite a bit of configurability.

Tests are yet to be created. Not sure exactly how to create tests to validate behaviour.

Example

import { ProgressBarStream } from "./unstable_progress_bar_stream.ts";

const readable = ReadableStream
  .from<Uint8Array>(async function* (): AsyncGenerator<Uint8Array> {
    for (let i = 0; i < 100; ++i) {
      yield new Uint8Array(1000).fill(97);
      await new Promise((a) => setTimeout(a, (Math.random() * 200) | 0));
    }
  }())
  .pipeThrough(
    new ProgressBarStream(Deno.stdout.writable, {
      totalSize: 1000 * 100,
    }),
  );

// deno-lint-ignore no-empty
for await (const _ of readable) {}

stdout:

[00:04] [###################-------------------------------] [38.09/97.66 KiB]

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.24%. Comparing base (3b75ee7) to head (5fcb98b).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6378      +/-   ##
==========================================
+ Coverage   96.23%   96.24%   +0.01%     
==========================================
  Files         556      558       +2     
  Lines       42065    42181     +116     
  Branches     6371     6379       +8     
==========================================
+ Hits        40481    40597     +116     
  Misses       1544     1544              
  Partials       40       40              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[kt3k]

I agree that showing the progress of byte number count is a common task. But can we also support the progress of abstract counter, like number of packages, number of files, etc.

[BlackAsLight]

I agree that showing the progress of byte number count is a common task. But can we also support the progress of abstract counter, like number of packages, number of files, etc.

Should the amount just offer to display no unit for that instance or ask for custom unit?

[kt3k]

Should the amount just offer to display no unit for that instance or ask for custom unit?

I think It'll probably be confusing to just omit the unit. If 10.0/50.0 is displayed, the user don't know if it's 50.0K or 50.0M.

How about having bytes: boolean option, for example? When it's true, it does the current behavior. If it's false, then it shows numbers like 30, 20K, 10M, etc without B suffix.

[BlackAsLight]

That could work. I was more thinking of offering a custom unit option and if set then the rate calculation would be 1 so they could see something like [4/500,000 files]

[timreichen]

Maybe we should add a formatter option instead of many different styling options.
This is more flexible and also avoids the problem of localization.

Something according to:

import { format as formatDuration } from "@std/fmt/duration.ts"
import { format as formatBytes } from "@std/fmt/bytes.ts"
new ProgressBarStream(Deno.stdout.writable, { formatter: ({ time, progressBar, value, max }) => `[${formatDuration(time)}] ${progressBar} [${formatBytes(value)}/${formatBytes(max)}]` })

[BlackAsLight]

Maybe we should add a formatter option instead of many different styling options. This is more flexible and also avoids the problem of localization.

Something according to:

import { format as formatDuration } from "@std/fmt/duration.ts"
import { format as formatBytes } from "@std/fmt/bytes.ts"
new ProgressBarStream(Deno.stdout.writable, { formatter: ({ time, progressBar, value, max }) => `[${formatDuration(time)}] ${progressBar} [${formatBytes(value)}/${formatBytes(max)}]` })

I added this and a bit more to it, making it optional as I doubt everyone who wants a progress bar wants to go through the effort of styling it.