1 | /// <reference types="node" />
|
2 |
|
3 | import EventEmitter = require("events");
|
4 |
|
5 | export interface Params {
|
6 | progress: number;
|
7 | eta: number;
|
8 | startTime: number;
|
9 | stopTime: number | null;
|
10 | total: number;
|
11 | value: number;
|
12 | maxWidth: number;
|
13 | }
|
14 |
|
15 | export interface Options {
|
16 | /**
|
17 | * progress bar output format.
|
18 | * The progressbar can be customized by using the following build-in placeholders. They can be combined in any order.
|
19 | * {bar} - the progress bar, customizable by the options barsize, barCompleteString and barIncompleteString
|
20 | * {percentage} - the current progress in percent (0-100)
|
21 | * {total} - the end value
|
22 | * {value} - the current value set by last update() call
|
23 | * {eta} - expected time of accomplishment in seconds
|
24 | * {duration} - elapsed time in seconds
|
25 | * {eta_formatted} - expected time of accomplishment formatted into appropriate units
|
26 | * {duration_formatted} - elapsed time formatted into appropriate units
|
27 | *
|
28 | * Example:
|
29 | * progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}
|
30 | * is rendered as
|
31 | * progress [========================================] 100% | ETA: 0s | 200/200
|
32 | */
|
33 | format?: string | GenericFormatter | undefined;
|
34 |
|
35 | /** a custom bar formatter function which renders the bar-element (default: format-bar.js) */
|
36 | formatBar?: BarFormatter | undefined;
|
37 |
|
38 | /** a custom timer formatter function which renders the formatted time elements like eta_formatted and duration-formatted (default: format-time.js) */
|
39 | formatTime?: TimeFormatter | undefined;
|
40 |
|
41 | /** a custom value formatter function which renders all other values (default: format-value.js) */
|
42 | formatValue?: ValueFormatter | undefined;
|
43 |
|
44 | /** the maximum update rate (default: 10) */
|
45 | fps?: number | undefined;
|
46 |
|
47 | /** output stream to use (default: process.stderr) */
|
48 | stream?: NodeJS.WritableStream | undefined;
|
49 |
|
50 | /** automatically call stop() when the value reaches the total (default: false) */
|
51 | stopOnComplete?: boolean | undefined;
|
52 |
|
53 | /** clear the progress bar on complete / stop() call (default: false) */
|
54 | clearOnComplete?: boolean | undefined;
|
55 |
|
56 | /** the length of the progress bar in chars (default: 40) */
|
57 | barsize?: number | undefined;
|
58 |
|
59 | /** position of the progress bar - 'left' (default), 'right' or 'center */
|
60 | align?: "left" | "right" | "center" | undefined;
|
61 |
|
62 | /** character to use as "complete" indicator in the bar (default: "=") */
|
63 | barCompleteString?: string | undefined;
|
64 |
|
65 | /** character to use as "incomplete" indicator in the bar (default: "-") */
|
66 | barIncompleteString?: string | undefined;
|
67 |
|
68 | /** character to use as "complete" indicator in the bar (default: "=") */
|
69 | barCompleteChar?: string | undefined;
|
70 |
|
71 | /** character to use as "incomplete" indicator in the bar (default: "-") */
|
72 | barIncompleteChar?: string | undefined;
|
73 |
|
74 | /**
|
75 | * hide the cursor during progress operation; restored on complete (default: false)
|
76 | * - pass `null` to keep terminal settings
|
77 | */
|
78 | hideCursor?: boolean | null | undefined;
|
79 |
|
80 | /** glue sequence (control chars) between bar elements (default: '') */
|
81 | barGlue?: string | undefined;
|
82 |
|
83 | /** number of updates with which to calculate the eta; higher numbers give a more stable eta (default: 10) */
|
84 | etaBuffer?: number | undefined;
|
85 |
|
86 | /**
|
87 | * trigger an eta calculation update during asynchronous rendering trigger using the current value
|
88 | * - should only be used for long running processes in conjunction with lof `fps` values and large `etaBuffer`
|
89 | * @default false
|
90 | */
|
91 | etaAsynchronousUpdate?: boolean | undefined;
|
92 |
|
93 | /** progress calculation relative to start value ? default start at 0 (default: false) */
|
94 | progressCalculationRelative?: boolean | undefined;
|
95 |
|
96 | /** disable line wrapping (default: false) - pass null to keep terminal settings; pass true to trim the output to terminal width */
|
97 | linewrap?: boolean | null | undefined;
|
98 |
|
99 | /** trigger redraw during update() in case threshold time x2 is exceeded (default: true) - limited to single bar usage */
|
100 | synchronousUpdate?: boolean | undefined;
|
101 |
|
102 | /** enable scheduled output to notty streams - e.g. redirect to files (default: false) */
|
103 | noTTYOutput?: boolean | undefined;
|
104 |
|
105 | /** set the output schedule/interval for notty output in ms (default: 2000ms) */
|
106 | notTTYSchedule?: number | undefined;
|
107 |
|
108 | /** display progress bars with 'total' of zero(0) as empty, not full (default: false) */
|
109 | emptyOnZero?: boolean | undefined;
|
110 |
|
111 | /** trigger redraw on every frame even if progress remains the same; can be useful if progress bar gets overwritten by other concurrent writes to the terminal (default: false) */
|
112 | forceRedraw?: boolean | undefined;
|
113 |
|
114 | /** add padding chars to formatted time and percentage to force fixed width (default: false) */
|
115 | autopadding?: boolean | undefined;
|
116 |
|
117 | /** the character sequence used for autopadding (default: " ") */
|
118 | autopaddingChar?: string | undefined;
|
119 |
|
120 | /** stop bar on SIGINT/SIGTERM to restore cursor settings (default: true) */
|
121 | gracefulExit?: boolean | undefined;
|
122 | }
|
123 |
|
124 | export interface Preset {
|
125 | barCompleteChar: string;
|
126 | barIncompleteChar: string;
|
127 |
|
128 | /**
|
129 | * Example: 'progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}'
|
130 | *
|
131 | * {bar} - the progress bar, customizable by the options barsize, barCompleteString and barIncompleteString
|
132 | *
|
133 | * {percentage} - the current progress in percent (0-100)
|
134 | *
|
135 | * {total} - the end value
|
136 | *
|
137 | * {value} - the current value set by last update() call
|
138 | *
|
139 | * {eta} - expected time of accomplishment in seconds (limited to 115days, otherwise INF is displayed)
|
140 | *
|
141 | * {duration} - elapsed time in seconds
|
142 | *
|
143 | * {eta_formatted} - expected time of accomplishment formatted into appropriate units
|
144 | *
|
145 | * {duration_formatted} - elapsed time formatted into appropriate units
|
146 | */
|
147 | format: string;
|
148 | }
|
149 |
|
150 | export class GenericBar extends EventEmitter {
|
151 | /** Initialize a new Progress bar. An instance can be used multiple times! it's not required to re-create it! */
|
152 | constructor(opt: Options, preset?: Preset);
|
153 |
|
154 | /** Internal render function */
|
155 | render(forceRendering?: boolean): void;
|
156 |
|
157 | /** Starts the progress bar and set the total and initial value */
|
158 | start(total: number, startValue: number, payload?: object): void;
|
159 |
|
160 | /** Stops the progress bar and go to next line */
|
161 | stop(): void;
|
162 |
|
163 | /** Sets the current progress value and optionally the payload with values of custom tokens as a second parameter */
|
164 | update(current: number, payload?: object): void;
|
165 | update(payload: object): void;
|
166 |
|
167 | /** Calculate the actual progress value */
|
168 | getProgress(): number;
|
169 |
|
170 | /** Increases the current progress value by a specified amount (default +1). Update payload optionally */
|
171 | increment(step?: number, payload?: object): void;
|
172 | increment(payload: object): void;
|
173 |
|
174 | /** Get the total (limit) value */
|
175 | getTotal(): number;
|
176 |
|
177 | /** Sets the total progress value while progressbar is active. Especially useful handling dynamic tasks. */
|
178 | setTotal(total: number): void;
|
179 |
|
180 | /** Force eta calculation update (long running processes) without altering the progress values. */
|
181 | updateETA(): void;
|
182 | }
|
183 |
|
184 | export class SingleBar extends GenericBar {
|
185 | /** Initialize a new Progress bar. An instance can be used multiple times! it's not required to re-create it! */
|
186 | constructor(opt: Options, preset?: Preset);
|
187 |
|
188 | /** Internal render function */
|
189 | render(): void;
|
190 |
|
191 | /** Sets the current progress value and optionally the payload with values of custom tokens as a second parameter */
|
192 | update(current: number, payload?: object): void;
|
193 | update(payload: object): void;
|
194 |
|
195 | /** Starts the progress bar and set the total and initial value */
|
196 | start(total: number, startValue: number, payload?: object): void;
|
197 |
|
198 | /** Stops the progress bar and go to next line */
|
199 | stop(): void;
|
200 | }
|
201 |
|
202 | export class MultiBar extends EventEmitter {
|
203 | constructor(opt: Options, preset?: Preset);
|
204 |
|
205 | /** add a new bar to the stack */
|
206 | create(total: number, startValue: number, payload?: any, barOptions?: Options): SingleBar;
|
207 |
|
208 | /** remove a bar from the stack */
|
209 | remove(bar: SingleBar): boolean;
|
210 |
|
211 | /** internal update routine */
|
212 | update(): void;
|
213 |
|
214 | stop(): void;
|
215 |
|
216 | /** log output above the progress bars; string must end with newline character! */
|
217 | log(data: string): void;
|
218 | }
|
219 |
|
220 | export const Presets: {
|
221 | /** Styles as of cli-progress v1.3.0 */
|
222 | legacy: Preset;
|
223 |
|
224 | /** Unicode Rectangles */
|
225 | rect: Preset;
|
226 |
|
227 | /** Unicode background shades are used for the bar */
|
228 | shades_classic: Preset;
|
229 |
|
230 | /** Unicode background shades with grey bar */
|
231 | shades_grey: Preset;
|
232 | };
|
233 |
|
234 | export interface GenericFormatter {
|
235 | (options: Options, params: Params, payload: any): string;
|
236 | }
|
237 |
|
238 | export interface TimeFormatter {
|
239 | (t: number, options: Options, roundToMultipleOf: number): string;
|
240 | }
|
241 |
|
242 | export interface ValueFormatter {
|
243 | (v: number, options: Options, type: ValueType): string;
|
244 | }
|
245 |
|
246 | export interface BarFormatter {
|
247 | (progress: number, options: Options): string;
|
248 | }
|
249 |
|
250 | export type ValueType = "percentage" | "total" | "value" | "eta" | "duration";
|
251 |
|
252 | declare const defaultFormatter: GenericFormatter;
|
253 | declare const formatBar: BarFormatter;
|
254 | declare const formatValue: ValueFormatter;
|
255 | declare const formatTime: TimeFormatter;
|
256 |
|
257 | export const Format: {
|
258 | Formatter: typeof defaultFormatter;
|
259 | BarFormat: typeof formatBar;
|
260 | ValueFormat: typeof formatValue;
|
261 | TimeFormat: typeof formatTime;
|
262 | };
|
263 |
|
264 | export class Bar extends SingleBar {}
|
265 |
|
266 | export {};
|