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

Attention: Patch coverage is 69.23077% with 32 lines in your changes missing coverage. Please review.

Project coverage is 96.18%. Comparing base (1f032bb) to head (af463c2).

Files with missing lines	Patch %	Lines
cli/unstable_progress_bar_stream.ts	21.73%	18 Missing ⚠️
cli/unstable_progress_bar.ts	82.71%	14 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6378      +/-   ##
==========================================
- Coverage   96.24%   96.18%   -0.07%     
==========================================
  Files         555      557       +2     
  Lines       42047    42151     +104     
  Branches     6369     6375       +6     
==========================================
+ Hits        40470    40542      +72     
- Misses       1537     1569      +32     
  Partials       40       40              

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

[kt3k]

fillChar?

[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)}]` })

[timreichen]

Maybe let's call it value like in progress HTMLElement?

[timreichen]

Maybe let's call it max like in progress HTMLElement?

[timreichen]

Maybe let's call it just clear as in

std/cli/prompt_secret.ts

Line 24 in 3b75ee7

clear?: boolean;

?

[timreichen]

I think options should be formulated positively rather than negatively, something like keepAlive, keepStreamOpen, closeStream or closeStreamWhenCompleted.