Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/TopCli/Spinner

Elegant Asynchronous Terminal (CLI) Spinner for Node.js
https://github.com/TopCli/Spinner

async cli ora spinner

Last synced: about 2 months ago
JSON representation

Elegant Asynchronous Terminal (CLI) Spinner for Node.js

Host: GitHub
URL: https://github.com/TopCli/Spinner
Owner: TopCli
License: mit
Created: 2019-05-02T08:30:55.000Z (over 5 years ago)
Default Branch: main
Last Pushed: 2024-10-14T04:42:49.000Z (3 months ago)
Last Synced: 2024-11-14T04:35:26.355Z (about 2 months ago)
Topics: async, cli, ora, spinner
Language: TypeScript
Homepage:
Size: 295 KB
Stars: 31
Watchers: 3
Forks: 4
Open Issues: 7
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md

Awesome Lists containing this project

awesome-crafted-nodejs - @slimio/async-cli-spinner - Elegant Asynchronous Terminal (CLI) Spinner for Node.js (Packages / CLI (TTY etc..))

README

        # Spinner

![version](https://img.shields.io/badge/dynamic/json.svg?style=for-the-badge&url=https://raw.githubusercontent.com/TopCli/Spinner/main/package.json&query=$.version&label=Version)

[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg?style=for-the-badge)](https://github.com/TopCli/Spinner/commit-activity)

[![mit](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](https://github.com/TopCli/Spinner/blob/main/LICENSE)

[![scorecard](https://api.securityscorecards.dev/projects/github.com/TopCli/Spinner/badge?style=for-the-badge)](https://ossf.github.io/scorecard-visualizer/#/projects/github.com/TopCli/Spinner)

![build](https://img.shields.io/github/actions/workflow/status/TopCli/Spinner/node.js.yml?style=for-the-badge)

Asynchronous CLI Spinner. This package has been created to handle simultaneous/multiple spinner at a time. The package has been inspired by [Ora](https://github.com/sindresorhus/ora) but asynchronous.

All available spinners are part of [cli-spinners](https://github.com/sindresorhus/cli-spinners#readme) package.







## Requirements

- [Node.js](https://nodejs.org/en/) v20 or higher

## Getting Started

This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).

```bash

$ npm i @topcli/spinner

# or

$ yarn add @topcli/spinner

```

## Usage example

Create and wait multiple spinner at a time.

```js

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)

```js

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:

```ts

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](https://github.com/sindresorhus/cli-spinners#readme) for all the spinner name.

```js

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:

```ts

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 ✨

[![All Contributors](https://img.shields.io/badge/all_contributors-4-orange.svg?style=flat-square)](#contributors-)

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

  

    

      
_Gentilhomme
💻 📖 👀 🛡️ 🐛

      
_{Alexandre Malaj}
💻 📖 🐛

      
_{PierreDemailly}
💻 🚧

      
_Ben
🐛

    

  

## License

MIT