BREAKING(cli/unstable): make ProgressBar value and max properties public

cli/unstable_progress_bar.ts

@@ -113,8 +113,8 @@ const UNIT_RATE_MAP = new Map<Unit, number>([
 
 /**
  * `ProgressBar` is a customisable class that reports updates to a
- * {@link WritableStream} on a 1s interval. Progress is communicated by calling
- * the `ProgressBar.add(x: number)` method.
+ * {@link WritableStream} on a 1s interval. Progress is communicated by using
+ * the `ProgressBar.value` property.
  *
  * @experimental **UNSTABLE**: New API, yet to be vetted.
  *
@@ -134,11 +134,11 @@ const UNIT_RATE_MAP = new Map<Unit, number>([
  * const bar = new ProgressBar({ max: 100_000 });
  *
  * for await (const buffer of gen) {
- *   bar.add(buffer.length);
+ *   bar.value += buffer.length;
  *   await writer.write(buffer);
  * }
  *
- * await bar.end();
+ * await bar.stop();
  * await writer.close();
  * ```
  *
@@ -155,23 +155,51 @@ const UNIT_RATE_MAP = new Map<Unit, number>([
  * });
  *
  * for (const x of Array(100)) {
- *   bar.add(1);
+ *   bar.value += 1;
  *   await delay(Math.random() * 500);
  * }
  *
- * bar.end();
+ * await bar.stop();
  */
 export class ProgressBar {
+  /**
+   * The current progress that has been completed.
+   * @example Usage
+   * ```ts no-assert
+   * import { ProgressBar } from "@std/cli/unstable-progress-bar";
+   *
+   * const progressBar = new ProgressBar({ max : 10 });
+   * progressBar.value += 1;
+   *
+   * // do stuff
+   *
+   * await progressBar.stop();
+   * ```
+   */
+  value: number;
+  /**
+   * The maximum progress that is expected.
+   * @example Usage
+   * ```ts no-assert
+   * import { ProgressBar } from "@std/cli/unstable-progress-bar";
+   *
+   * const progressBar = new ProgressBar({ max : 1 });
+   * progressBar.max = 100;
+   *
+   * // do stuff
+   *
+   * await progressBar.stop();
+   * ```
+   */
+  max: number;
+
   #unit: Unit;
   #rate: number;
   #writer: WritableStreamDefaultWriter;
   #id: number;
   #startTime: number;
   #lastTime: number;
   #lastValue: number;
-
-  #value: number;
-  #max: number;
   #barLength: number;
   #fillChar: string;
   #emptyChar: string;
@@ -189,15 +217,16 @@ export class ProgressBar {
     const {
       writable = Deno.stderr.writable,
       value = 0,
+      max,
       barLength = 50,
       fillChar = "#",
       emptyChar = "-",
       clear = false,
       fmt = (x) => `${x.styledTime()} ${x.progressBar} ${x.styledData()} `,
       keepOpen = true,
     } = options;
-    this.#value = value;
-    this.#max = options.max;
+    this.value = value;
+    this.max = max;
     this.#barLength = barLength;
     this.#fillChar = fillChar;
     this.#emptyChar = emptyChar;
@@ -216,13 +245,13 @@ export class ProgressBar {
     this.#id = setInterval(() => this.#print(), 1000);
     this.#startTime = performance.now();
     this.#lastTime = this.#startTime;
-    this.#lastValue = this.#value;
+    this.#lastValue = this.value;
   }
 
   async #print(): Promise<void> {
     const currentTime = performance.now();
 
-    const size = this.#value / this.#max * this.#barLength | 0;
+    const size = this.value / this.max * this.#barLength | 0;
     const fillChars = this.#fillChar.repeat(size);
     const emptyChars = this.#emptyChar.repeat(this.#barLength - size);
 
@@ -233,48 +262,32 @@ export class ProgressBar {
         return `[${minutes}:${seconds}]`;
       },
       styledData: (fractions = 2): string => {
-        const currentValue = (this.#value / this.#rate).toFixed(fractions);
-        const maxValue = (this.#max / this.#rate).toFixed(fractions);
+        const currentValue = (this.value / this.#rate).toFixed(fractions);
+        const maxValue = (this.max / this.#rate).toFixed(fractions);
         return `[${currentValue}/${maxValue} ${this.#unit}]`;
       },
       progressBar: `[${fillChars}${emptyChars}]`,
       time: currentTime - this.#startTime,
       previousTime: this.#lastTime - this.#startTime,
-      value: this.#value,
+      value: this.value,
       previousValue: this.#lastValue,
-      max: this.#max,
+      max: this.max,
     };
     this.#lastTime = currentTime;
-    this.#lastValue = this.#value;
+    this.#lastValue = this.value;
     await this.#writer.write("\r\u001b[K" + this.#fmt(formatter))
       .catch(() => {});
   }
 
-  /**
-   * Increments the progress by `x`.
-   *
-   * @example Usage
-   * ```ts ignore
-   * import { ProgressBar } from "@std/cli/unstable-progress-bar";
-   *
-   * const progressBar = new ProgressBar(Deno.stdout.writable, { max: 100 });
-   * progressBar.add(10);
-   * ```
-   * @param x The amount of progress that has been made.
-   */
-  add(x: number): void {
-    this.#value += x;
-  }
-
   /**
    * Ends the progress bar and cleans up any lose ends.
    *
    * @example Usage
    * ```ts ignore
    * import { ProgressBar } from "@std/cli/unstable-progress-bar";
    *
-   * const progressBar = new ProgressBar(Deno.stdout.writable, { max: 100 });
-   * await progressBar.end()
+   * const progressBar = new ProgressBar({ max: 100 });
+   * await progressBar.stop()
    * ```
    */
   async stop(): Promise<void> {

cli/unstable_progress_bar_stream.ts

@@ -53,7 +53,7 @@ export class ProgressBarStream extends TransformStream<Uint8Array, Uint8Array> {
         bar = new ProgressBar(options);
       },
       transform(chunk, controller) {
-        bar?.add(chunk.length);
+        if (bar) bar.value += chunk.length;
         controller.enqueue(chunk);
       },
       flush(_controller) {

cli/unstable_progress_bar_test.ts

@@ -17,7 +17,7 @@ Deno.test("ProgressBar() outputs default result", async () => {
   const { readable, writable } = new TransformStream();
   const bar = new ProgressBar({ writable, max: 10 * 1000 });
 
-  for await (const a of getData(10, 1000)) bar.add(a.length);
+  for await (const a of getData(10, 1000)) bar.value += a.length;
   bar.stop().then(() => writable.close());
 
   for await (const buffer of readable) {
@@ -66,7 +66,7 @@ Deno.test("ProgressBar() can handle a readable.cancel() correctly", async () =>
   const { readable, writable } = new TransformStream();
   const bar = new ProgressBar({ writable, max: 10 * 1000 });
 
-  for await (const a of getData(10, 1000)) bar.add(a.length);
+  for await (const a of getData(10, 1000)) bar.value += a.length;
   bar.stop();
 
   await readable.cancel();
@@ -76,7 +76,7 @@ Deno.test("ProgressBar() can remove itself when finished", async () => {
   const { readable, writable } = new TransformStream();
   const bar = new ProgressBar({ writable, max: 10 * 1000, clear: true });
 
-  for await (const a of getData(10, 1000)) bar.add(a.length);
+  for await (const a of getData(10, 1000)) bar.value += a.length;
   bar.stop()
     .then(() => writable.close());
 
@@ -102,7 +102,7 @@ Deno.test("ProgressBar() passes correct values to formatter", async () => {
     },
   });
 
-  for await (const a of getData(10, 1000)) bar.add(a.length);
+  for await (const a of getData(10, 1000)) bar.value += a.length;
   bar.stop();
 
   await new Response(readable).bytes();