multispinner

Install multispinner as a standard Node.js module using npm. This module requires Node.js 4.0 or newer.

$ npm install --save multispinner

Import the Multispinner class into your Node.js application using the standard require syntax.

var Multispinner = require('multispinner')

The repository contains several illustrative examples of how to use the module in different scenarios:

• events.js: Demonstrates creating spinners from an array and responding to success and err completion events using staggered setTimeout calls.
• customAnimation.js: Shows how to define a custom spinner animation using the frames option.
• randomInfiniteLoop.js: Demonstrates creating a variable number of spinners with random text that complete randomly in an infinite loop.
• cli-with-promises: A practical example of a CLI app that uses Promise.all() to execute multiple HTTP GET requests in parallel, with a dedicated spinner for each URL.

To run these examples, navigate to the extras/examples directory and use node:

$ node <example_filename>

$ node <example>

Use these methods to manage the state and animation of your spinners:

• multispinner.start(): Starts the animation. Only call this if autoStart was set to false in the constructor. Calling it when autoStart is true will cause double-speed animation and dropped frames.
• multispinner.success(spinner): Marks a specific spinner (by its string ID) as completed with a success state. This updates its symbol and color.
• multispinner.error(spinner): Marks a specific spinner (by its string ID) as completed with an error state. This updates its symbol and color.

const multispinner = new Multispinner(['foo', 'bar'], { preText: 'Downloading' });

const fooTask = new Promise((resolve, reject) => {
  // async work
});

fooTask
  .then((res) => {
    multispinner.success('foo');
  })
  .catch((err) => {
    multispinner.error('foo');
  });

When instantiating Multispinner, you can pass an opts object to customize the animation behavior. Common options include:

• interval: The delay between animation frames (in milliseconds).
• autoStart: If true, the animation loop starts immediately upon construction.
• frames: An array of strings representing the animation frames.
• indent: Number of spaces to indent the spinners.
• preText: Text to display before the spinners.
• postText: Text to display after the spinners.
• color: An object mapping states to chalk colors.
• clear: If true, the spinners are cleared from the terminal once all are completed.

Use these methods to programmatically inspect the state of the multispinner instance:

• allCompleted(): Returns true if every spinner's state is no longer incomplete.
• allSuccess(): Returns true if every spinner's state is exactly success.
• anyErrors(): Returns an array of strings containing the names of all spinners currently in the error state.

You can manually transition a specific spinner to a terminal state using the success(spinner) or error(spinner) methods. This will update the visual symbol and trigger the appropriate events when all spinners reach a completed state.

// Assuming 'ms' is an instance of Multispinner

// Mark a specific spinner as successful
ms.success('task1');

// Mark a specific spinner as failed
ms.error('task2');

The Multispinner class is the main entrypoint for managing multiple concurrent progress indicators in the terminal. It extends EventEmitter, allowing you to listen for lifecycle events like done, success, or err.

const Multispinner = require('node-multispinner');

const spinners = {
  task1: 'Downloading files...',
  task2: 'Installing dependencies...'
};

const opts = {
  interval: 100,
  autoStart: true
};

const ms = new Multispinner(spinners, opts);

Since Multispinner is an EventEmitter, you can react to the completion of the entire batch of spinners.

• done: Emitted when all spinners have moved out of the incomplete state.
• success: Emitted if all spinners reached the success state.
• err: Emitted for each spinner that reached the error state. The event payload is the name of the spinner.

ms.on('done', () => {
  console.log('All tasks finished!');
});

ms.on('success', () => {
  console.log('Everything succeeded!');
});

ms.on('err', (spinnerName) => {
  console.error(`Task failed: ${spinnerName}`);
});