Spinner

Asynchronous CLI Spinner. This package has been created to handle simultaneous/multiple spinner at a time. The package has been inspired by Ora but in Asynchronous.

All available spinners are part of cli-spinners package.

Requirements

Node.js v16 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @topcli/spinner
# or
$ yarn add @topcli/spinner

Usage example

Create and wait multiple spinner at a time.

import * as timers from "node:timers/promises";
import Spinner from "@topcli/spinner";

async function fnWithSpinner(prefixText, succeed = true) {
    const spinner = new Spinner({ prefixText }).start("Start working!");

    await timers.setTimeout(1000);
    spinner.text = "Work in progress...";
    await timers.setTimeout(1000);

    if (succeed) {
        spinner.succeed(`All done in ${spinner.elapsedTime.toFixed(2)}ms !`);
    }
    else {
        spinner.failed("Something wrong happened !");
    }
}

await Spinner.startAll([
    fnWithSpinner,
    Spinner.create(fnWithSpinner),
    Spinner.create(fnWithSpinner, "Item 1"),
    Spinner.create(fnWithSpinner, "Item 2", false)
]);
console.log("All spinners finished!");

If you want to only achieve one Spinner by one Spinner, use it like Ora (it will work)

const spinner = new Spinner().start("Start working!");

await sleep(1000);
spinner.text = "Work in progress...";

await sleep(1000);
spinner.succeed("All done !");

👀 When you are working on a CLI that can be used as an API too, the verbose option allow you to disable the Spinner.

API

Spinner line structure : ${spinner} ${prefixText} - ${text}

Properties :

declare namespace Spinner {
  public spinner: cliSpinners.Spinner;
  public prefixText: string;
  public text: string;
  public color: string;
  public started: boolean;
  public startTime: number;
  public stream: TTY.WriteStream;
  public readonly elapsedTime: number;
}

spinner: spinner type (default: "dots")
prefixText: mostly used to differentiate each spinner
text: you can change text at any moment.
color: spinner color
elapsedTime: time elapsed since start() call

constructor(options?: Spinner.options)

Create a new Spinner object. options is described by the following TypeScript interface:

declare namespace Spinner {
  interface spinnerObj {
    frames: string[];
    interval: number;
  }

  interface options {
    spinner: SpinnerObj | Spinner.spinners;
    text: string;
    prefixText: string;
    color: string;
    verbose: boolean;
  }
}

👀 Look cli-spinners for all kind of available spinners.

Example:

import Spinner from "@topcli/spinner";

const spinner = new Spinner();
const dotsSpinner = new Spinner({ spinner: "dots" });

static startAll(functions: Spinner.Handler[], options?: Spinner.startOpt): Promise<any[]>

Start all functions with spinners passed in array.

⚠️ Only accept functions that return a Promise.

Options is described by the following TypeScript interface:

declare namespace Spinner {
  type RecapSet = "none" | "error" | "always";

  interface startOpt {
    recap: RecapSet;
    rejects: boolean;
  }
}

Default recap : always

static create(fn: Spinner.Handler, args?: any): Function|[Function, ...any]

This method allow to pass arguments to our spinner function. This method prevent execute function to earlier.

async function fnWithSpinner(prefixText) {
  const spinner = new Spinner({ prefixText }).start("Start working!");

  await new Promise((resolve) => setTimeout(resolve, 1000));
  spinner.text = "Work in progress...";

  await new Promise((resolve) => setTimeout(resolve, 1000));
  spinner.succeed("All done !");
}

Spinner.startAll([
  fnWithSpinner("Item 1"), // <-- Wrong, it's executed directly, not in startAll
  Spinner.create(fnWithSpinner, "Item 2") // <-- What you should do
])
.then(() => console.log("All spinners finished!"))
.catch(console.error);

start(text?: string): Spinner

Start the spinner in the CLI and write the text passed in param.

import Spinner from "@topcli/spinner";

async function fnWithSpinner() {
  const spinner = new Spinner().start("Start working!");
}

Spinner.startAll([
  fnWithSpinner
])
.then(() => console.log("All spinners finished!"))
.catch(console.error);

succeed(text?: string): void

Stop the spinner in the CLI, write the text passed in param and mark it as succeed with a symbol.

import Spinner from "@topcli/spinner";

async function fnWithSpinner() {
  const spinner = new Spinner().start("Start working!");

  await new Promise((resolve) => setTimeout(resolve, 1000));
  spinner.succeed("All done !");
}

Spinner.startAll([
  fnWithSpinner
])
.then(() => console.log("All spinners finished!"))
.catch(console.error);

failed(text?: string): void

Stop the spinner in the CLI, write the text passed in param and mark it as failed with a symbol.

import Spinner from "@topcli/spinner";

async function fnWithSpinner() {
  const spinner = new Spinner().start("Start working!");

  await new Promise((resolve) => setTimeout(resolve, 1000));
  spinner.failed("Something wrong happened !");
}

Spinner.startAll([
  fnWithSpinner
])
.then(() => console.log("All spinners finished!"))
.catch(console.error);

⚠️ Functions start(), succeed() and failed() are supposed to be executed in a function which return a promise and will be called by Spinner.startAll().

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_Gentilhomme
💻 📖 👀 🛡️ 🐛

_{Alexandre Malaj}
💻 📖 🐛

License

MIT