@kwaeri/progress
Version:
The @kwaeri/progress component module of the @kwaeri/user-executable framework.
243 lines (242 loc) • 6.87 kB
text/typescript
/**
* SPDX-PackageName: kwaeri/progress
* SPDX-PackageVersion: 0.6.0
* SPDX-FileCopyrightText: © 2014 - 2022 Richard Winters <kirvedx@gmail.com> and contributors
* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR MIT
*/
import { ServiceEventBits } from '@kwaeri/service';
export type ProgressBarConfigurationBits = {
type?: string;
barLength?: number;
spinner?: boolean;
spinAnim?: string;
percentage?: boolean;
};
/**
* Progress
*
* This class provides the methods required to effectively manipulate terminal/console output
* such that we can display a progress bar while presenting end-users with information.
*/
export declare class Progress {
/**
* @var { any }
*/
private id;
/**
* @var { string }
*/
private type;
/**
* @var { boolean }
*/
private spinner;
/**
* @var { boolean }
*/
private percentage;
/**
* @var { boolean }
*/
private active;
/**
* @var { number }
*/
private total?;
/**
* @var { number }
*/
private current?;
/**
* @var { string[] }
*/
private spinnerFrames;
/**
* @var { number }
*/
private spinnerInterval;
/**
* @var { number }
*/
private frame;
/**
* @var { number }
*/
private barLength;
/**
* @var { number }
*/
private preferredBarLength;
/**
* @var { number }
*/
private columns?;
/**
* @var { string }
*/
private notification;
/**
* @var { string }
*/
private stamp?;
/**
* @var { Intl.DateTimeFormatOptions }
*/
private timeOptions;
/**
* Class constructor
*
* @param { number } barLength The total length of the progress bar. Defaults to 25.
*
* @returns { void }
*/
constructor(options?: ProgressBarConfigurationBits);
/**
* A method to intialize (start) a new progress bar
*
* @param { number } total The total that represents a completed process
*
* @returns { void }
*/
init(current?: number, total?: number): void;
/**
* Method to update current progress and trigger the progress bar to be drawn
*
* @param { number } current The current progress value.
*
* @returns { void }
*/
update(current?: number): void;
/**
* Method to update the notice to the end-user displayed with the progress bar
* and triggers the progress bar to be drawn
*
* @param { string } notice The string notice to display with the progress bar
*
* @return { void }
*/
notify(notice?: string): void;
/**
* Method to update the progress level of the progress bar, the notice displayed
* with the progress bar, and to trigger the progress bar to be drawn.
*
* @param { number } current The current level of progress
* @param { string } notice The string notice to display with the progress bar
*
* @returns { void }
*/
updateAndNotify(current: number, notice?: string): void;
/**
* Does a final draw after stopping the render loop
*
* @param none
*
* @returns { void }
*/
complete(): void;
/**
* A handler which implements a basic ServiceEvent procedure
*
* @param { ServiceEventBits } data ServiceEventBits
*
* @returns { void }
*
* As an example:
*
* ```typescript
* serviceProvider.updateProgress({
* progressLevel: 25,
* notice: "Currently processing x of y.",
* log: "w of y processed successfully."
* });
* ```
*/
handler(data: ServiceEventBits): void;
/**
* Returns a progress bar handler bound to the instance of the progress bar
* object it controls.
*
* @returns { ( data: ServiceEventBits ) => void } A bound reference to Progress::handler.
*/
getHandler(): (data: ServiceEventBits) => void;
/**
* Method to deactivate (stop) the progress bar (rendering loop)
*
* @param { void }
*
* @returns { void }
*/
stop(): void;
/**
* Method to render the progress bar in the terminal. By default this method
* starts a rendering loop, but boolean true can be passed to force a single
* render that does not additionally set a timeout to support facilities
* such as `log()` with out breaking the display.
*
* @param { boolean } immediate Flag which determines whether to start a rendering
* loop or to immediately render a single time
*
* @returns { void }
*/
private render;
/**
* Method to draw a progress bar
*
* @param { void }
*
* @returns { void }
*/
private draw;
/**
* Method to get the progress bar display buffer
*
* @param { void }
*
* @returns { string } The string buffer for a terminal-based progress bar display
*/
private getBuffer;
/**
* Method to set the column count and barlength within the terminal that the
* progress bar will be displayed in (allows for componesation of manual
* adjustment of the terminal window size in a desktop environment)
*
* @param { number } preferredBarLength The preferred length of the bar (set at instantiation, defaults to 25)
*
* @returns { number } The adjusted bar length, set to fit within the available horizontal space of the terminal
* with the preferredBarLength as a maximum - while considering any wrappings.
*/
private getBarLength;
/**
* Method which prepares a string representation of a portion of a progress
* bar that is to be rendered within a terminal or console window
*
* @param { number } length The number of times the current character should be written
* @param { string } char The current character that should be repeated
* @param { string } color The color of the current progress bar portion
*
* @returns { string } The prepared and buffered string representing the progress bar portion requested
*/
private getBar;
/**
* Method to get the current spinner state to render.
*
* @param { void }
*
* @returns { string } The string buffer for the spinner
*/
private getSpinner;
/**
* Method to add information to our progres output
*
* @param { string } message The string message to present to the user
*
* @returns { Progress } Returns this to allow chaining
*/
log(message: string, type?: number): this;
/**
* Method to get a timestamp for logging purposes
*
* @returns { string } A timestamp in a log format
*/
private getStamp;
}