Task and Options

Task

A single task is an object with the following properties, where the task is the main attraction that the desired function gets executed.

The task can be further customized depending on the context and properties.

task can be one of the following:

  • Function/Promise
  • Listr
  • Stream
  • Observable

Properties

title

Optional title: string

Title of the task.

Give this task a title if you want to track it by name in the current renderer.

Tasks without a title will hide in the default renderer and are useful for running a background instance. On verbose renderer, state changes from these tasks will log as 'Task without a title.'

Defined in

src/interfaces/listr.interface.ts:36


skip

Optional skip: string | boolean | (ctx: Ctx) => string | boolean | Promise<string | boolean>

Skip this task depending on the context.

The function that has been passed in will be evaluated at the runtime when the task tries to initially run.

Defined in

src/interfaces/listr.interface.ts:49


enabled

Optional enabled: boolean | (ctx: Ctx) => boolean | Promise<boolean>

Enable a task depending on the context.

The function that has been passed in will be evaluated at the initial creation of the Listr class for rendering purposes, as well as re-evaluated when the time for that specific task has come.

Defined in

src/interfaces/listr.interface.ts:56


retry

Optional retry: number

Adds the given number of retry attempts to the task if the task fails.

Defined in

src/interfaces/listr.interface.ts:60


exitOnError

Optional exitOnError: boolean | (ctx: Ctx) => boolean | Promise<boolean>

Set exit on the error option from task-level instead of setting it for all the subtasks.

Defined in

src/interfaces/listr.interface.ts:71


options

Optional options: ListrGetRendererTaskOptions<Renderer>

Per task options, that depends on the selected renderer.

These options depend on the implementation of the selected renderer. If the selected renderer has no options it will be displayed as never.

Defined in

src/interfaces/listr.interface.ts:78

Methods

task

task(ctx, task): void | ListrTaskResult<Ctx>

The task itself.

Task can be a sync or async function, an Observable, or a Stream. Task will be executed, if the certain criteria of the state are met and whenever the time for that specific task has come.

Parameters
NameType
ctxCtx
taskListrTaskWrapper<Ctx, Renderer>
Returns

void | ListrTaskResult<Ctx>

Defined in

src/interfaces/listr.interface.ts:43


rollback

Optional rollback(ctx, task): void | ListrTaskResult<Ctx>

Runs a specific event if the current task or any of the subtasks has failed.

Mostly useful for rollback purposes for subtasks. But can also be useful whenever a task is failed and some measures have to be taken to ensure the state is not changed.

Parameters
NameType
ctxCtx
taskListrTaskWrapper<Ctx, Renderer>
Returns

void | ListrTaskResult<Ctx>

Defined in

src/interfaces/listr.interface.ts:67

Options

Options is an object with the following properties, can customize the execution, rendering and behavior of the given task list.

This is a global set of defaults and most of them can be overwritten through defining subtasks and defining per-subtask options.

Properties

ctx

Optional ctx: Ctx

To inject a context through this options wrapper. Context can also be defined in run time.

default {}

Defined in

src/interfaces/listr.interface.ts:90


concurrent

Optional concurrent: number | boolean

Concurrency sets how many tasks will be run at the same time in parallel.

default false > Default is to run everything synchronously.

true will set it to Infinity, false will set it to synchronous.

If you pass in a number it will limit it to that number.

Defined in

src/interfaces/listr.interface.ts:100


exitOnError

Optional exitOnError: boolean

Determine the default behavior of exiting on errors.

default true > exit on any error coming from the tasks.

Defined in

src/interfaces/listr.interface.ts:106


exitAfterRollback

Optional exitAfterRollback: boolean

Determine the behavior of exiting after rollback actions.

This is independent of exitOnError, since failure of a rollback can be a more critical operation comparing to failing a single task.

default true > exit after rolling back tasks

Defined in

src/interfaces/listr.interface.ts:115


collectErrors

Optional collectErrors: false | "minimal" | "full"

Collects errors to ListrInstance.errors

This can take up a lot of memory, so disabling it can fix out-of-memory errors

  • 'full' will clone the current context and task in to the error instance
  • 'minimal' will only collect the error message and the location
  • false will collect no errors

default 'minimal'

Defined in

src/interfaces/listr.interface.ts:127


registerSignalListeners

Optional registerSignalListeners: boolean

By default, Listr2 will track SIGINIT signal to update the renderer one last time before completely failing.

default true

Defined in

src/interfaces/listr.interface.ts:133


rendererFallback

Optional rendererFallback: boolean | () => boolean

Determine the certain condition required to use the non-TTY renderer.

default null > handled internally

Defined in

src/interfaces/listr.interface.ts:139


rendererSilent

Optional rendererSilent: boolean | () => boolean

Determine the certain condition required to use the silent renderer.

default null > handled internally

Defined in

src/interfaces/listr.interface.ts:145


disableColor

Optional disableColor: boolean

Disabling the color, useful for tests and such.

default false

Defined in

src/interfaces/listr.interface.ts:151


injectWrapper

Optional injectWrapper: Object

Inject data directly to TaskWrapper.

Type declaration
NameType
enquirer?Enquirer<object>
Defined in

src/interfaces/listr.interface.ts:155

Edit this page on GitHub Updated at Tue, Feb 1, 2022