listr

What is listr?

Listr is a Node.js library for creating elegant CLI task lists. It allows you to define a series of tasks that can be executed sequentially or concurrently, with support for dynamic updates, subtasks, and conditional execution.

What are listr's main functionalities?

Sequential Task Execution

This feature allows you to define and execute tasks sequentially. Each task is represented as an object with a title and a task function that returns a promise.

const Listr = require('listr');

const tasks = new Listr([
  {
    title: 'Task 1',
    task: () => Promise.resolve('Task 1 completed')
  },
  {
    title: 'Task 2',
    task: () => Promise.resolve('Task 2 completed')
  }
]);

tasks.run().then(() => {
  console.log('All tasks completed');
}).catch(err => {
  console.error(err);
});

Concurrent Task Execution

This feature allows you to execute tasks concurrently by setting the 'concurrent' option to true. All tasks will run in parallel.

const Listr = require('listr');

const tasks = new Listr([
  {
    title: 'Task 1',
    task: () => Promise.resolve('Task 1 completed')
  },
  {
    title: 'Task 2',
    task: () => Promise.resolve('Task 2 completed')
  }
], { concurrent: true });

tasks.run().then(() => {
  console.log('All tasks completed');
}).catch(err => {
  console.error(err);
});

Conditional Task Execution

This feature allows you to conditionally skip tasks based on a condition. The 'skip' function can return a string to indicate why the task was skipped.

const Listr = require('listr');

const tasks = new Listr([
  {
    title: 'Task 1',
    task: () => Promise.resolve('Task 1 completed')
  },
  {
    title: 'Task 2',
    task: () => Promise.resolve('Task 2 completed'),
    skip: () => {
      if (someCondition) {
        return 'Task 2 skipped';
      }
    }
  }
]);

tasks.run().then(() => {
  console.log('All tasks completed');
}).catch(err => {
  console.error(err);
});

Subtasks

This feature allows you to define subtasks within a main task. Each subtask is represented as an object within a nested Listr instance.

const Listr = require('listr');

const tasks = new Listr([
  {
    title: 'Main Task',
    task: () => new Listr([
      {
        title: 'Subtask 1',
        task: () => Promise.resolve('Subtask 1 completed')
      },
      {
        title: 'Subtask 2',
        task: () => Promise.resolve('Subtask 2 completed')
      }
    ])
  }
]);

tasks.run().then(() => {
  console.log('All tasks completed');
}).catch(err => {
  console.error(err);
});

Other packages similar to listr

ora

Ora is a library for creating elegant terminal spinners. While it focuses on spinners rather than task lists, it can be used in conjunction with task management libraries to provide visual feedback during task execution.

inquirer

Inquirer is a library for creating interactive command-line prompts. It can be used to gather user input before executing tasks, making it a good complement to task management libraries like Listr.

prompts

Prompts is another library for creating interactive command-line prompts. It is similar to Inquirer but offers a more modern API and can be used alongside task management libraries to enhance user interaction.

README

listr

Terminal task list

Install

$ npm install --save listr

Usage

const execa = require('execa');
const Listr = require('listr');

const tasks = new Listr([
	{
		title: 'Git',
		task: () => {
			return new Listr([
				{
					title: 'Checking git status',
					task: () => execa.stdout('git', ['status', '--porcelain']).then(result => {
						if (result !== '') {
							throw new Error('Unclean working tree. Commit or stash changes first.');
						}
					});
				},
				{
					title: 'Checking remote history',
					task: () => execa.stdout('git', ['rev-list', '--count', '--left-only', '@{u}...HEAD']).then(result => {
						if (result !== '0') {
							throw new Error('Remote history differ. Please pull changes.');
						}
					});
				}
			]);
		}
	},
	{
		title: 'Install package dependencies',
		task: () => execa('npm', ['install'])
	},
	{
		title: 'Run tests',
		task: () => execa('npm', ['test'])
	},
	{
		title: 'Publish package',
		task: () => execa('npm', ['publish'])
	}
]);

tasks.run().catch(err => {
	console.error(err);
});

Task

A task can return different values. If a task returns, it means the task was completed succesfully. If a task throws an error, the task failed.

const tasks = new Listr([
	{
		title: 'Success',
		task: () => 'Foo'
	},
	{
		title: 'Failure',
		task: () => {
			throw new Error('Bar')
		}
	}
]);

Promises

A task can also be async by returning a Promise. If the promise resolves, the task completed sucessfully, it it rejects, the task failed.

const tasks = new Listr([
	{
		title: 'Success',
		task: () => Promise.resolve('Foo');
	},
	{
		title: 'Failure',
		task: () => Promise.reject('Bar')
	}
]);

Observable

A task can also return an Observable. The thing about observables is that it can emit multiple values and can be used to show the output of the task. Please note that only the last line of the output is rendered.

const tasks = new Listr([
	{
		title: 'Success',
		task: () => {
			return new Observable(observer => {
				observer.next('Foo');

				setTimeout(() => {
					observer.next('Bar');
				}, 2000);

				setTimeout(() => {
					observer.complete();
				}, 4000);
			});
		}
	},
	{
		title: 'Failure',
		task: () => Promise.reject(new Error('Bar'))
	}
]);

Streams

It's also possible to return a stream. The stream will be converted to an Observable and handled as such.

API

Listr([tasks])

tasks

Type: object[]

List of tasks.

title

Type: string

Title of the task.

task

Type: Function

Task function.

Instance

addTask(task)

Returns the instance.

task

Type: object[]

Task object.

run()

Start executing the tasks.

Related

• ora - Elegant terminal spinner
• cli-spinners - Spinners for use in the terminal

License

MIT © Sam Verschueren