版博士V2.0程序
Nevar pievienot vairāk kā 25 tēmas Tēmai ir jāsākas ar burtu vai ciparu, tā var saturēt domu zīmes ('-') un var būt līdz 35 simboliem gara.
 
 
 
 

950 rindas
38 KiB

  1. import Enquirer from 'enquirer';
  2. import { Subject, Observable } from 'rxjs';
  3. import { Writable, Readable } from 'stream';
  4. import { WriteStream } from 'fs';
  5. interface BasePromptOptions {
  6. message: string | (() => string) | (() => Promise<string>);
  7. initial?: boolean | number | number[] | string | (() => string) | (() => Promise<string>);
  8. required?: boolean;
  9. stdin?: NodeJS.ReadStream;
  10. stdout?: NodeJS.WriteStream;
  11. header?: string;
  12. footer?: string;
  13. skip?: (value: any) => boolean | Promise<boolean>;
  14. format?: (value: any) => any | Promise<any>;
  15. result?: (value: any) => any | Promise<any>;
  16. validate?: (value: any, state: any) => boolean | Promise<boolean> | string | Promise<string> | Promise<string | boolean>;
  17. onSubmit?: (name: any, value: any, prompt: Enquirer.Prompt) => boolean | Promise<boolean>;
  18. onCancel?: (name: any, value: any, prompt: Enquirer.Prompt) => boolean | Promise<boolean>;
  19. }
  20. interface BasePromptOptionsWithName extends BasePromptOptions {
  21. name: string | (() => string);
  22. }
  23. interface ArrayPromptOptions extends BasePromptOptions {
  24. choices: string[] | BasePromptOptionsWithName[];
  25. maxChoices?: number;
  26. multiple?: boolean;
  27. initial?: number | number[];
  28. delay?: number;
  29. separator?: boolean;
  30. sort?: boolean;
  31. linebreak?: boolean;
  32. edgeLength?: number;
  33. align?: 'left' | 'right';
  34. scroll?: boolean;
  35. hint?: string;
  36. }
  37. interface BooleanPromptOptions extends BasePromptOptions {
  38. initial?: boolean | (() => string) | (() => Promise<string>);
  39. }
  40. interface StringPromptOptions extends BasePromptOptions {
  41. initial?: string;
  42. multiline?: boolean;
  43. }
  44. interface ScalePromptOptions extends ArrayPromptOptions {
  45. scale: StringPromptOptions[];
  46. margin?: [number, number, number, number];
  47. }
  48. interface NumberPromptOptions extends BasePromptOptions {
  49. min?: number;
  50. max?: number;
  51. delay?: number;
  52. float?: boolean;
  53. round?: boolean;
  54. major?: number;
  55. minor?: number;
  56. initial?: number;
  57. }
  58. interface SnippetPromptOptions extends BasePromptOptions {
  59. newline?: string;
  60. fields: Partial<BasePromptOptionsWithName>[];
  61. template: string;
  62. }
  63. interface SortPromptOptions extends BasePromptOptions {
  64. hint?: string;
  65. drag?: boolean;
  66. numbered?: boolean;
  67. }
  68. interface SurveyPromptOptions extends ArrayPromptOptions {
  69. scale: BasePromptOptionsWithName[];
  70. margin: [number, number, number, number];
  71. }
  72. interface QuizPromptOptions extends ArrayPromptOptions {
  73. correctChoice: number;
  74. }
  75. interface TogglePromptOptions extends BasePromptOptions {
  76. enabled?: string;
  77. disabled?: string;
  78. }
  79. /** Returns all the prompt options depending on the type selected. */
  80. type PromptOptions<T extends boolean = false> = Unionize<{
  81. [K in PromptTypes]-?: T extends true ? {
  82. type: K;
  83. } & PromptOptionsType<K> & {
  84. name: string | (() => string);
  85. } : {
  86. type: K;
  87. } & PromptOptionsType<K>;
  88. }> | ({
  89. type: string;
  90. } & T extends true ? PromptOptionsType<string> & {
  91. name: string | (() => string);
  92. } : PromptOptionsType<string>);
  93. type Unionize<T extends Record<PropertyKey, unknown>> = {
  94. [P in keyof T]: T[P];
  95. }[keyof T];
  96. type PromptTypes = 'AutoComplete' | 'BasicAuth' | 'Confirm' | 'Editable' | 'Form' | 'Input' | 'Invisible' | 'List' | 'MultiSelect' | 'Numeral' | 'Password' | 'Quiz' | 'Scale' | 'Select' | 'Snippet' | 'Sort' | 'Survey' | 'Text' | 'Toggle';
  97. type PromptOptionsType<T> = T extends keyof PromptOptionsMap ? PromptOptionsMap[T] : T extends string ? BasePromptOptions & Record<PropertyKey, unknown> : any;
  98. declare class PromptOptionsMap implements Record<PromptTypes, Record<PropertyKey, any>> {
  99. AutoComplete: ArrayPromptOptions;
  100. BasicAuth: StringPromptOptions;
  101. Confirm: BooleanPromptOptions;
  102. Editable: ArrayPromptOptions;
  103. Form: ArrayPromptOptions;
  104. Input: StringPromptOptions;
  105. Invisible: StringPromptOptions;
  106. List: ArrayPromptOptions;
  107. MultiSelect: ArrayPromptOptions;
  108. Numeral: NumberPromptOptions;
  109. Password: StringPromptOptions;
  110. Quiz: QuizPromptOptions;
  111. Scale: ScalePromptOptions;
  112. Select: ArrayPromptOptions;
  113. Snippet: SnippetPromptOptions;
  114. Sort: SortPromptOptions;
  115. Survey: SurveyPromptOptions;
  116. Text: StringPromptOptions;
  117. Toggle: TogglePromptOptions;
  118. }
  119. interface PromptSettings {
  120. error?: boolean;
  121. cancelCallback?: (settings?: PromptSettings) => string | Error | PromptError | void;
  122. stdout?: WriteStream | Writable;
  123. enquirer?: Enquirer;
  124. }
  125. interface PromptInstance extends Omit<BasePromptOptions, 'onCancel' | 'onSubmit'> {
  126. submit: () => void;
  127. cancel: (err?: string) => void;
  128. }
  129. /**
  130. * Extend the task to have more functionality while accessing from the outside.
  131. */
  132. declare class TaskWrapper<Ctx, Renderer extends ListrRendererFactory> {
  133. task: Task<Ctx, ListrRendererFactory>;
  134. errors: ListrError<Ctx>[];
  135. private options;
  136. constructor(task: Task<Ctx, ListrRendererFactory>, errors: ListrError<Ctx>[], options: ListrBaseClassOptions<Ctx, any, any>);
  137. /** Get the title of the current task. */
  138. get title(): string;
  139. /** Change the title of the current task. */
  140. set title(data: string);
  141. /** Get the output from the output channel. */
  142. get output(): string;
  143. /** Send a output to the output channel. */
  144. set output(data: string);
  145. /** Create a new subtask with given renderer selection from the parent task. */
  146. newListr<NewCtx = Ctx>(task: ListrTask<NewCtx, Renderer> | ListrTask<NewCtx, Renderer>[] | ((parent: Omit<this, 'skip' | 'enabled'>) => ListrTask<NewCtx, Renderer> | ListrTask<NewCtx, Renderer>[]), options?: ListrSubClassOptions<NewCtx, Renderer>): Listr<NewCtx, any, any>;
  147. /** Report a error in process for error collection. */
  148. report(error: Error, type: ListrErrorTypes): void;
  149. /** Skip current task. */
  150. skip(message?: string): void;
  151. /** Get the number of retrying, else returns false */
  152. isRetrying(): Task<Ctx, Renderer>['retry'];
  153. /**
  154. * Create a new Enquirer prompt using prompt options.
  155. *
  156. * Since process.stdout is controlled by Listr, this will passthrough all Enquirer data through internal stdout.
  157. */
  158. prompt<T = any>(options: PromptOptions | PromptOptions<true>[]): Promise<T>;
  159. /** Cancels the current prompt attach to this task. */
  160. cancelPrompt(throwError?: boolean): void;
  161. /**
  162. * Pass stream of data to internal stdout.
  163. *
  164. * Since Listr2 takes control of process.stdout utilizing the default renderer, any data outputted to process.stdout
  165. * will corrupt its looks.
  166. *
  167. * This returns a fake stream to pass any stream inside Listr as task data.
  168. */
  169. stdout(): NodeJS.WriteStream & NodeJS.WritableStream;
  170. /** Run this task. */
  171. run(ctx: Ctx): Promise<void>;
  172. }
  173. /** Available task states. */
  174. declare enum ListrTaskState {
  175. PENDING = "PENDING",
  176. COMPLETED = "COMPLETED",
  177. FAILED = "FAILED",
  178. SKIPPED = "SKIPPED",
  179. ROLLING_BACK = "ROLLING_BACK",
  180. ROLLED_BACK = "ROLLED_BACK",
  181. RETRY = "RETRY"
  182. }
  183. /**
  184. * Create a task from the given set of variables and make it runnable.
  185. */
  186. declare class Task<Ctx, Renderer extends ListrRendererFactory> extends Subject<ListrEvent> {
  187. listr: Listr<Ctx, any, any>;
  188. tasks: ListrTask<Ctx, any>;
  189. options: ListrOptions;
  190. rendererOptions: ListrGetRendererOptions<Renderer>;
  191. /** Unique id per task, randomly generated in the uuid v4 format */
  192. id: string;
  193. /** The current state of the task. */
  194. state: string;
  195. /** The task object itself, to further utilize it. */
  196. task: (ctx: Ctx, task: TaskWrapper<Ctx, Renderer>) => void | ListrTaskResult<Ctx>;
  197. /** Extend current task with multiple subtasks. */
  198. subtasks: Task<Ctx, any>[];
  199. /** Title of the task */
  200. title?: string;
  201. /** Untouched unchanged title of the task */
  202. initialTitle?: string;
  203. /** Output data from the task. */
  204. output?: string;
  205. /** Skip current task. */
  206. skip: boolean | string | ((ctx: Ctx) => boolean | string | Promise<boolean | string>);
  207. /** Current retry number of the task if retrying */
  208. retry?: {
  209. count: number;
  210. withError?: any;
  211. };
  212. /**
  213. * A channel for messages.
  214. *
  215. * This requires a separate channel for messages like error, skip or runtime messages to further utilize in the renderers.
  216. */
  217. message: {
  218. /** Run time of the task, if it has been successfully resolved. */
  219. duration?: number;
  220. /** Error message of the task, if it has been failed. */
  221. error?: string;
  222. /** Skip message of the task, if it has been skipped. */
  223. skip?: string;
  224. /** Rollback message of the task, if the rollback finishes */
  225. rollback?: string;
  226. /** Retry messages */
  227. retry?: {
  228. count: number;
  229. withError?: any;
  230. };
  231. };
  232. /** Per task options for the current renderer of the task. */
  233. rendererTaskOptions: ListrGetRendererTaskOptions<Renderer>;
  234. /** This will be triggered each time a new render should happen. */
  235. renderHook$: Subject<void>;
  236. prompt: undefined | PromptInstance | PromptError;
  237. private enabled;
  238. private enabledFn;
  239. constructor(listr: Listr<Ctx, any, any>, tasks: ListrTask<Ctx, any>, options: ListrOptions, rendererOptions: ListrGetRendererOptions<Renderer>);
  240. set state$(state: ListrTaskState);
  241. set output$(data: string);
  242. set message$(data: Task<Ctx, Renderer>['message']);
  243. set title$(title: string);
  244. /**
  245. * A function to check whether this task should run at all via enable.
  246. */
  247. check(ctx: Ctx): Promise<void>;
  248. /** Returns whether this task has subtasks. */
  249. hasSubtasks(): boolean;
  250. /** Returns whether this task is in progress. */
  251. isPending(): boolean;
  252. /** Returns whether this task is skipped. */
  253. isSkipped(): boolean;
  254. /** Returns whether this task has been completed. */
  255. isCompleted(): boolean;
  256. /** Returns whether this task has been failed. */
  257. hasFailed(): boolean;
  258. /** Returns whether this task has an active rollback task going on. */
  259. isRollingBack(): boolean;
  260. /** Returns whether the rollback action was successful. */
  261. hasRolledBack(): boolean;
  262. /** Returns whether this task has an actively retrying task going on. */
  263. isRetrying(): boolean;
  264. /** Returns whether enabled function resolves to true. */
  265. isEnabled(): boolean;
  266. /** Returns whether this task actually has a title. */
  267. hasTitle(): boolean;
  268. /** Returns whether this task has a prompt inside. */
  269. isPrompt(): boolean;
  270. /** Run the current task. */
  271. run(context: Ctx, wrapper: TaskWrapper<Ctx, Renderer>): Promise<void>;
  272. }
  273. /** Default updating renderer for Listr2 */
  274. declare class DefaultRenderer implements ListrRenderer {
  275. tasks: Task<any, typeof DefaultRenderer>[];
  276. options: (typeof DefaultRenderer)['rendererOptions'];
  277. renderHook$?: Task<any, any>['renderHook$'];
  278. /** designates whether this renderer can output to a non-tty console */
  279. static nonTTY: boolean;
  280. /** renderer options for the defauult renderer */
  281. static rendererOptions: {
  282. /**
  283. * indentation per level of subtask
  284. *
  285. * @default 2
  286. */
  287. indentation?: number;
  288. /**
  289. * clear all the output generated by the renderer when the task finishes its execution
  290. *
  291. * @default false
  292. * @global global option that can not be temperated with subtasks
  293. */
  294. clearOutput?: boolean;
  295. /**
  296. * show the subtasks of the current task
  297. *
  298. * @default true
  299. */
  300. showSubtasks?: boolean;
  301. /**
  302. * collapse subtasks after current task completes its execution
  303. *
  304. * @default true
  305. */
  306. collapse?: boolean;
  307. /**
  308. * show skip messages or show the original title of the task, this will also disable collapseSkips mode
  309. *
  310. * You can disable showing the skip messages, even though you passed in a message by settings this option,
  311. * if you want to keep the original task title intact.
  312. *
  313. * @default true
  314. */
  315. showSkipMessage?: boolean;
  316. /**
  317. * collapse skip messages into a single message and overwrite the task title
  318. *
  319. * @default true
  320. */
  321. collapseSkips?: boolean;
  322. /**
  323. * suffix skip messages with [SKIPPED] when in collapseSkips mode
  324. *
  325. * @default true
  326. */
  327. suffixSkips?: boolean;
  328. /**
  329. * shows the thrown error message or show the original title of the task, this will also disable collapseErrors mode
  330. * You can disable showing the error messages, even though you passed in a message by settings this option,
  331. * if you want to keep the original task title intact.
  332. *
  333. * @default true
  334. */
  335. showErrorMessage?: boolean;
  336. /**
  337. * collapse error messages into a single message and overwrite the task title
  338. *
  339. * @default true
  340. */
  341. collapseErrors?: boolean;
  342. /**
  343. * suffix retry messages with [RETRY-${COUNT}] when retry is enabled for a task
  344. *
  345. * @default true
  346. */
  347. suffixRetries?: boolean;
  348. /**
  349. * only update through triggers from renderhook
  350. *
  351. * useful for tests and stuff. this will disable showing spinner and only update the screen if something else has
  352. * happened in the task worthy to show
  353. *
  354. * @default false
  355. * @global global option that can not be temperated with subtasks
  356. */
  357. lazy?: boolean;
  358. /**
  359. * show duration for all tasks
  360. *
  361. * @default false
  362. * @global global option that can not be temperated with subtasks
  363. */
  364. showTimer?: boolean;
  365. /**
  366. * removes empty lines from the data output
  367. *
  368. * @default true
  369. */
  370. removeEmptyLines?: boolean;
  371. /**
  372. * formats data output depending on your requirements.
  373. *
  374. * @default 'truncate'
  375. * @global global option that can not be temperated with subtasks
  376. */
  377. formatOutput?: 'truncate' | 'wrap';
  378. };
  379. /** per task options for the default renderer */
  380. static rendererTaskOptions: {
  381. /**
  382. * write task output to the bottom bar instead of the gap under the task title itself.
  383. * useful for a stream of data.
  384. * @default false
  385. *
  386. * `true` only keep 1 line of the latest data outputted by the task.
  387. * `false` only keep 1 line of the latest data outputted by the task.
  388. * `number` will keep designated data of the latest data outputted by the task.
  389. */
  390. bottomBar?: boolean | number;
  391. /**
  392. * keep output after task finishes
  393. * @default false
  394. *
  395. * works both for the bottom bar and the default behavior
  396. */
  397. persistentOutput?: boolean;
  398. /**
  399. * show the task time if it was successful
  400. */
  401. showTimer?: boolean;
  402. };
  403. private id?;
  404. private bottomBar;
  405. private promptBar;
  406. private readonly spinner;
  407. private spinnerPosition;
  408. constructor(tasks: Task<any, typeof DefaultRenderer>[], options: (typeof DefaultRenderer)['rendererOptions'], renderHook$?: Task<any, any>['renderHook$']);
  409. getTaskOptions(task: Task<any, typeof DefaultRenderer>): (typeof DefaultRenderer)['rendererTaskOptions'];
  410. isBottomBar(task: Task<any, typeof DefaultRenderer>): boolean;
  411. hasPersistentOutput(task: Task<any, typeof DefaultRenderer>): boolean;
  412. hasTimer(task: Task<any, typeof DefaultRenderer>): boolean;
  413. getSelfOrParentOption<T extends keyof (typeof DefaultRenderer)['rendererOptions']>(task: Task<any, typeof DefaultRenderer>, key: T): (typeof DefaultRenderer)['rendererOptions'][T];
  414. getTaskTime(task: Task<any, typeof DefaultRenderer>): string;
  415. createRender(options?: {
  416. tasks?: boolean;
  417. bottomBar?: boolean;
  418. prompt?: boolean;
  419. }): string;
  420. render(): void;
  421. end(): void;
  422. private multiLineRenderer;
  423. private renderBottomBar;
  424. private renderPrompt;
  425. private dumpData;
  426. private formatString;
  427. private indentMultilineOutput;
  428. private getSymbol;
  429. private addSuffixToMessage;
  430. }
  431. declare class SilentRenderer implements ListrRenderer {
  432. tasks: Task<any, typeof SilentRenderer>[];
  433. options: typeof SilentRenderer['rendererOptions'];
  434. /** designates whether this renderer can output to a non-tty console */
  435. static nonTTY: boolean;
  436. /** renderer options for the silent renderer */
  437. static rendererOptions: never;
  438. /** per task options for the silent renderer */
  439. static rendererTaskOptions: never;
  440. constructor(tasks: Task<any, typeof SilentRenderer>[], options: typeof SilentRenderer['rendererOptions']);
  441. render(): void;
  442. end(): void;
  443. }
  444. /** Type of listr internal events. */
  445. declare enum ListrEventType {
  446. TITLE = "TITLE",
  447. STATE = "STATE",
  448. ENABLED = "ENABLED",
  449. SUBTASK = "SUBTASK",
  450. DATA = "DATA",
  451. MESSAGE = "MESSAGE"
  452. }
  453. /**
  454. * This is the default renderer which is neither verbose or updating.
  455. * It provides short output like update renderer, but does not disturb
  456. * stdin during execution of listr tasks
  457. */
  458. declare class SimpleRenderer implements ListrRenderer {
  459. readonly tasks: Task<any, typeof SimpleRenderer>[];
  460. options: typeof SimpleRenderer['rendererOptions'];
  461. static nonTTY: boolean;
  462. static rendererOptions: {
  463. /**
  464. * if true this will add
  465. * timestamp at the begin of the rendered line
  466. *
  467. * @example
  468. *
  469. * ```bash
  470. * [12:33:44] ✔ Do something important
  471. * ```
  472. *
  473. * @default false
  474. */
  475. prefixWithTimestamp?: boolean;
  476. /**
  477. * choose between process.stdout and process.stderr
  478. *
  479. * @default stdout
  480. */
  481. output?: 'stdout' | 'stderr';
  482. };
  483. static rendererTaskOptions: never;
  484. /**
  485. * Event type renderer map contains functions to process different task events
  486. */
  487. eventTypeRendererMap: Partial<{
  488. [P in ListrEventType]: (t: Task<any, typeof SimpleRenderer>, event: ListrEventFromType<P>) => void;
  489. }>;
  490. constructor(tasks: Task<any, typeof SimpleRenderer>[], options: typeof SimpleRenderer['rendererOptions']);
  491. static now(): Date;
  492. static formatTitle(task?: Task<any, typeof SimpleRenderer>): string;
  493. log(output?: string): void;
  494. end(): void;
  495. render(tasks?: Task<any, typeof SimpleRenderer>[]): void;
  496. }
  497. /** Default loglevels for the logger */
  498. declare enum LogLevels {
  499. SILENT = "SILENT",
  500. FAILED = "FAILED",
  501. SKIPPED = "SKIPPED",
  502. SUCCESS = "SUCCESS",
  503. DATA = "DATA",
  504. STARTED = "STARTED",
  505. TITLE = "TITLE",
  506. RETRY = "RETRY",
  507. ROLLBACK = "ROLLBACK"
  508. }
  509. /**
  510. * Options for the logger
  511. */
  512. interface LoggerOptions {
  513. useIcons: boolean;
  514. }
  515. /**
  516. * A internal logger for using in the verbose renderer mostly.
  517. */
  518. declare class Logger {
  519. private options?;
  520. constructor(options?: LoggerOptions);
  521. fail(message: string): void;
  522. skip(message: string): void;
  523. success(message: string): void;
  524. data(message: string): void;
  525. start(message: string): void;
  526. title(message: string): void;
  527. retry(message: string): void;
  528. rollback(message: string): void;
  529. protected parseMessage(level: LogLevels, message: string): string;
  530. protected logColoring({ level, message }: {
  531. level: LogLevels;
  532. message: string;
  533. }): string;
  534. private wrapInBrackets;
  535. }
  536. declare class VerboseRenderer implements ListrRenderer {
  537. tasks: Task<any, typeof VerboseRenderer>[];
  538. options: typeof VerboseRenderer['rendererOptions'];
  539. /** designates whether this renderer can output to a non-tty console */
  540. static nonTTY: boolean;
  541. /** renderer options for the verbose renderer */
  542. static rendererOptions: ({
  543. /**
  544. * useIcons instead of text for log level
  545. * @default false
  546. */
  547. useIcons?: boolean;
  548. /**
  549. * log tasks with empty titles
  550. * @default true
  551. */
  552. logEmptyTitle?: boolean;
  553. /**
  554. * log title changes
  555. * @default true
  556. */
  557. logTitleChange?: boolean;
  558. /**
  559. * show duration for all tasks
  560. */
  561. showTimer?: boolean;
  562. } & {
  563. /**
  564. * inject a custom logger
  565. */
  566. logger?: new (...args: any) => Logger;
  567. /**
  568. * inject options to custom logger
  569. */
  570. options?: any;
  571. });
  572. /** per task options for the verbose renderer */
  573. static rendererTaskOptions: never;
  574. private logger;
  575. constructor(tasks: Task<any, typeof VerboseRenderer>[], options: typeof VerboseRenderer['rendererOptions']);
  576. render(): void;
  577. end(): void;
  578. private verboseRenderer;
  579. }
  580. /** The default renderer value used in Listr2 applications */
  581. type ListrDefaultRendererValue = 'default';
  582. /** Type of default renderer */
  583. type ListrDefaultRenderer = typeof DefaultRenderer;
  584. /** Name of default fallback renderer */
  585. type ListrFallbackRendererValue = 'verbose';
  586. /** Type of default fallback renderer */
  587. type ListrFallbackRenderer = typeof VerboseRenderer;
  588. /** Silent rendere for internal usage */
  589. type ListrSilentRendererValue = 'silent';
  590. /** Typeof silent renderer */
  591. type ListrSilentRenderer = typeof SilentRenderer;
  592. /** Simple renderer that simplifies things */
  593. type ListrSimpleRendererValue = 'simple';
  594. /** Typeof simple renderer */
  595. type ListrSimpleRenderer = typeof SimpleRenderer;
  596. /**
  597. * Listr2 can process either the integrated renderers as string aliases,
  598. * or utilize a compatible style renderer that extends the ListrRenderer abstract class.
  599. */
  600. type ListrRendererValue = ListrSilentRendererValue | ListrDefaultRendererValue | ListrSimpleRendererValue | ListrFallbackRendererValue | ListrRendererFactory;
  601. /**
  602. * Returns the class type from friendly names of the renderers.
  603. */
  604. type ListrGetRendererClassFromValue<T extends ListrRendererValue> = T extends ListrDefaultRendererValue ? ListrDefaultRenderer : T extends ListrSimpleRendererValue ? ListrSimpleRenderer : T extends ListrFallbackRendererValue ? ListrFallbackRenderer : T extends ListrSilentRenderer ? ListrSilentRenderer : T extends ListrRendererFactory ? T : never;
  605. /**
  606. * Returns the friendly names from the type of renderer classes.
  607. */
  608. type ListrGetRendererValueFromClass<T extends ListrRendererFactory> = T extends DefaultRenderer ? ListrDefaultRendererValue : T extends SimpleRenderer ? ListrSimpleRendererValue : T extends VerboseRenderer ? ListrFallbackRendererValue : T extends SilentRenderer ? ListrSilentRenderer : T extends ListrRendererFactory ? T : never;
  609. /**
  610. * Returns renderer global options depending on the renderer type.
  611. */
  612. type ListrGetRendererOptions<T extends ListrRendererValue> = T extends ListrDefaultRendererValue ? ListrDefaultRenderer['rendererOptions'] : T extends ListrSimpleRendererValue ? ListrSimpleRenderer['rendererOptions'] : T extends ListrFallbackRendererValue ? ListrFallbackRenderer['rendererOptions'] : T extends ListrSilentRenderer ? ListrSilentRenderer['rendererOptions'] : T extends ListrRendererFactory ? T['rendererOptions'] : never;
  613. /**
  614. * Returns renderer per task options depending on the renderer type.
  615. */
  616. type ListrGetRendererTaskOptions<T extends ListrRendererValue> = T extends ListrDefaultRendererValue ? ListrDefaultRenderer['rendererTaskOptions'] : T extends ListrSimpleRendererValue ? ListrSimpleRenderer : T extends ListrFallbackRendererValue ? ListrFallbackRenderer['rendererTaskOptions'] : T extends ListrSilentRenderer ? ListrSilentRenderer['rendererTaskOptions'] : T extends ListrRendererFactory ? T['rendererTaskOptions'] : never;
  617. /** Select renderer as default renderer */
  618. interface ListrDefaultRendererOptions<T extends ListrRendererValue> {
  619. /** the default renderer */
  620. renderer?: T;
  621. /** Renderer options depending on the current renderer */
  622. rendererOptions?: ListrGetRendererOptions<T>;
  623. }
  624. /** Select a fallback renderer to fallback to in non-tty conditions */
  625. interface ListrDefaultNonTTYRendererOptions<T extends ListrRendererValue> {
  626. /** the fallback renderer to fallback to on non-tty conditions */
  627. nonTTYRenderer?: T;
  628. /** Renderer options depending on the current renderer */
  629. nonTTYRendererOptions?: ListrGetRendererOptions<T>;
  630. }
  631. /** Renderer options for the base class, including setup for selecting default and fallback renderers. */
  632. type ListrRendererOptions<Renderer extends ListrRendererValue, FallbackRenderer extends ListrRendererValue> = ListrDefaultRendererOptions<Renderer> & ListrDefaultNonTTYRendererOptions<FallbackRenderer>;
  633. /** The bones of a listr renderer. */
  634. declare class ListrRenderer {
  635. /** designate renderer global options that is specific to the current renderer */
  636. static rendererOptions: Record<PropertyKey, any>;
  637. /** designate renderer per task options that is specific to the current renderer */
  638. static rendererTaskOptions: Record<PropertyKey, any>;
  639. /** designate whether this renderer can work in non-tty environments */
  640. static nonTTY: boolean;
  641. /** A function to what to do on render */
  642. render: () => void;
  643. /** A function to what to do on end of the render */
  644. end: (err?: Error) => void;
  645. /** create a new renderer */
  646. constructor(tasks: readonly Task<any, ListrRendererFactory>[], options: typeof ListrRenderer.rendererOptions, renderHook$?: Subject<void>);
  647. }
  648. /** Exported for javascript applications to extend the base renderer */
  649. declare class ListrBaseRenderer implements ListrRenderer {
  650. static rendererOptions: Record<PropertyKey, any>;
  651. static rendererTaskOptions: Record<PropertyKey, any>;
  652. static nonTTY: boolean;
  653. tasks: Task<any, typeof ListrBaseRenderer>[];
  654. options: typeof ListrBaseRenderer.rendererOptions;
  655. render: () => void;
  656. end: (err?: Error) => void;
  657. constructor(tasks: Task<any, typeof ListrBaseRenderer>[], options: typeof ListrBaseRenderer.rendererOptions);
  658. }
  659. /** A renderer factory from the current type */
  660. type ListrRendererFactory = typeof ListrRenderer;
  661. /** Supported type of renderers for each type in the listr. */
  662. interface SupportedRenderer {
  663. renderer: ListrRendererFactory;
  664. nonTTY: boolean;
  665. }
  666. /** Listr Default Context */
  667. type ListrContext = any | undefined;
  668. /**
  669. * ListrTask.
  670. *
  671. * Defines the task, conditions and options to run a specific task in the listr.
  672. */
  673. interface ListrTask<Ctx = ListrContext, Renderer extends ListrRendererFactory = any> {
  674. /**
  675. * Title of the task.
  676. *
  677. * Give this task a title if you want to track it by name in the current renderer.
  678. *
  679. * Tasks without a title will hide in the default renderer and are useful for running a background instance.
  680. * On verbose renderer, state changes from these tasks will log as 'Task without a title.'
  681. */
  682. title?: string;
  683. /**
  684. * The task itself.
  685. *
  686. * Task can be a sync or async function, an Observable, or a Stream.
  687. * Task will be executed, if the certain criteria of the state are met and whenever the time for that specific task has come.
  688. */
  689. task: (ctx: Ctx, task: TaskWrapper<Ctx, Renderer>) => void | ListrTaskResult<Ctx>;
  690. /**
  691. * Skip this task depending on the context.
  692. *
  693. * The function that has been passed in will be evaluated at the runtime when the task tries to initially run.
  694. */
  695. skip?: boolean | string | ((ctx: Ctx) => boolean | string | Promise<boolean | string>);
  696. /**
  697. * Enable a task depending on the context.
  698. *
  699. * The function that has been passed in will be evaluated at the initial creation of the Listr class for rendering purposes,
  700. * as well as re-evaluated when the time for that specific task has come.
  701. */
  702. enabled?: boolean | ((ctx: Ctx) => boolean | Promise<boolean>);
  703. /**
  704. * Adds the given number of retry attempts to the task if the task fails.
  705. */
  706. retry?: number;
  707. /**
  708. * Runs a specific event if the current task or any of the subtasks has failed.
  709. *
  710. * Mostly useful for rollback purposes for subtasks.
  711. * But can also be useful whenever a task is failed and some measures have to be taken to ensure the state is not changed.
  712. */
  713. rollback?: (ctx: Ctx, task: TaskWrapper<Ctx, Renderer>) => void | ListrTaskResult<Ctx>;
  714. /**
  715. * Set exit on the error option from task-level instead of setting it for all the subtasks.
  716. */
  717. exitOnError?: boolean | ((ctx: Ctx) => boolean | Promise<boolean>);
  718. /**
  719. * Per task options, that depends on the selected renderer.
  720. *
  721. * These options depend on the implementation of the selected renderer. If the selected renderer has no options it will
  722. * be displayed as never.
  723. */
  724. options?: ListrGetRendererTaskOptions<Renderer>;
  725. }
  726. /**
  727. * Options to set the behavior of this base task.
  728. */
  729. interface ListrOptions<Ctx = ListrContext> {
  730. /**
  731. * To inject a context through this options wrapper. Context can also be defined in run time.
  732. *
  733. * @default {}
  734. */
  735. ctx?: Ctx;
  736. /**
  737. * Concurrency sets how many tasks will be run at the same time in parallel.
  738. *
  739. * @default false > Default is to run everything synchronously.
  740. *
  741. * `true` will set it to `Infinity`, `false` will set it to synchronous.
  742. *
  743. * If you pass in a `number` it will limit it to that number.
  744. */
  745. concurrent?: boolean | number;
  746. /**
  747. * Determine the default behavior of exiting on errors.
  748. *
  749. * @default true > exit on any error coming from the tasks.
  750. */
  751. exitOnError?: boolean;
  752. /**
  753. * Determine the behavior of exiting after rollback actions.
  754. *
  755. * This is independent of exitOnError, since failure of a rollback can be a more critical operation comparing to
  756. * failing a single task.
  757. *
  758. * @default true > exit after rolling back tasks
  759. */
  760. exitAfterRollback?: boolean;
  761. /**
  762. * Collects errors to `ListrInstance.errors`
  763. *
  764. * This can take up a lot of memory, so disabling it can fix out-of-memory errors
  765. *
  766. * - 'full' will clone the current context and task in to the error instance
  767. * - 'minimal' will only collect the error message and the location
  768. * - false will collect no errors
  769. *
  770. * @default 'minimal'
  771. */
  772. collectErrors?: false | 'minimal' | 'full';
  773. /**
  774. * By default, Listr2 will track SIGINIT signal to update the renderer one last time before completely failing.
  775. *
  776. * @default true
  777. */
  778. registerSignalListeners?: boolean;
  779. /**
  780. * Determine the certain condition required to use the non-TTY renderer.
  781. *
  782. * @default null > handled internally
  783. */
  784. rendererFallback?: boolean | (() => boolean);
  785. /**
  786. * Determine the certain condition required to use the silent renderer.
  787. *
  788. * @default null > handled internally
  789. */
  790. rendererSilent?: boolean | (() => boolean);
  791. /**
  792. * Disabling the color, useful for tests and such.
  793. *
  794. * @default false
  795. */
  796. disableColor?: boolean;
  797. /**
  798. * Inject data directly to TaskWrapper.
  799. */
  800. injectWrapper?: {
  801. enquirer?: Enquirer<object>;
  802. };
  803. }
  804. /**
  805. * Task can be set of sync or async function, an Observable or a stream.
  806. */
  807. type ListrTaskResult<Ctx> = string | Promise<any> | Listr<Ctx, ListrRendererValue, any> | Readable | NodeJS.ReadableStream | Observable<any>;
  808. /**
  809. * Parent class options.
  810. *
  811. * Parent class has more options where you can also select the and set renderer and non-tty renderer.
  812. *
  813. * Any subtasks will respect those options so they will be stripped of that properties.
  814. */
  815. type ListrBaseClassOptions<Ctx = ListrContext, Renderer extends ListrRendererValue = ListrDefaultRendererValue, FallbackRenderer extends ListrRendererValue = ListrFallbackRendererValue> = ListrOptions<Ctx> & ListrDefaultRendererOptions<Renderer> & ListrDefaultNonTTYRendererOptions<FallbackRenderer>;
  816. /**
  817. * Sub class options.
  818. *
  819. * Subtasks has reduced set options where the missing ones are explicitly set by the base class.
  820. */
  821. type ListrSubClassOptions<Ctx = ListrContext, Renderer extends ListrRendererValue = ListrDefaultRendererValue> = ListrOptions<Ctx> & Omit<ListrDefaultRendererOptions<Renderer>, 'renderer'>;
  822. /** The internal communication event. */
  823. type ListrEvent = {
  824. type: Exclude<ListrEventType, 'MESSAGE' | 'DATA'>;
  825. data?: string | boolean;
  826. } | {
  827. type: ListrEventType.DATA;
  828. data: string;
  829. } | {
  830. type: ListrEventType.MESSAGE;
  831. data: Task<any, any>['message'];
  832. };
  833. /**
  834. * Used to match event.type to ListrEvent permutations
  835. */
  836. type ListrEventFromType<T extends ListrEventType, E = ListrEvent> = E extends {
  837. type: infer U;
  838. } ? T extends U ? E : never : never;
  839. /** The internal error handling mechanism.. */
  840. declare class ListrError<Ctx extends ListrContext = ListrContext> extends Error {
  841. error: Error;
  842. type: ListrErrorTypes;
  843. task: Task<Ctx, ListrRendererFactory>;
  844. path: string;
  845. ctx: Ctx;
  846. constructor(error: Error, type: ListrErrorTypes, task: Task<Ctx, ListrRendererFactory>);
  847. }
  848. /**
  849. * The actual error type that is collected and to help identify where the error is triggered from.
  850. */
  851. declare enum ListrErrorTypes {
  852. /** Task has failed and will try to retry. */
  853. WILL_RETRY = "WILL_RETRY",
  854. /** Task has failed and will try to rollback. */
  855. WILL_ROLLBACK = "WILL_ROLLBACK",
  856. /** Task has failed, ran the rollback action but the rollback action itself has failed. */
  857. HAS_FAILED_TO_ROLLBACK = "HAS_FAILED_TO_ROLLBACK",
  858. /** Task has failed. */
  859. HAS_FAILED = "HAS_FAILED",
  860. /** Task has failed, but exitOnError is set to false, so will ignore this error. */
  861. HAS_FAILED_WITHOUT_ERROR = "HAS_FAILED_WITHOUT_ERROR"
  862. }
  863. /** The internal error handling mechanism for prompts only. */
  864. declare class PromptError extends Error {
  865. constructor(message: string);
  866. }
  867. /**
  868. * Creates a new set of Listr2 task list.
  869. */
  870. declare class Listr<Ctx extends ListrContext = ListrContext, Renderer extends ListrRendererValue = ListrDefaultRendererValue, FallbackRenderer extends ListrRendererValue = ListrFallbackRendererValue> {
  871. task: ListrTask<Ctx, ListrGetRendererClassFromValue<Renderer>> | ListrTask<Ctx, ListrGetRendererClassFromValue<Renderer>>[];
  872. options?: ListrBaseClassOptions<Ctx, Renderer, FallbackRenderer>;
  873. parentTask?: Task<any, any>;
  874. tasks: Task<Ctx, ListrGetRendererClassFromValue<Renderer>>[];
  875. err: ListrError<Ctx>[];
  876. ctx: Ctx;
  877. rendererClass: ListrRendererFactory;
  878. rendererClassOptions: ListrGetRendererOptions<ListrRendererFactory>;
  879. renderHook$: Task<any, any>['renderHook$'];
  880. path: string[];
  881. private concurrency;
  882. private renderer;
  883. constructor(task: ListrTask<Ctx, ListrGetRendererClassFromValue<Renderer>> | ListrTask<Ctx, ListrGetRendererClassFromValue<Renderer>>[], options?: ListrBaseClassOptions<Ctx, Renderer, FallbackRenderer>, parentTask?: Task<any, any>);
  884. add(task: ListrTask<Ctx, ListrGetRendererClassFromValue<Renderer>> | ListrTask<Ctx, ListrGetRendererClassFromValue<Renderer>>[]): void;
  885. run(context?: Ctx): Promise<Ctx>;
  886. private checkAll;
  887. private runTask;
  888. }
  889. /**
  890. * Creates a new Listr2 task manager.
  891. *
  892. * Useful for creating a single instance of Listr2 with pre-set settings.
  893. */
  894. declare class Manager<Ctx = ListrContext, Renderer extends ListrRendererValue = 'default', FallbackRenderer extends ListrRendererValue = 'verbose'> {
  895. options?: ListrBaseClassOptions<Ctx, Renderer, FallbackRenderer>;
  896. err: ListrError[];
  897. private tasks;
  898. constructor(options?: ListrBaseClassOptions<Ctx, Renderer, FallbackRenderer>);
  899. set ctx(ctx: Ctx);
  900. add<InjectCtx = Ctx>(tasks: ListrTask<InjectCtx, ListrGetRendererClassFromValue<Renderer>>[] | ((ctx?: InjectCtx) => ListrTask<InjectCtx, ListrGetRendererClassFromValue<Renderer>>[]), options?: ListrSubClassOptions<InjectCtx, Renderer>): void;
  901. runAll<InjectCtx = Ctx>(options?: ListrBaseClassOptions<InjectCtx, Renderer, FallbackRenderer>): Promise<InjectCtx>;
  902. newListr<InjectCtx, InjectRenderer extends ListrRendererValue = Renderer, InjectFallbackRenderer extends ListrRendererValue = FallbackRenderer>(tasks: ListrTask<InjectCtx, ListrGetRendererClassFromValue<InjectRenderer>>[], options?: ListrBaseClassOptions<InjectCtx, InjectRenderer, InjectFallbackRenderer>): Listr<InjectCtx, InjectRenderer, InjectFallbackRenderer>;
  903. indent<InjectCtx = Ctx>(tasks: ListrTask<InjectCtx, ListrGetRendererClassFromValue<Renderer>>[] | ((ctx?: InjectCtx) => ListrTask<InjectCtx, ListrGetRendererClassFromValue<Renderer>>[]), options?: ListrBaseClassOptions<InjectCtx, Renderer, FallbackRenderer>, taskOptions?: Omit<ListrTask<InjectCtx, ListrGetRendererClassFromValue<Renderer>>, 'task'>): ListrTask<InjectCtx, ListrGetRendererClassFromValue<Renderer>>;
  904. run<InjectCtx = Ctx>(tasks: ListrTask<InjectCtx, ListrGetRendererClassFromValue<Renderer>>[], options?: ListrBaseClassOptions<InjectCtx, Renderer, FallbackRenderer>): Promise<InjectCtx>;
  905. getRuntime(pipetime: number): string;
  906. }
  907. /**
  908. * Create a new prompt with Enquirer externally.
  909. * This extends enquirer so you dont have to give a name to single prompts and such so it is also
  910. * useful to use externally.
  911. * @param this
  912. * @param options
  913. * @param settings
  914. */
  915. declare function createPrompt(this: any, options: PromptOptions | PromptOptions<true>[], settings?: PromptSettings): Promise<any>;
  916. declare function destroyPrompt(this: TaskWrapper<any, any>, throwError?: boolean): void;
  917. declare const figures: {
  918. warning: string;
  919. cross: string;
  920. arrowDown: string;
  921. tick: string;
  922. arrowRight: string;
  923. pointer: string;
  924. checkboxOn: string;
  925. arrowLeft: string;
  926. squareSmallFilled: string;
  927. pointerSmall: string;
  928. };
  929. export { Listr, ListrBaseClassOptions, ListrBaseRenderer, ListrContext, ListrDefaultNonTTYRendererOptions, ListrDefaultRenderer, ListrDefaultRendererOptions, ListrDefaultRendererValue, ListrError, ListrErrorTypes, ListrEvent, ListrEventFromType, ListrEventType, ListrFallbackRenderer, ListrFallbackRendererValue, ListrGetRendererClassFromValue, ListrGetRendererOptions, ListrGetRendererTaskOptions, ListrGetRendererValueFromClass, ListrOptions, ListrRenderer, ListrRendererFactory, ListrRendererOptions, ListrRendererValue, ListrSilentRenderer, ListrSilentRendererValue, ListrSimpleRenderer, ListrSimpleRendererValue, ListrSubClassOptions, ListrTask, Task as ListrTaskObject, ListrTaskResult, ListrTaskState, TaskWrapper as ListrTaskWrapper, LogLevels, Logger, Manager, PromptError, PromptInstance, PromptOptions, PromptOptionsMap, PromptOptionsType, PromptSettings, PromptTypes, SupportedRenderer, Unionize, createPrompt, destroyPrompt, figures };