@std/cli: Support multiple spinners at the same time

[nnmrts]

Currently, if one tries to display multiple spinners at the same time, the spinners "override" each other.

import { Spinner } from "@std/cli";

const spinner1 = new Spinner({
	color: "yellow",
	message: "Loading..."
});

const spinner2 = new Spinner({
	color: "red",
	message: "Loading..."
});

const spinner3 = new Spinner({
	color: "blue",
	message: "Loading..."
});

spinner1.start();

setTimeout(() => {
	spinner1.stop();
	console.info("Finished loading!");
}, 3_000);

setTimeout(() => {
	spinner2.start();

	setTimeout(() => {
		spinner2.stop();
		console.info("Finished loading!");
	}, 3_000);
}, 1_000);

setTimeout(() => {
	spinner3.start();
	setTimeout(() => {
		spinner3.stop();
		console.info("Finished loading!");
	}, 2_000);
}, 4_000);

Running the above code looks like this:

Bildschirmaufnahme.2024-06-13.um.22.54.02.mov

Therefore I propose enhancing the existing Spinner class or even adding a new MultiSpinner class to avoid introducing breaking changes, that is able to handle multiple spinners, like so:

import { Spinner } from "@std/cli";

import { ansi } from "@cliffy/ansi";

const activeMultiSpinners = [];

const MultiSpinner = class extends Spinner {

	static #updateMultiSpinners = () => {
		const runningMultiSpinners = activeMultiSpinners
			.filter((multiSpinner) => multiSpinner.running);

		for (const [index, multiSpinner] of runningMultiSpinners.entries()) {
			if (runningMultiSpinners.length > 1) {
				multiSpinner.message = index === runningMultiSpinners.length - 1
					? `${multiSpinner.actualMessage}${ansi.cursorUp(index)}`
					: `${multiSpinner.actualMessage}${ansi.cursorDown(1)}`;
			}
			else {
				multiSpinner.message = multiSpinner.actualMessage;
			}
		}
	};

	actualMessage = "";

	running = false;

	constructor({
		color,
		message
	} = {}) {
		super({
			color,
			message
		});

		this.actualMessage = message;

		activeMultiSpinners.push(this);
	}

	start() {
		this.running = true;
		MultiSpinner.#updateMultiSpinners();
		super.start();
	}

	stop(message) {
		this.running = false;
		MultiSpinner.#updateMultiSpinners();
		super.stop();
	}

};

export default MultiSpinner;

Running the example from before with this new MultiSpinner class looks like this:

Bildschirmaufnahme.2024-06-13.um.23.01.14.mov

Obviously my code was just a quick test to see if this even works, I used @cliffy/ansi to make it simpler, a global activeMultiSpinners array is probably not the way to go and timing might also be buggy (no idea in which order updateMultiSpinners and stop should be called). And I don't even want to know what happens if something like ⏎ is pressed. 😅

But yeah, what do you think about this addition? I personally was a bit surprised it was that easy to augment the base Spinner class, so it might not be that difficult to actually add this, using the same cursorDown(1) and cursorUp(length - 1) logic.

[kt3k]

Is this common pattern in cli tool development? I personally don't often see the multiple spinners in cli tools in general.

[nnmrts]

I also don't see it often, but maybe that's because there is no popular library for this yet? I could only find these two:

• https://github.com/jbcarpanelli/spinnies (last commit 5 years ago)
• https://github.com/codekirei/node-multispinner (last commit 9 years ago)

[andrewthauer]

It's quite common for multiple progress bars (ie docker) and less so for spinners.

Minikube is an example that uses multiple spinners on setup to show a series of async tasks running.

Multiple spinners can be useful for anytime you need to do tasks in parallel, but can't really track individual progress steps.

[iuioiua]

This is a reasonable expectation for a spinner implementation. SGTM.

[nnmrts]

Btw, the snippet I shared above is broken in so many ways, so whoever implements this shouldn't take much inspiration from it. It turned out to be a bit more challenging to do this right, especially when trying to support "nested" spinners (s1 starts - s2 starts - s2 stops - s1 stops) or when trying to combine spinners with normal console.log output.

[kt3k]

Popular npm packages (ora, cli-spinners) that implement spinners don't support multiple spinners. I'm skeptical the users need this feature.

If we add this feature, I expect the added complexity won't be small. I wonder if it's worth the effort for such rarely used feature.

Minikube is an example that uses multiple spinners on setup to show a series of async tasks running.

Can anybody give more examples of multiple loading indicators in CLI tools? If minikube is only common example, then it feels too rare feature to provide support in the standard library.

[iuioiua]

Hmm, fair point. This may not be worth the added complexity incurred. I think this is fine as long as we provide justification and possible workarounds in the documentation.

[kt3k]

(Sharing another point raised in an offline discussion.)

When there are multiple things going on in CLI tools, I often see the single loading indicator with the message part changing quickly (e.g. npm install shows its progress in this way). I guess that would be more common way to show the progress of multiple things in a terminal app.

[nnmrts]

Yeah...currently in my project, I went forward with a "single-line" approach as well, to track multiple, especially nested, processes, looking like this:

import { Spinner } from "@std/cli";

/**
 * @implements {Spinner}
 * @extends {Spinner}
 * @example
 * const loader = new Loader({
 * 	color: "blue",
 * 	message: "Loading..."
 * });
 *
 * loader.start(); // "Loading..."
 *
 * await new Promise((resolve) => setTimeout(resolve, 1000));
 *
 * loader.setBlock("block1", "a"); // "1 | a"
 *
 * await new Promise((resolve) => setTimeout(resolve, 1000));
 *
 * loader.setBlock("block1", "b"); // "2 | b"
 * loader.setBlock("block2", "c"); // "3 | b | c"
 *
 * await new Promise((resolve) => setTimeout(resolve, 1000));
 *
 * loader.removeBlock("block1"); // "4 | c"
 *
 * await new Promise((resolve) => setTimeout(resolve, 1000));
 *
 * loader.stop();
 */
const Loader = class extends Spinner {

	/**
	 * @type {Map<unknown, string>}
	 */
	#blocks = new Map();

	/**
	 * @type {Map<unknown, number>}
	 */
	#maximumLengths = new Map();

	/**
	 * @type {number}
	 */
	#messageCount = 0;

	/**
	 * @type {unknown[]}
	 */
	#order = [];

	/**
	 * Updates the message.
	 *
	 * @example
	 * this.#updateMessage();
	 */
	#updateMessage = () => {
		this.message = [
			this.#messageCount,
			...this.#order
				.filter((blockId) => this.#blocks.has(blockId))
				.map((blockId, index) => {
					const blockValue = this.#blocks.get(blockId);

					return (
						index === 0
							? blockValue
							: blockValue.padStart(this.#maximumLengths.get(blockId))
					);
				})

		]
			.join(" | ");
	};

	/**
	 *
	 * @param {unknown} id - The id of the block.
	 * @example
	 * const loader = new Loader({
	 * 	color: "blue",
	 * 	message: "Loading..."
	 * });
	 *
	 * loader.start();
	 *
	 * loader.setBlock("block1", "value1");
	 *
	 * loader.removeBlock("block1");
	 *
	 * loader.stop();
	 */
	removeBlock = (id) => {
		this.#blocks.delete(id);

		this.#messageCount += 1;

		if (this.#messageCount % 1 === 0) {
			this.#updateMessage();
		}
	};

	/**
	 * Set the value of a block.
	 *
	 * @param {unknown} id - The id of the block.
	 * @param {string|number|boolean} value - The value of the block.
	 * @example
	 * const loader = new Loader({
	 * 	color: "blue",
	 * 	message: "Loading..."
	 * });
	 *
	 * loader.start();
	 *
	 * loader.setBlock("block1", "value1");
	 *
	 * loader.stop();
	 */
	setBlock = (id, value) => {
		const valueString = String(value);

		this.#maximumLengths.set(id, Math.max(
			this.#maximumLengths.get(id) ?? 0,
			valueString.length
		));

		this.#blocks.set(id, valueString);

		if (!this.#order.includes(id)) {
			this.#order.push(id);
		}

		this.#messageCount += 1;

		this.#updateMessage();
	};

};

export default Loader;

Bildschirmaufnahme.2024-06-18.um.17.25.55.mov

Bildschirmaufnahme.2024-06-18.um.17.24.09.mov

It works for now, but if the list of things I want to track gets longer, one line might just not be enough.