listr2

Appearance

v6.0.0 has many new features, speed improvements and dependency updates.

Foreword ​

I am aware that breaking changes are inconvenient. Breaking changes that require you to refactor your code in this repository is rare and far between.

But this is a big update where a core component like rxjs has been replaced with an event-emitter-based approach, which is required to refactor anything that is renderer related.

So in this update, custom renderers might take the biggest hit since rendering has been completely refactored.

While doing so I have decided to address one of the biggest problems with the repository. While using an updating renderer like DefaultRenderer, you might accidentally or unwillingly log into the console, where this completely breaks the underlying log-update library. Now there is a ProcessOutput abstraction is in place to avoid this as much as we can.

The naming scheme of some options was inconsistent and was bugging me for a long-time. Some of the fields are just kept to be somewhat compatible with the original Listr library. Since this is no longer a concern of mine and this library is extended beyond it is compatibility with the original, I have taken the initiative to update some options with a more consistent naming scheme.

Migration ​

WARNING

If you encounter any more of the breaking changes, please feel free to contribute by editing this page.

  • node.js version 16 is required as a minimum since support for version 14 has been terminated.
  • The fallback renderer default has been changed from VerboseRenderer to SimpleRenderer since it is mostly non-TTY compatible if there are no prompts.
  • rxjs has been dropped in favor of an event-emitter-based approach with eventemitter3. This will possibly break every custom renderer since custom-renderers might rely on subscribe on Task. The refactoring is nothing very marginal where you can compare the current and old VerboseRenderer for guidance.
  • The Listr and Manager err fields have been renamed to errors for consistency.
  • DefaultRenderer default output format, which handles fitting the rendered data inside the terminal columns, has been changed from truncate to wrap, since it is the more logical choice to display all the output data.
  • The Listr options nonTTYRenderer and nonTTYRendererOptions have been renamed to fallbackRenderer, fallbackRendererOptions respectively for consistency.
  • The Listr options fallbackCondition and silentCondition have been renamed to fallbackRendererCondition, silentRendererCondition respectively for consistency.
  • The Listr option collectErrors default behavior has been changed from 'minimal' to false since this is the most underused functionality and decided that it should be opt-in for saving some memory.
  • The Listr property path which is mostly used for collecting the errors to find out the task hierarchy is now an array of strings instead of a joined string.
  • The ListrLogger implementation has been completely reworked and renamed from Logger to ListrLogger, anything that relies on it has to be reworked.
  • Most of the internal API of the library is now exported, so you can directly use functionality like color through colorrette etc. without bringing your own library.
  • DefaultRenderer, VerboseRenderer and SimpleRenderer now use pluggable components for timestamps and task time parsing.
  • DefaultRenderer options collapse which corresponded whether the subtasks would be collapsed or not is renamed to collapseSubtasks for consistency.
  • DefaultRenderer option suffixSkips now has the default value of false where it would not have [SKIPPED] at the end of the task.
  • VerboseRenderer no longer has the field logEmptyTitle and skips tasks without titles instead of logging them as 'Task without title.'.
  • TestRenderer is encouraged to be used for testing purposes instead of VerboseRenderer.
  • ListrTaskState PENDING has been renamed to STARTED and ListrEventType DATA has been renamed to OUTPUT for consistency.
  • ListrTaskRetry which is the output of the task.isRetrying() now holds the error value in error instead of prior withError.
  • The Listr now has additional options to forceColor and forceTTY since this was a complaint.
  • To use up-to-date dependencies, everything development related in the repository has been converted to esm and DefaultRenderer now imports anything esm through dynamical imports.
  • Prompts in the tasks now have their channel, which might break your custom renderer implementation.