@imgildev/nspin-render

Overview

Lightweight persistent stdout rendering for Node.js.

nspin-render is a small composable terminal rendering primitive focused on:

• explicit lifecycle semantics
• deterministic stdout persistence
• graceful degradation
• bounded rendering behavior

Installation

bun add @imgildev/nspin-render

npm install @imgildev/nspin-render

Basic Usage

import { Spinner } from "@imgildev/nspin-render";

const spinner = new Spinner({
  frames: ["◐", "◓", "◑", "◒"],
  interval: 80,
  format: ["bold", "cyan"],
});

spinner.start("Loading...");

setTimeout(() => {
  spinner.stop();
}, 2000);

Lifecycle

spinner.start("Loading...");

spinner.pause();

spinner.resume();

spinner.stop();

spinner.destroy();

Lifecycle operations are:

• idempotent
• locally scoped
• composable

Runtime State

spinner.isRunning;
spinner.isPaused;
spinner.elapsedMs;

Multiple Instances

const spinnerA = new Spinner();
const spinnerB = new Spinner();

spinnerA.start("Task A");
spinnerB.start("Task B");

nspin-render supports bounded local cursor coordination between concurrent spinner instances.

Non-TTY Behavior

In non-TTY environments:

• persistent rendering degrades to append-only output
• cursor movement is intentionally avoided

This improves compatibility with:

• CI pipelines
• redirected stdout
• logging pipelines

SpinnerOptions

interface SpinnerOptions {
  frames?: string[];
  interval?: number;
  format?: FormatOptions;
  position?: "left" | "right";
}

Documentation

• GitHub Repository
• API Reference
• Architecture
• Troubleshooting
• Contributing Guide

Documentation & Support

For detailed documentation, comprehensive usage examples, and API references, please visit the GitHub repository.

If you have any issues or suggestions, please open an issue on GitHub.

This README for npm is a simplified version. For the complete documentation, including all examples and in-depth API details, please refer to the full README on GitHub.