feat: add configurable output stream (#13)

Author: nightnei

README.md

@@ -63,6 +63,19 @@ setTimeout(() => {
 
 Calling `spinner.stop();` will stop the spinner and remove it.
 
+### Output stream
+
+Spinners write to `process.stdout` by default. To keep stdout available for machine-readable output, pass another stream such as `process.stderr`:
+
+```js
+import {Spinner} from 'picospinner';
+
+const spinner = new Spinner({
+  text: 'Loading...',
+  stream: process.stderr
+});
+```
+
 ### Colours
 
 As of version **3.0.0** colours are enabled by default. This feature uses the [`styleText`](https://nodejs.org/api/util.html#utilstyletextformat-text-options) function from [`node:util`](https://nodejs.org/api/util.html) if it is available (Node versions greater than **22.0.0**, **21.7.0** or **20.12.0**). If it's not available, no colours will be displayed.

src/index.ts

@@ -1,14 +1,17 @@
 import * as constants from './constants.js';
-import {Renderer, TextComponent} from './renderer.js';
+import {Renderer, TextComponent, type OutputStream} from './renderer.js';
 import * as util from 'node:util';
 
+export type {OutputStream} from './renderer.js';
+
 export type Formatter = (input: string) => string;
 
 export type DisplayOptions = {
   symbolFormatter?: Formatter;
   text?: string;
   symbol?: string;
   symbolType?: 'succeed' | 'fail' | 'warn' | 'info' | 'spinner';
+  stream?: OutputStream;
 };
 
 export type SpinnerOptions = {
@@ -39,6 +42,8 @@ export type Symbols = {
 // Global renderer so that multiple spinners can run at the same time
 export const renderer = new Renderer();
 
+const renderersByStream = new WeakMap<OutputStream, Renderer>([[process.stdout, renderer]]);
+
 export class Spinner {
   public running = false;
 
@@ -51,6 +56,8 @@ export class Spinner {
   private frames: string[];
   private component = new TextComponent('');
   private colors?: ColorOptions;
+  private stream: OutputStream = process.stdout;
+  private outputRenderer = renderer;
 
   constructor(display: DisplayOptions | string = '', {disableNewLineEnding, colors, frames = constants.DEFAULT_FRAMES, symbols = {} as Partial<Symbols>}: SpinnerOptions = {}) {
     // Merge symbols with defaults
@@ -85,7 +92,7 @@ export class Spinner {
     this.currentSymbol = this.frames[0];
 
     this.tick();
-    renderer.addComponent(this.component);
+    this.outputRenderer.addComponent(this.component);
     this.addListeners();
   }
 
@@ -130,6 +137,7 @@ export class Spinner {
   }
 
   setDisplay(displayOpts: DisplayOptions = {}, render = true) {
+    if (displayOpts.stream) this.setStream(displayOpts.stream);
     if (typeof displayOpts.symbol === 'string') {
       if (typeof displayOpts.symbolType === 'string') {
         this.currentSymbol = this.format(displayOpts.symbol, displayOpts.symbolType);
@@ -142,6 +150,23 @@ export class Spinner {
     if (typeof displayOpts.symbol === 'string') this.end();
   }
 
+  private setStream(stream: OutputStream) {
+    if (stream === this.stream) return;
+
+    const wasRunning = this.running;
+    if (wasRunning) this.outputRenderer.removeComponent(this.component);
+
+    this.stream = stream;
+    let outputRenderer = renderersByStream.get(stream);
+    if (!outputRenderer) {
+      outputRenderer = new Renderer(true, stream);
+      renderersByStream.set(stream, outputRenderer);
+    }
+    this.outputRenderer = outputRenderer;
+
+    if (wasRunning) this.outputRenderer.addComponent(this.component);
+  }
+
   setText(text: string, render = true) {
     this.text = this.format(text, 'text');
     if (this.running) {
@@ -177,7 +202,7 @@ export class Spinner {
     clearInterval(this.interval);
     this.clearListeners();
     if (keepComponent) this.component.finish();
-    else renderer.removeComponent(this.component);
+    else this.outputRenderer.removeComponent(this.component);
     this.running = false;
   }
 

src/renderer.ts

@@ -1,5 +1,10 @@
 import * as constants from './constants.js';
 import {countLines} from './string-lines.js';
+import type {Writable} from 'node:stream';
+
+export interface OutputStream extends Writable {
+  getWindowSize?: () => [number, number];
+}
 
 export class TextComponent {
   onChange?: () => void;
@@ -38,22 +43,25 @@ export class Renderer {
   private finishedComponents = 0;
   private outputBuffer = '';
 
-  constructor(public hideCursor: boolean = true) {}
+  constructor(
+    public hideCursor: boolean = true,
+    private stream: OutputStream = process.stdout
+  ) {}
 
   addComponent(component: TextComponent) {
     this.components.push(component);
     component.onChange = this.render.bind(this);
     component.onFinish = this.onComponentFinish.bind(this);
 
-    if (process.stdout.getWindowSize) this.terminalWidth = process.stdout.getWindowSize()[0];
+    if (this.stream.getWindowSize) this.terminalWidth = this.stream.getWindowSize()[0];
     this.render();
   }
 
   private onComponentFinish() {
     this.finishedComponents++;
     if (this.finishedComponents === this.components.length) {
       this._reset();
-      process.stdout.write(constants.SHOW_CURSOR);
+      this.stream.write(constants.SHOW_CURSOR);
     }
   }
 
@@ -69,8 +77,8 @@ export class Renderer {
     this.clear();
 
     if (this.components.length === 0) {
-      process.stdout.write(this.outputBuffer);
-      if (this.hideCursor) process.stdout.write(constants.SHOW_CURSOR);
+      this.stream.write(this.outputBuffer);
+      if (this.hideCursor) this.stream.write(constants.SHOW_CURSOR);
       this.lastLinesAmt = 0;
       return;
     }
@@ -93,7 +101,7 @@ export class Renderer {
       this.outputBuffer += constants.SHOW_CURSOR;
     }
 
-    process.stdout.write(this.outputBuffer);
+    this.stream.write(this.outputBuffer);
   }
 
   clear() {

src/test/spinner-test.ts

@@ -1,7 +1,7 @@
 import * as assert from 'node:assert/strict';
 import {test} from 'node:test';
 import {ColorOptions, Spinner, Symbols, renderer} from '../index.js';
-import {createFinishingRenderedLine, createRenderedLine, createRenderedOutput, interceptStdout, suppressStdout, TickMeasuredSpinner} from './utils.js';
+import {createFinishingRenderedLine, createRenderedLine, createRenderedOutput, interceptStderr, interceptStdout, suppressStdout, TickMeasuredSpinner} from './utils.js';
 import process from 'node:process';
 import * as constants from '../constants.js';
 
@@ -254,4 +254,19 @@ test('spinner', async (t) => {
   );
   await t.test('displays colors with symbol formatter', () => testSpinner(undefined, 'lorem ipsum dolor', (s) => `a${s}a`, true));
   await t.test('disableNewLineEnding prevents ending new line', () => testSpinner(undefined, undefined, undefined, undefined, true));
+  await t.test('writes to configured stream', async () => {
+    renderer._reset();
+
+    let stdout = '';
+    const stderr = await interceptStderr(async () => {
+      stdout = await interceptStdout(async () => {
+        const spinner = new Spinner({stream: process.stderr}, {colors: false});
+        spinner.start();
+        spinner.stop();
+      });
+    });
+
+    assert.equal(stdout, '');
+    assert.equal(stderr, createRenderedLine(constants.DEFAULT_FRAMES[0], '', true) + constants.CLEAR_LINE + constants.UP_LINE + constants.CLEAR_LINE + constants.SHOW_CURSOR);
+  });
 });

src/test/utils.ts

@@ -42,25 +42,33 @@ export function suppressStdout() {
   return () => (process.stdout.write = stdoutWrite);
 }
 
-export async function interceptStdout(exec: () => Promise<void> | void) {
+async function interceptOutput(stream: NodeJS.WriteStream, exec: () => Promise<void> | void) {
   let output = '';
-  const stdoutWrite = process.stdout.write.bind(process.stdout);
+  const streamWrite = stream.write.bind(stream);
 
   // @ts-expect-error - types are wrong here for the callback
-  capcon.startIntercept(process.stdout, (data: string) => {
-    // Since stdout is used to communicate test data, the interceptor should write data that is not from picospinner to stdout
+  capcon.startIntercept(stream, (data: string) => {
+    // Since output streams are used to communicate test data, the interceptor should write data that is not from picospinner back to the stream
     if (isMainCallstack()) {
       output += data;
-    } else stdoutWrite(data);
+    } else streamWrite(data);
   });
 
   await exec();
 
-  capcon.stopIntercept(process.stdout);
+  capcon.stopIntercept(stream);
 
   return output;
 }
 
+export function interceptStdout(exec: () => Promise<void> | void) {
+  return interceptOutput(process.stdout, exec);
+}
+
+export function interceptStderr(exec: () => Promise<void> | void) {
+  return interceptOutput(process.stderr, exec);
+}
+
 function getCallstack() {
   try {
     throw new Error();