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
• bounded rendering behavior
• graceful degradation
• operational transparency

The renderer intentionally avoids:

• framework orchestration
• process ownership
• signal ownership
• runtime-global coordination
• terminal monopolization

Index

• nspin-render
  • Overview
  • Index
  • Installation
  • Philosophy
  • Basic Usage
  • Lifecycle
    • Pause and Resume
    • Destroy
  • Runtime State
  • Multiple Spinner Instances
  • Graceful Degradation
  • Non-TTY Behavior
  • Explicit Ownership
  • Runtime Philosophy
  • Documentation
  • Development
  • Design Direction
  • Runtime Compatibility
  • Why This Exists
  • Support
  • Feedback
  • Contributing
  • Code of Conduct
  • Changelog
  • License

Installation

bun add @imgildev/nspin-render

npm install @imgildev/nspin-render

Philosophy

nspin-render is designed around a simple principle:

stdout mutation should remain explicit, local, and mechanically understandable

The project prioritizes:

• composability
• bounded behavior
• explicit ownership
• graceful degradation
• predictable lifecycle semantics

Over:

• abstraction layering
• orchestration systems
• hidden coordination
• framework-style APIs

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

The renderer exposes explicit lifecycle operations:

start → pause/resume → stop → destroy

Lifecycle operations are:

• idempotent
• locally scoped
• composable
• best-effort under terminal instability

Pause and Resume

spinner.pause();

spinner.resume();

Paused instances:

• preserve ownership
• stop render scheduling
• resume deterministically

Destroy

spinner.destroy();

Destroyed instances:

• permanently relinquish ownership
• cannot restart
• degrade safely into no-ops

Runtime State

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

State access remains:

• readonly
• local
• mechanically transparent

Multiple Spinner Instances

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

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

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

The renderer intentionally avoids:

• terminal-global orchestration
• layout engines
• centralized runtime coordination

Graceful Degradation

Terminal environments are imperfect.

nspin-render intentionally tolerates:

• partial TTY support
• cursor failures
• stdout write failures
• external stdout interference
• interrupted cleanup

The renderer favors:

bounded degradation over strict terminal control

Failures remain:

• local
• composable
• operationally bounded

Non-TTY Behavior

Persistent rendering requires TTY cursor support.

In non-TTY environments:

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

This improves compatibility with:

• CI pipelines
• redirected stdout
• logging pipelines
• non-interactive runtimes

Example degraded output:

Loading...
Loading...
Loading...

Explicit Ownership

Each spinner instance owns only:

• its own lifecycle
• its own rendering state
• its own cleanup behavior

The renderer does NOT own:

• the process
• signal policy
• terminal-global behavior
• runtime orchestration

This keeps rendering behavior:

• composable
• embeddable
• operationally transparent

Runtime Philosophy

The renderer intentionally favors:

• simplicity
• lifecycle clarity
• bounded behavior
• composability
• operational resilience

Over:

• orchestration
• abstraction layering
• speculative extensibility
• framework-style coordination

Documentation

• API_REFERENCE.md

  • Complete API contracts and runtime semantics.

• ARCHITECTURE.md

  • Architectural philosophy, ownership model, and rendering coordination.

• TROUBLESHOOTING.md

  • Runtime caveats, degradation behavior, and terminal compatibility notes.

• CONTRIBUTING.md

  • Contribution workflow and project governance expectations.

• SECURITY.md

  • Security policy and supported runtime expectations.

Development

Install dependencies:

bun install

Run tests:

bun test

Run checks:

bun run check

Build the package:

bun run build

Design Direction

The project evolves through:

• operational refinement
• bounded hardening
• composability preservation
• lifecycle clarity
• resilience improvements

The architecture intentionally resists:

• framework drift
• authority expansion
• orchestration semantics
• speculative complexity

Long-term stability is preferred over continuous expansion.

Contributions should preserve the project's core invariants:

• explicit ownership
• composability
• bounded coordination
• graceful degradation
• mechanical transparency

The project intentionally prioritizes:

• simplicity
• operational clarity
• maintainability
• deterministic lifecycle behavior

Over:

• abstraction layering
• orchestration systems
• speculative extensibility
• feature accumulation

Before introducing changes, prefer asking:

does this materially improve operational clarity or runtime resilience without increasing architectural complexity?

Runtime Compatibility

nspin-render is designed for:

• modern Node.js runtimes
• Bun-compatible environments
• interactive TTY terminals

Behavior may vary across:

• terminal emulators
• CI environments
• shell implementations
• redirected stdout pipelines

Graceful degradation is intentional.

Why This Exists

Most spinner libraries optimize primarily for:

• visual effects
• feature accumulation
• abstraction convenience

nspin-render instead focuses on:

• deterministic stdout persistence
• explicit lifecycle semantics
• bounded rendering behavior
• composable terminal interaction

The goal is not to become a terminal framework.

The goal is to remain:

• small
• explicit
• resilient
• mechanically understandable

Support

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

Feedback

If you enjoy using nspin-render, please consider leaving a review on GitHub or sharing your feedback.

Contributing

Contributions are welcome! Please review our Contributing Guidelines and Development Guide for setup instructions and coding standards.

Code of Conduct

We strive to create a welcoming, inclusive, and respectful community. Please see our Code of Conduct before contributing.

Changelog

For a complete list of changes, see the CHANGELOG.md.

License

This package is licensed under the MIT License.