Wondering what’s next for npm?Check out our public roadmap! »

    @kwaeri/progress
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.0 • Public • Published

    kwaeri-node-kit-progress

    pipeline status coverage report CII Best Practices

    The @kwaeri/progress component for the @kwaeri/node-kit application platform

    TOC

    The Implementation

    The progress component module provides methods for implementing a progress bar in a terminal/command prompt that displays the progress of - and notifications for - processes invoked by end-users of @kwaeri/cli [nkm].

    @kwaeri/progress was originally included in the entry point to the platform under the directory [from root] node-kit/external/. In an attempt to standardize implementation - by separating concerns - as well as to ease maintainence of each component of the platform, the progress was migrated to its own component module.

    Getting Started

    NOTE

    @kwaeri/progress is not ready for production. We've published this module for testing and development purposes. You're free to try out anything that may already be available, but please be aware that there is likely to be many aspects of the platform which are not working and/or are completely broken. As we near completion of the new platform, we'll update documentation and provide complete examples and tutorials for getting started.

    Installation

    @kwaeri/node-kit wraps the various components under the kwaeri scope, and provides a single entry point to the node-kit platform for easing the process of building a kwaeri application.

    However, if you wish to install @kwaeri/progress and utilize it specifically - perform the following steps to get started:

    Install @kwaeri/progress:

    npm install @kwaeri/progress

    Usage

    The progress component is leveraged for showing a progress bar and its notifications to end-users of the CLI, through the Steward, explicitly in its handling of commands passed to it by the end user requesting automation of sorts - which is pretty much the core purpose of the CLI.

    To leverage the progress component, you'll first need to include it:

    // INCLUDES
    import { Progress } from '@kwaeri/progress';
     
    // ...

    Next, you'll want to instantiate it. You can choose a type?, whether to show the spinner and/or percentage, the preferred progress bar length, or accept the defaults.

    Constructor
    /**
     * @param { string } type The type of the progress bar. Defaults to "bar"
     * @param { boolean } spinner Flags wether to display the spinner with the progress bar.
     * @param { boolean } percentage Flags whether to display the percentage with the progress bar
     * @param { number } barLength The number of columns to use for displaying the progress bar
     */
    constructor( { type?: string, spinner?: boolean, percentage?: boolean, barLength?: number } = { type: "bar", spinner: true, percentage: false, barLength: 25 } )void;
    • The default bar length is 25 characters, unless the number of columns does not allow for this - in which case the bar length will be the number of columns available, minus any characters required for rendering the progress bar decorations.
    // DEFINES
     
    /* The argument object is optional, as are any properties */
    let progress = new Progress( { type: "bar", spinner: true, percentage: false, barLength: 25 } );
     
    //...

    Finally, you'll want to initialize the progress bar. You can set the current and total level of progress - though defaults of 0 and 100 exist, respectively:

    Init
    /**
     * @param { number } current The current level of progress to set
     * @param { number } total The total level of progress that can be set
     *
     * @returns { void }
     */
    public init( currentnumber = 0, totalnumber = 100 )void;

    Using init typically involves simply calling it:

    // Initialize - and render - the progress bar.
    progress.init();
     
    //...

    Initializing the progress bar renders it, so at this point you'll want to make use of Progress facilities to handle all output to the console. Several methods exist to aid in this:

    Update

    The update() method allows you to pass in a progress level:

    /**
     * @param { number } current The current level of progress to display
     *
     * @returns { void }
     */
    public update( current?: number )void;

    update() is typically called to increase progress:

    // Update progress to 10%
    progress.update( 10 );
     
    //...

    Notify

    The notify() method allows you to pass in a notice to be displayed beside the progress bar:

    /**
     * @param { string } notice The string notification to be written to stdout
     *
     * @returns { void }
     */
    public notify( noticestring = "" )void;
    // Alert the user to the current action
    progress.notify( `Downloading file: ${_someFiles[i]}...` );
     
    //...

    You can invoke the method with out any arguments in order to clear the notification as well.

    UpdateAndNotify

    The updateAndNotify() method allows you to update the level of progress and the notification being displayed simultaneously:

    /**
     * @param { number } current The current level of proegress to display
     * @param { string } notice The notice to display beside the progress bar. May be left blank to clear
     *
     * @returns { void }
     */
    public updateAndNotify( currentnumber, notice?: = "" )void;

    The updateAndNotify() method's second argument by default is an empty string, allowing you leave it out:

    // Completed!
    progress.updateAndNotify( 100, "Download complete." );
     
    //...

    updateAndNotify() simply sets the internal notification property value and subsequently calls update() in order to accomplish it's function.

    Log

    The log() method allows the caller to essentially perform a console.log() when using the progress component - with out breaking the progress bar display.

    /**
     * @param { string } message The string message to log to the console window
     * @param { number } type The type of the message being logged (INFO, ERROR< IMPORTANT, CRITICAL)
     *
     * @returns { Progress } Returns `this` to allow chaining
     */
    public log( messagestring, typenumber = 0 )this;
    • log() accepts a type value, which determines what flag is displayed with the log item. 0 = INFO, 1 = ERROR, 2 = IMPORTANT, 3 = CRITICAL. The default is 0 (INFO).
    • log() returns this to allow chaining.
    // Log completed file download:
    progress.log( `File ${_someFiles[i]} downloaded successfully.` ).updateAndNotify( Math.round( ( ( i * 100 ) / _someFiles.length ) ), `Preparing to download ${_someFiles[i+1]}` );
     
    //...

    The log() method is the tool that brings it all together and enables leveraging the component module for a variety of tasks.

    How to Contribute Code

    Our Open Source projects are always open to contribution. If you'd like to cocntribute, all we ask is that you follow the guidelines for contributions, which can be found at the Massively Modified Wiki

    There you'll find topics such as the guidelines for contributions; step-by-step walk-throughs for getting set up, Coding Standards, CSS Naming Conventions, and more.

    Other Ways to Contribute

    There are other ways to contribute to the project other than with code. Consider testing the software, or in case you've found an Bug - please report it. You can also support the project monetarly through donations via PayPal.

    Regardless of how you'd like to contribute, you can also find in-depth information for how to do so at the Massively Modified Wiki

    Bug Reports

    To submit bug reports, request enhancements, and/or new features - please make use of the issues system baked-in to our source control project space at Gitlab

    You may optionally start an issue, track, and manage it via email by sending an email to our project's Service Desk.

    For more in-depth documentation on the process of submitting bug reports, please visit the Massively Modified Wiki on Bug Reports

    Vulnerability Reports

    Our Vulnerability Reporting process is very similar to Gitlab's. In fact, you could say its a fork.

    To submit vulnerability reports, please email our Security Group. We will try to acknowledge receipt of said vulnerability by the next business day, and to also provide regular updates about our progress. If you are curious about the status of your report feel free to email us again. If you wish to encrypt your disclosure email, like with gitlab - please email us to ask for our GPG Key.

    Please refrain from requesting compensation for reporting vulnerabilities. We will publicly acknowledge your responsible disclosure, if you request us to do so. We will also try to make the confidential issue public after the vulnerability is announced.

    You are not allowed, and will not be able, to search for vulnerabilities on Gitlab.com. As our software is open source, you may download a copy of the source and test against that.

    Confidential Issues

    When a vulnerability is discovered, we create a [confidential issue] to track it internally. Security patches will be pushed to private branches and eventually merged into a security branch. Security issues that are not vulnerabilites can be seen on our public issue tracker.

    For more in-depth information regarding vulnerability reports, confidentiality, and our practices; Please visit the Massively Modified Wiki on Vulnerability

    Donations

    If you cannot contribute time or energy to neither the code base, documentation, nor community support; please consider making a monetary contribution which is extremely useful for maintaining the Massively Modified network and all the goodies offered free to the public.

    Donate via PayPal.com

    Install

    npm i @kwaeri/progress

    DownloadsWeekly Downloads

    1

    Version

    0.1.0

    License

    Apache-2.0

    Unpacked Size

    63.3 kB

    Total Files

    12

    Last publish

    Collaborators

    • avatar