feat(progress-bar): setup basic

package.json

@@ -27,6 +27,7 @@
     "prettier": "3.3.3"
   },
   "dependencies": {
+    "cli-progress": "^3.12.0",
     "commander": "^12.1.0",
     "github-slugger": "^2.0.0",
     "glob": "^11.0.0",

src/generators/legacy-html/index.mjs

@@ -11,6 +11,12 @@ import tableOfContents from './utils/tableOfContents.mjs';
 
 import { groupNodesByModule } from '../../utils/generators.mjs';
 import { getRemarkRehype } from '../../utils/remark.mjs';
+import {
+  createProgressBar,
+  startProgressBar,
+  updateProgressBar,
+  stopProgressBar,
+} from '../../utils/progressBar.mjs';
 
 /**
  * @typedef {{
@@ -147,6 +153,10 @@ export default {
       return replaceTemplateValues(generatedTemplate);
     };
 
+    // Creates a progress bar to show the progress of the generation process
+    const progressBar = createProgressBar('Generating HTML files');
+    startProgressBar(progressBar, headNodes.length);
+
     for (const node of headNodes) {
       const result = processModuleNodes(node);
 
@@ -157,7 +167,10 @@ export default {
       });
 
       await writeFile(join(output, `${node.api}.html`), minified);
+      updateProgressBar(progressBar);
     }
+    // Stops the progress bar and clears the line
+    stopProgressBar(progressBar);
 
     // Define the output folder for API docs assets
     const assetsFolder = join(output, 'assets');

src/loader.mjs

@@ -6,6 +6,13 @@ import { extname } from 'node:path';
 import { globSync } from 'glob';
 import { VFile } from 'vfile';
 
+import {
+  createProgressBar,
+  startProgressBar,
+  updateProgressBar,
+  stopProgressBar,
+} from './utils/progressBar.mjs';
+
 /**
  * This method creates a simple abstract "Loader", which technically
  * could be used for different things, but here we want to use it to load
@@ -26,8 +33,15 @@ const createLoader = () => {
       filePath => extname(filePath) === '.md'
     );
 
+    const progressBar = createProgressBar('Loading files');
+    startProgressBar(progressBar, resolvedFiles.length);
+
     return resolvedFiles.map(async filePath => {
       const fileContents = await readFile(filePath, 'utf-8');
+      updateProgressBar(progressBar);
+      // normally we stop the progress bar when the loop is done
+      // but here we return the loop so we need to stop it when the last file is loaded
+      if (progressBar.value === progressBar.total) stopProgressBar(progressBar);
 
       return new VFile({ path: filePath, value: fileContents });
     });

src/utils/progressBar.mjs

@@ -0,0 +1,43 @@
+import { styleText } from 'node:util';
+
+import cliProgress from 'cli-progress';
+
+/**
+ *
+ * @param {string} label
+ * @returns {import('cli-progress').SingleBar}
+ */
+export function createProgressBar(label = '') {
+  const format = ` ${styleText(['bold', 'green'], '{bar}')} | ${label} {percentage}% | {value}/{total}`;
+
+  return new cliProgress.SingleBar({
+    format,
+    barCompleteChar: '\u2588',
+    barIncompleteChar: '\u2591',
+    hideCursor: true,
+  });
+}
+
+/**
+ *
+ * @param {import('cli-progress').SingleBar} bar
+ * @param {number} total
+ */
+export function startProgressBar(bar, total) {
+  bar.start(total, 0);
+}
+
+/**
+ * @param {import('cli-progress').SingleBar} bar
+ * @param {number} value
+ */
+export function updateProgressBar(bar, value = 1) {
+  bar.update(value);
+}
+
+/**
+ * @param {import('cli-progress').SingleBar} bar
+ */
+export function stopProgressBar(bar) {
+  bar.stop();
+}

src/utils/tests/progressBar.test.mjs

@@ -0,0 +1,30 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import cliProgress from 'cli-progress';
+
+import {
+  createProgressBar,
+  startProgressBar,
+  stopProgressBar,
+} from '../progressBar.mjs';
+
+describe('progressBar', () => {
+  it('createProgressBar returns an instance of SingleBar', () => {
+    const bar = createProgressBar();
+    assert.ok(bar instanceof cliProgress.SingleBar);
+  });
+
+  it('startProgressBar sets the correct total value', () => {
+    const bar = createProgressBar();
+    startProgressBar(bar, 100);
+    assert.strictEqual(bar.getTotal(), 100);
+  });
+
+  it('stopProgressBar stops the progress bar', () => {
+    const bar = createProgressBar();
+    startProgressBar(bar, 100);
+    stopProgressBar(bar);
+    assert.strictEqual(bar.isActive, false);
+  });
+});