Flexi-Progress

Flexi-Progress is a powerful Node.js package that empowers you to integrate customizable and flexible progress bars seamlessly into your command-line applications. Whether you're building a CLI tool, a data processing script, or any other command-line program, Flexi-Progress lets you provide visual feedback on the progress of tasks with ease.

Features

• Customizable Appearance: Personalize the visual style of the progress bar to align with your preferences. Adjust options such as bar length, bar character, empty bar character, and brackets to create a tailored appearance.
• Progress Percentage Display: Facilitate progress tracking by presenting the completion percentage right beside the progress bar. Keep users informed about the task's advancement.
• Intuitive Interaction: Seamlessly manage progress bars using intuitive methods such as starting, updating, and stopping. This ensures effortless monitoring and control of task progression.
• Concurrent Task Management: Enhance productivity by efficiently handling multiple tasks through the management of distinct progress indicators. Each task can be monitored individually for optimized progress tracking.
• Informative Messaging: Elevate user engagement by offering contextual information through messages and notifications displayed alongside the progress bar. Users remain well-informed and engaged during the entire progress tracking process.
• Animation Feature: Enable or disable animations for the progress bar. Control whether to display dynamic animations while the progress updates.

These features collectively empower Flexi-Progress to provide a versatile, user-friendly, and informative solution for monitoring progress across diverse tasks and projects.

Installation

You can easily install flexi-progress using npm:

npm install flexi-progress

Usage

Here's an example demonstrating how to integrate Flexi-Progress into your application:

const { CreateBar, HandlerError } = require("flexi-progress");

// Simulate a process with the given progress bar instance
async function simulateProcess(progressBar) {
  const totalSteps = 50;

  // Start the progress bar
  progressBar.start();

  for (let i = 0; i <= totalSteps; i++) {
    // Update the progress bar with the current value
    progressBar.update(i);

    // Update progress with a message when progress reaches 25%
    if (i === 25) {
      progressBar.updateProgressWithMessage(i, "Halfway there!");
    }

    // Show a message alongside the progress bar at 10% progress
    if (i === 10) {
      progressBar.showMessage("Initializing...");
    }

    // Simulate a delay between each step
    await new Promise((resolve) => setTimeout(resolve, 100));
  }

  // Stop the progress bar and mark it as complete
  progressBar.stop();
  console.log("Process completed.");
}

try {
  // Create a new progress bar instance with customization options
  const progressBar = new CreateBar(100, {
    // Customize the appearance and behavior of the progress bar

    // Define the length of the progress bar (number of characters)
    barLength: 40,

    // Specify the character representing the filled portion of the progress bar
    barChar: "=",

    // Specify the character representing the empty portion of the progress bar
    emptyBarChar: "-",

    // Display the completion percentage next to the progress bar
    showPercentage: true,

    // Specify the character used as the opening bracket of the progress bar
    openingBracket: "[",

    // Specify the character used as the closing bracket of the progress bar
    closingBracket: "]",

    // Show the progress bar in the console
    showInConsole: true,

    // Enable or disable animations for the progress bar
    animation: true,
    animationInterval: 500,
    animationFrames: ["🌕", "🌖", "🌗", "🌘", "🌑", "🌒", "🌓", "🌔"],
  });

  // Attach a callback to the 'flexiProgress' event
  progressBar.on("flexiProgress", (progress) => {
    console.log(`Current progress: ${progress.toFixed(2)}%`);
  });

  // Run the simulation using the defined progress bar
  simulateProcess(progressBar);
} catch (error) {
  if (error instanceof HandlerError) {
    console.error(`Flexi-Progress Error: ${error.message}`);
  } else {
    console.error(`An unexpected error occurred: ${error.message}`);
  }
}

Annotations:

1. Import the CreateBar and HandlerError modules from "flexi-progress".
2. Define a function simulateProcess to simulate a process using a given progress bar instance.
3. Start the process of updating the progress bar.
4. Loop through a set number of steps to simulate the progress of a task.
5. Update the progress bar with the current value (i).
6. If the progress reaches 25%, update the progress bar with a message.
7. Display a message alongside the progress bar when the progress reaches 10%.
8. Simulate a delay between each step to visualize the progress.
9. Stop the progress bar and mark the process as complete.
10. Use a try-catch block to handle potential errors when creating the progress bar.
11. Inside the try block, create a new progress bar instance with specified customization options.
12. Attach a callback to the 'flexiProgress' event to log the current progress.
13. Run the simulation process using the defined progress bar instance.
14. Inside the catch block, handle errors. If it's a HandlerError, display a specific error message; otherwise, display a general error message.

API Reference

CreateBar(total, options) Creates a new progress bar instance.

• total (required): The total value representing the completion of the task.
• options (optional): An object containing customization options:
  • barLength: The length of the progress bar (default: 20).
  • barChar: Character used to represent the filled portion of the bar (default: =).
  • emptyBarChar: Character used to represent the empty portion of the bar (default: -).
  • showPercentage: Whether to display the completion percentage (default: true).
  • openingBracket: Character to use as the opening bracket (default: [).
  • closingBracket: Character to use as the closing bracket (default: ]).
  • showInConsole: Whether to show the progress in the console (default: true).

start() Starts the progress bar.

update(value) Updates the progress bar with the provided value.

updateProgressWithMessage(value, message) NEW! Updates the progress bar with the provided value and displays a message.

showMessage(message) NEW! Displays a message alongside the progress bar.

getBar() Returns the representation of the progress bar as a string.

stop() Stops the progress bar and completes it.

on(event, callback) NEW! Adds a callback function to the specified event. The event parameter is a string representing the event name, and the callback parameter is a function that will be executed when the event is triggered. For example:

const { CreateBar } = require("flexi-progress");
const progressBar = new CreateBar(100);

progressBar.on("flexiProgress", (progress) => {
  console.log(`Current progress: ${progress.toFixed(2)}%`);
});

This allows you to attach custom functionality to specific progress events, such as updating messages or triggering actions when certain progress thresholds are reached.

Please note that the 'flexiProgress' event is triggered each time the progress is updated. You can use this event to track and respond to the progress changes in your application.

Changelog - Flexi-Progress v1.0.3

• Added Colorful Progress Bar: Introducing the ability to display a colorful progress bar based on the completion percentage. The progress bar color changes dynamically as the task progresses, providing a visual representation of the progress status.
  • The color scheme is as follows:
    • Less than 25%: Red
    • 25% - 49%: Yellow
    • 50% - 74%: Green
    • 75% and above: Blue
  • The colors are applied to the progress bar using ANSI escape codes, enhancing the visual experience without relying on external libraries.
• Added Animation Customization: Expanded animation customization options for the progress bar.
  • animation: Set to true to enable animation or false to disable it (default: true).
  • animationFrames: An array of characters used for animation frames (default: ['-', '\\', '|', '/']).
  • animationInterval: The time interval (in milliseconds) between animation frames (default: 100).
• Code Enhancements and Refinements: Further improved code quality, readability, and maintainability by refactoring and optimizing existing code.

Contributing

Contributions are welcome! If you have any ideas for improvements or new features, feel free to reach out to us on Discord. You can contact us at JainaGam3r45 to discuss your ideas or to collaborate. We value your input and appreciate your contributions.