The spinner package provides a foundation for updatable texts, including spinners.

spinner/index.js

The spinner/index.js module is the main user-facing module of the package.

The module exports:

• Spinner class of spinner/spinner.js module exported by name.
• spin() function of spinner/spin.js module exported by name and as the default export.

import spin, {Spinner} from 'console-toolkit/spinner/index.js';

spinner/spinner.js

The spinner/spinner.js module provides the SpinnerBase and Spinner classes. The former serves as a foundation for updatable texts. The latter can be instantiated with a spinner definition.

Class SpinnerBase

The SpinnerBase class has the following properties:

Name	Return type	Description
constructor(isStarted)	SpinnerBase	Creates a new SpinnerBase instance.
isStarted	boolean	Returns true if the spinner is started.
isActive	boolean	Returns true if the spinner is active.
isFinished	boolean	Returns true if the spinner is finished.
state	string	Gets/sets the state of the spinner.
reset()	—	Resets the spinner.
nextFrameIndex(length)	number	Gets the next frame index from 0 to length - 1.
getFrame()	string	Gets the current frame.

state can be one of the following string values:

• the empty string ('') — the spinner is not started.
• 'active' — the spinner is active.
• 'paused' — the spinner is paused.
• 'finished' — the spinner is finished.

reset() resets the spinner to its initial state.

nextFrameIndex(length) can be used to get a frame from an array of frames.

getFrame() can be used to get the current frame. SpinnerBase implements this method as a stub, which returns a static string. It should be overridden in subclasses.

The SpinnerBase class implements the same interface as an updater object in output/updater.js.

Class Spinner

The Spinner class has the following properties:

Name	Return type	Description
constructor(spinnerDefinition, isStarted)	Spinner	Creates a new Spinner instance.

The Spinner class extends SpinnerBase class and implements getFrame() method.

spinnerDefinition is an object with the following properties:

• frames — an array of frames. A frame could be a strings object or a value that can be coerced to strings. See Concepts: strings.
• notStarted — an array of frames used when the spinner is not started. Defaults to [' '].
• finished — an array of frames used when the spinner is finished. Defaults to ['✓'].

This class is used to create spinners defined in spinner/spinners.js (see below).

Exports

SpinnerBase is exported by name. Spinner is exported by name and as the default export.

spinner/spin.js

The spinner/spin.js module provides the spin() function, which is a back-quote function to create an updatable string. It returns a specialized object based on the SpinnerBase class.

import spin, {Spinner} from 'console-toolkit/spinner/index.js';
import {bouncingBall} from 'console-toolkit/spinner/spinners.js';
import {Updater} from 'console-toolkit/output/updater.js';

const spinner = spin`Spinner: [${new Spinner()}], ${new Spinner(bouncingBall)}, state: ${state => state}`;
const updater = new Updater(spinner);

if (updater.writer.isTTY) {
  updater.update(); // draw the initial frame now
  updater.startRefreshing();
} else {
  updater.final(); // just draw the last frame
}

// Example - Spinner: [⠸], (    ● ), state: active

The following arguments are supported:

• a function — it will be called fn(state) and should return a string.
• a SpinnerBase object — the state will be set and the getFrame() method is called, which should return a string.
• an array of strings — its elements will be used sequentially.
• a string — it will be used as is.

Exports

spin() is exported as the default export.

spinner/spinners.js

The spinner/spinners.js module exports a collection of spinner definitions. See file for more details.