🌜
🌞
listr

listr

v0.14.3

Terminal task list

npm install listr

README

listr

Build Status Linux Build status Windows Coverage Status

Terminal task list

listr

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.');
                        }
                    })
                }
            ], {concurrent: true});
        }
    },
    {
        title: 'Install package dependencies with Yarn',
        task: (ctx, task) => execa('yarn')
            .catch(() => {
                ctx.yarn = false;

                task.skip('Yarn not available, install it via `npm install -g yarn`');
            })
    },
    {
        title: 'Install package dependencies with npm',
        enabled: ctx => ctx.yarn === false,
        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, if it rejects, the task failed.

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

Tip: Always reject a promise with some kind of Error object.

Observable

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 {Observable} = require('rxjs');

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'))
    }
]);

You can use the Observable package you feel most comfortable with, like RxJS or zen-observable.

Streams

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

const fs = require('fs');
const split = require('split');

const list = new Listr([
    {
        title: 'File',
        task: () => fs.createReadStream('data.txt', 'utf8')
            .pipe(split(/\r?\n/, null, {trailing: false}))
    }
]);

Skipping tasks

skipping task

Optionally specify a skip function to determine whether a task can be skipped.

  • If the skip function returns a truthy value or a Promise that 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 skip function returns a falsey value or a Promise that resolves to a falsey value then the task will be executed as normal.
  • If the 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')
    }
]);

Tip: You can still skip a task while already executing the task function with the task object.

Enabling tasks

By default, every task is enabled which means that every task will be executed. However, it's also possible to provide an enabled function that returns whether the task should be executed or not.

const tasks = new Listr([
    {
        title: 'Install package dependencies with Yarn',
        task: (ctx, task) => execa('yarn')
            .catch(() => {
                ctx.yarn = false;

                task.skip('Yarn not available, install it via `npm install -g yarn`');
            })
    },
    {
        title: 'Install package dependencies with npm',
        enabled: ctx => ctx.yarn === false,
        task: () => execa('npm', ['install'])
    }
]);

In the above example, we try to run yarn first, if that fails we will fall back to npm. However, at first only the Yarn task will be visible. Because we set the yarn flag of the context object to false, the second task will automatically be enabled and will be executed.

Note: This does not work in combination with concurrent tasks.

Context

A context object is passed as argument to 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'}
});

Task object

A special task object is passed as second argument to the task function. This task object lets you change the title while running your task, you can skip it depending on some results or you can update the task's output.

const tasks = new Listr([
    {
        title: 'Install package dependencies with Yarn',
        task: (ctx, task) => execa('yarn')
            .catch(() => {
                ctx.yarn = false;

                task.title = `${task.title} (or not)`;
                task.skip('Yarn not available');
            })
    },
    {
        title: 'Install package dependencies with npm',
        skip: ctx => ctx.yarn !== false && 'Dependencies already installed with Yarn',
        task: (ctx, task) => {
            task.output = 'Installing dependencies...';

            return execa('npm', ['install'])
        }
    }
]);

tasks.run();

Custom renderers

It's possible to write custom renderers for Listr. A renderer is an ES6 class that accepts the tasks that it should render, 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 when 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) { }

    static get nonTTY() {
        return false;
    }

    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.

The nonTTY property returns a boolean indicating if the renderer supports non-TTY environments. The default for this property is false if you do not implement it.

Observables

Every task is an observable. The task emits three different events and every event is an object with a type property.

  1. The state of the task has changed (STATE).
  2. The task outputted data (DATA).
  3. The task returns a subtask list (SUBTASKS).
  4. The task's title changed (TITLE).
  5. The task became enabled or disabled (ENABLED).

This allows you to flexibly build your UI. Let's render every task that starts executing.

class CustomRenderer {

    constructor(tasks, options) {
        this._tasks = tasks;
        this._options = Object.assign({}, options);
    }

    static get nonTTY() {
        return true;
    }

    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. For instance, when using the update-renderer, you can pass in all of its options.

concurrent

Type: boolean number
Default: false

Set to true if you want to run tasks in parallel, set to a number to control the concurrency. By default it runs tasks sequentially.

exitOnError

Type: boolean
Default: true

Set to false if you don't want to stop the execution of other tasks when one or more tasks fail.

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.

nonTTYRenderer

Type: string object
Default: verbose

The renderer that should be used if the main renderer does not support TTY environments. You can either pass in the name of the 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.

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

License

MIT © Sam Verschueren

Release Notes

0.14.3
By Sam Verschueren • Published on November 17, 2018
  • Bump dependencies 5157edfcaaf32af74dd6e56d2b195b429b70e9b1
  • Tweak documentation (#109) 927b2daf8eb93a4e9ade36d487563206c66597eb
  • Add notes about Observables libraries (#103) 6d19ba711e0b2a53aa80f957aff182e4306e3f84
  • Fix tests (#123) 2856259d38ddf35b3bfac2935eb9c4dfcad3ec1b
  • Fix example (#124) 792604c898da703a3012dc164ad606c532988670

General

License
MIT
Typescript Types
Tree-shakeable
No

Popularity

GitHub Stargazers
3,041
Community Interest
3,005
Number of Forks
127

Maintenance

Commits
10/219/2202
Last Commit
Open Issues
56
Closed Issues
55
Open Pull Requests
10
Closed Pull Requests
13

Versions

Versions Released
10/219/2201
Latest Version Released
Nov 17, 2018
Current Tags
latest0.14.3

Contributors

SamVerschueren
SamVerschueren
Commits: 80
alexpsi
alexpsi
Commits: 1
okonet
okonet
Commits: 1
southpolesteve
southpolesteve
Commits: 1
scott113341
scott113341
Commits: 1
kostasx
kostasx
Commits: 1
ArfatSalman
ArfatSalman
Commits: 1
LitoMore
LitoMore
Commits: 1
sudo-suhas
sudo-suhas
Commits: 1
reconbot
reconbot
Commits: 1
insipx
insipx
Commits: 1
rap2hpoutre
rap2hpoutre
Commits: 1
chris-olszewski
chris-olszewski
Commits: 1
andywer
andywer
Commits: 1
TylorS
TylorS
Commits: 1