Research
Security News
Quasar RAT Disguised as an npm Package for Detecting Vulnerabilities in Ethereum Smart Contracts
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
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 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);
});
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, 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.
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.
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}))
}
]);
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')
}
]);
Tip: You can still skip a task while already executing the
task
function with the task object.
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.
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'}
});
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();
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.
Every task is an observable. The task emits three different events and every event is an object with a type
property.
STATE
).DATA
).SUBTASKS
).TITLE
).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.
Type: object[]
List of tasks.
Type: string
Title of the task.
Type: Function
Task function.
Type: Function
Skip function. Read more about skipping tasks.
Any renderer specific options. For instance, when using the update-renderer
, you can pass in all of its options.
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.
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.
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.
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.
Returns the instance.
Type: object
object[]
Task object or multiple task objects.
Start executing the tasks. Returns a Promise
for the context object.
Type: object
Default: Object.create(null)
Initial context object.
MIT © Sam Verschueren
FAQs
Terminal task list
The npm package listr receives a total of 1,299,834 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.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.