Package Exports
- listr
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (listr) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
listr
Terminal task list
Install
$ npm install --save listrUsage
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);
});Task
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')
}
}
]);Promises
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')
}
]);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.
Skipping tasks
Optionally specify a skip function to determine whether a task can be skipped.
- If the
skipfunction returns a truthy value or aPromisethat resolves to a truthy value then the task will be skipped. - If the returned value is a string it will be displayed as the reason for skipping the task.
- If the
skipfunction returns a falsey value or aPromisethat resolves to a falsey value then the task will be executed as normal. - If the
skipfunction throws or returns aPromisethat 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')
}
]);Context
A context object is being passed as argument into every skip and task function. This allows you to create composable tasks and change the behaviour of your task depending on previous results.
const tasks = new Listr([
{
title: 'Task 1',
skip: ctx => ctx.foo === 'bar',
task: () => Promise.resolve('Foo')
},
{
title: 'Can be skipped',
skip: () => {
if (Math.random() > 0.5) {
return 'Reason for skipping';
}
},
task: ctx => {
ctx.unicorn = 'rainbow';
}
},
{
title: 'Task 3',
task: ctx => Promise.resolve(`${ctx.foo} ${ctx.bar}`)
}
]);
tasks.run({
foo: 'bar'
}).then(ctx => {
console.log(ctx);
//=> {foo: 'bar', unicorn: 'rainbow'}
});Custom renderers
It's possible to write custom renderers for Listr. A renderer is an ES6 class that accepts the tasks that it should renderer, and the Listr options object. It has two methods, the render method which is called when it should start rendering, and the end method. The end method is called all the tasks are completed or if a task failed. If a task failed, the error object is passed in via an argument.
class CustomRenderer {
constructor(tasks, options) { }
render() { }
end(err) { }
}
module.exports = CustomRenderer;Note: A renderer is not passed through to the subtasks, only to the main task. It is up to you to handle that case.
Observables
Every task is an observable. The task emits three different events and every event is an object with a type property.
- The state of the task has changed (
STATE). - The task outputted data (
DATA). - The task returns a subtask list (
SUBTASKS).
This allows you to flexibly build up your UI. Let's render every task that starts executing.
class CustomRenderer {
constructor(tasks, options) {
this._tasks = tasks;
this._options = Object.assign({}, options);
}
render() {
for (const task of this._tasks) {
task.subscribe(event => {
if (event.type === 'STATE' && task.isPending()) {
console.log(`${task.title} [started]`);
}
});
}
}
end(err) { }
}
module.exports = CustomRenderer;If you want more complex examples, take a look at the update and verbose renderers.
API
Listr([tasks], [options])
tasks
Type: object[]
List of tasks.
title
Type: string
Title of the task.
task
Type: Function
Task function.
skip
Type: Function
Skip function. Read more about skipping tasks.
options
Any renderer specific options.
concurrent
Type: boolean
Default: false
Set to true if you want tasks to run concurrently.
renderer
Type: string object
Default: default
Options: default verbose silent
Renderer that should be used. You can either pass in the name of the known renderer, or a class of a custom renderer.
Instance
add(task)
Returns the instance.
task
Type: object object[]
Task object or multiple task objects.
run([context])
Start executing the tasks. Returns a Promise for the context object.
context
Type: object
Default: Object.create(null)
Initial context object.
Related
- ora - Elegant terminal spinner
- cli-spinners - Spinners for use in the terminal
License
MIT © Sam Verschueren