Package Exports

@topcli/spinner
@topcli/spinner/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@topcli/spinner) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 asynchronous.

All available spinners are part of cli-spinners package.

Requirements

Node.js v22 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(withPrefix, succeed = true) {
    const spinner = new Spinner()
      .start("Start working!", { withPrefix });

    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 Promise.allSettled([
    fnWithSpinner(),
    fnWithSpinner("Item 1"),
    fnWithSpinner("Item 2", false)
]);
Spinner.reset(); // reset internal count
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 timers.setTimeout(1_000);
spinner.text = "Work in progress...";

await timers.setTimeout(1_000);
spinner.succeed("All done !");

[!TIP] 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

constructor(options?: ISpinnerOptions)

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

export interface ISpinnerOptions {
  /**
   * Spinner name (from cli-spinners lib)
   *
   * @default "dots"
   */
  name?: cliSpinners.SpinnerName;
  /**
   * Spinner frame color
   *
   * @default "white"
   */
  color?: string;
  /**
   * Do not log anything when disabled
   *
   * @default true
   */
  verbose?: boolean;
}

[!TIP] Check cli-spinners for all the spinner name.

new Spinner({ name: "dots2" });

start(text?: string, options?: IStartOptions): Spinner

Start the spinner and optionaly write the text passed as first parameter.

The options payload is described by the following TypeScript interface:

export interface IStartOptions {
  withPrefix?: string;
}

succeed(text?: string): void

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

failed(text?: string): void

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

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_Gentilhomme
💻 📖 👀 🛡️ 🐛

_{Alexandre Malaj}
💻 📖 🐛

_{PierreDemailly}
💻 🚧

_Ben
🐛

License

MIT