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

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

Name	Type
`ctx`	`Ctx`
`task`	`ListrTaskWrapper`<`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

Name	Type
`ctx`	`Ctx`
`task`	`ListrTaskWrapper`<`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

Name	Type
`enquirer?`	`Enquirer`<`object`>

Defined in

src/interfaces/listr.interface.ts:155