Opinionated library for declaring Listr2 task structure

Listr2 is a very flexible library for running tasks that depend on each other and it allows presenting task status in a beautiful way. However declaring how to run those tasks is rather tedious. Listr2 has 4 renderers but to achieve better clarity they need to be customized. Listr2 supports parallel tasks, but exception in any of those terminates whole process. It's not obvious how to pipe output from external processes to Listr2 so that verbose logs are investigatable. listr2-scheduler is an attempt to address these shortcomings.

Simple example

1import { schedule } from "listr2-scheduler";
2
3const driver = schedule((when, make) => {
4  when(null, make("bundle")).call(createAppBundle);
5  when("bundle").call(uploadAppToStaging);
6  when("bundle").call(uploadBundleMapFileForCrashAnalytics);
7});
8
9driver.run({ printer: "summary" });

Hopefully it's obvious that createAppBundle function will be executed at the beginning and after it finishes uploadAppToStaging and uploadBundleMapFileForCrashAnalytics will be executed in parallel. Here's equivalent ordering in pure Listr2:

1import { Listr } from "listr2";
2
3new Listr(
4  [
5    {
6      title: "Create app bundle",
7      task: async (_, task) => {
8        await createAppBundle();
9
10        return task.newListr(
11          [
12            {
13              title: "Upload app to staging",
14              task: uploadAppToStaging,
15            },
16            {
17              title: "Upload bundle map file for crash analytics",
18              task: uploadBundleMapFileForCrashAnalytics,
19            },
20          ],
21          { concurrent: true }
22        );
23      },
24    },
25  ],
26  {
27    renderer: "default",
28    rendererOptions: {
29      collapseSubtasks: false,
30    },
31  }
32).run();

Besides "summary" printer (which uses default Listr2 renderer with some customizations) listr2-scheduler offers only "verbose" alternative which prints all events with timestamp prefix.

Configuration

When call is provided only executor function, it constructs task title from function name, but task title can be provided separately as shown below.

Conditional tasks can be declared by using ? or ! prefix in input keys. Tasks can have more than one input. Tasks can have maximum one output.

1const ci = Boolean(process.env.CI);
2
3schedule<"ci" | "silent" | "testResults" | "fmtResults">((when, make) => {
4  when("?ci", make("testResults")).call("All tests", runAllTests);
5  when("!ci", make("testResults")).call("Quick tests", runQuickTests);
6  when(null, make("fmtResults")).call("Check code formatting", runPrettier);
7  when(["!ci", "!silent", "fmtResults", "testResults"]).call("Finish", showDoneAlert);
8}).run({ printer: ci ? "verbose" : "summary" }, { ci, silent: false });

For task to start values for all the input keys have to be provided either by config parameter (the second argument to run) or by another task as a result value. When task input key is prefixed with ? the value provided must be truthy, when prefix is ! value must be falsy. If value does not match requirements, task is skipped. When there's no prefix in the key any value for that key is allowed, including undefined and null. However config passed to run cannot provide undefined values. Any keys that are undefined in config must be provided by tasks.

Executor functions

Executor functions for listr2-scheduler receive one argument of type Worker that allows task to update task rendering and execution.

1export type Worker<T = any> = {
2  readonly data: T;
3  readonly printer: "verbose" | "summary";
4  readonly setTitleSuffix: (suffix: string) => void;
5  readonly updateTitle: (title: string) => void;
6  readonly reportStatus: (text: string) => void;
7  readonly publish: (text: string) => void;
8  readonly getTag: (options?: { colored: boolean }) => string;
9  readonly on: (event: "finalize", callback: ErrorCallback<void>) => void;
10  readonly assertCanContinue: (tag?: string) => void;
11  readonly toolkit: Toolkit;
12};

• data is an object that is given as a second argument to run function, and it is augmented by return values of executor functions.

• setTitleSuffix appends to task title in "summary" mode. Suffix remains in the final "summary" report.

• updateTitle updates task title in "summary" mode. Clears title suffix. Title get restored to original in final "summary" report.

• reportStatus prints task status in both "verbose" and "summary" modes.

• publish in "summary" mode prints provided message at the end, in "verbose" mode prints provided message without any prefixes. Useful for warnings and similar important messages.

• getTag returns worker tag that can be used to decorate piped output from external processes to differentiate text coming from multiple parallel tasks.

1import { decorateLines, Worker } from "listr2-scheduler";
2
3export function checkServerConnection(worker: Worker) {
4  decorateLines(worker, "Start pinging", process.stdout);
5  const sub = execa("ping", ["-c", "3", "npmjs.com"]);
6  sub.stdout && decorateLines(worker, sub.stdout, process.stdout);
7  sub.stderr && decorateLines(worker, sub.stderr, process.stderr);
8  await sub;
9}

• on allows executor to be informed about errors in other parallely running executors. NOTE: Only the last registered callback will be invoked.

1async function prepareTestFiles(worker) {
2  const controller = new AbortController();
3  worker.on('finalize', () => controller.abort());
4  await fetch(testFilesBundleUrl, { signal: controller.signal });
5}

• assertCanContinue throws if some parallel executor has thrown an exception.

1async function analyzeSourceFiles(worker) {
2  let completed = 0;
3  for (const filePath of all) {
4    worker.reportStatus('Analyzing ' + filePath);
5    await analyzeFile(filePath);
6    completed += 1;
7    worker.assertCanContinue('Analyzed ' + completed + '/' + all.length);
8  }
9}

• toolkit is by default an empty object. It's type can be augmented with TypeScript declaration and it can be provided as an argument to run directly or via constructor function attach.

1import { schedule } from "listr2-scheduler";
2
3declare module "listr2-scheduler" {
4  interface Toolkit {
5    download: (url: string) => Promise<Maybe<Buffer>>;
6  }
7}
8
9schedule((when) => {
10  when(null).call("Fetch lint rules", ({ toolkit }) => toolkit.download(lintUrl));
11}).run({ printer: "verbose", toolkit: { download } });