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.
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);
});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 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 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.
Terminal task list
$ npm install --save listr
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.');
}
});
}
], {concurrent: true});
}
},
{
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);
});
A task can return different values. If a task returns, it means the task was completed successfully. If a task throws an error, the task failed.
const tasks = new Listr([
{
title: 'Success',
task: () => 'Foo'
},
{
title: 'Failure',
task: () => {
throw new Error('Bar')
}
}
]);
A task can also be async by returning a Promise. If the promise resolves, the task completed successfully, it it rejects, the task failed.
const tasks = new Listr([
{
title: 'Success',
task: () => Promise.resolve('Foo');
},
{
title: 'Failure',
task: () => Promise.reject('Bar')
}
]);
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'))
}
]);
It's also possible to return a stream. The stream will be converted to an Observable and handled as such.
Optionally specify a skip function to determine whether a task can be skipped.
skip function returns a truthy value or a Promise that resolves to a truthy value then the task will be skipped.skip function returns a falsey value or a Promise that resolves to a falsey value then the task will be executed as normal.skip function throws or returns a Promise that rejects, the task (and the whole build) will fail.const tasks = new Listr([
{
title: 'Task 1',
task: () => Promise.resolve('Foo')
},
{
title: 'Can be skipped',
skip: () => {
if (Math.random() > 0.5) {
return 'Reason for skipping';
}
},
task: () => 'Bar'
},
{
title: 'Task 3',
task: () => Promise.resolve('Bar')
}
]);
Type: object[]
List of tasks.
Type: string
Title of the task.
Type: Function
Task function.
Type: Function
Skip function. Read more about skipping tasks.
Type: boolean
Default: true
Set to false if you want to disable the rendering of the subtasks. Subtasks will be rendered if
an error occurred in one of them.
Type: boolean
Default: false
Set to true if you want tasks to run concurrently.
Returns the instance.
Type: object object[]
Task object or multiple task objects.
Start executing the tasks.
MIT © Sam Verschueren
FAQs
Terminal task list
The npm package listr receives a total of 1,528,801 weekly downloads. As such, listr popularity was classified as popular.
We found that listr demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.