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 | /** Whether the progress bar is active */
|
155 | isActive: boolean;
|
156 |
|
157 | /** Internal render function */
|
158 | render(forceRendering?: boolean): void;
|
159 |
|
160 | /** Starts the progress bar and set the total and initial value */
|
161 | start(total: number, startValue: number, payload?: object): void;
|
162 |
|
163 | /** Stops the progress bar and go to next line */
|
164 | stop(): void;
|
165 |
|
166 | /** Sets the current progress value and optionally the payload with values of custom tokens as a second parameter */
|
167 | update(current: number, payload?: object): void;
|
168 | update(payload: object): void;
|
169 |
|
170 | /** Calculate the actual progress value */
|
171 | getProgress(): number;
|
172 |
|
173 | /** Increases the current progress value by a specified amount (default +1). Update payload optionally */
|
174 | increment(step?: number, payload?: object): void;
|
175 | increment(payload: object): void;
|
176 |
|
177 | /** Get the total (limit) value */
|
178 | getTotal(): number;
|
179 |
|
180 | /** Sets the total progress value while progressbar is active. Especially useful handling dynamic tasks. */
|
181 | setTotal(total: number): void;
|
182 |
|
183 | /** Force eta calculation update (long running processes) without altering the progress values. */
|
184 | updateETA(): void;
|
185 | }
|
186 |
|
187 | export class SingleBar extends GenericBar {
|
188 | /** Initialize a new Progress bar. An instance can be used multiple times! it's not required to re-create it! */
|
189 | constructor(opt: Options, preset?: Preset);
|
190 |
|
191 | /** Internal render function */
|
192 | render(): void;
|
193 |
|
194 | /** Sets the current progress value and optionally the payload with values of custom tokens as a second parameter */
|
195 | update(current: number, payload?: object): void;
|
196 | update(payload: object): void;
|
197 |
|
198 | /** Starts the progress bar and set the total and initial value */
|
199 | start(total: number, startValue: number, payload?: object): void;
|
200 |
|
201 | /** Stops the progress bar and go to next line */
|
202 | stop(): void;
|
203 | }
|
204 |
|
205 | export class MultiBar extends EventEmitter {
|
206 | constructor(opt: Options, preset?: Preset);
|
207 |
|
208 | /** Whether the progress bar is active */
|
209 | isActive: boolean;
|
210 |
|
211 | /** Add a new bar to the stack */
|
212 | create(total: number, startValue: number, payload?: any, barOptions?: Options): SingleBar;
|
213 |
|
214 | /** Remove a bar from the stack */
|
215 | remove(bar: SingleBar): boolean;
|
216 |
|
217 | /** Internal update routine */
|
218 | update(): void;
|
219 |
|
220 | stop(): void;
|
221 |
|
222 | /** Log output above the progress bars; string must end with newline character! */
|
223 | log(data: string): void;
|
224 | }
|
225 |
|
226 | export const Presets: {
|
227 | /** Styles as of cli-progress v1.3.0 */
|
228 | legacy: Preset;
|
229 |
|
230 | /** Unicode Rectangles */
|
231 | rect: Preset;
|
232 |
|
233 | /** Unicode background shades are used for the bar */
|
234 | shades_classic: Preset;
|
235 |
|
236 | /** Unicode background shades with grey bar */
|
237 | shades_grey: Preset;
|
238 | };
|
239 |
|
240 | export interface GenericFormatter {
|
241 | (options: Options, params: Params, payload: any): string;
|
242 | }
|
243 |
|
244 | export interface TimeFormatter {
|
245 | (t: number, options: Options, roundToMultipleOf: number): string;
|
246 | }
|
247 |
|
248 | export interface ValueFormatter {
|
249 | (v: number, options: Options, type: ValueType): string;
|
250 | }
|
251 |
|
252 | export interface BarFormatter {
|
253 | (progress: number, options: Options): string;
|
254 | }
|
255 |
|
256 | export type ValueType = "percentage" | "total" | "value" | "eta" | "duration";
|
257 |
|
258 | declare const defaultFormatter: GenericFormatter;
|
259 | declare const formatBar: BarFormatter;
|
260 | declare const formatValue: ValueFormatter;
|
261 | declare const formatTime: TimeFormatter;
|
262 |
|
263 | export const Format: {
|
264 | Formatter: typeof defaultFormatter;
|
265 | BarFormat: typeof formatBar;
|
266 | ValueFormat: typeof formatValue;
|
267 | TimeFormat: typeof formatTime;
|
268 | };
|
269 |
|
270 | export class Bar extends SingleBar {}
|
271 |
|
272 | export {};
|