index.js

'use strict';

// Import frame presets from external file
const FRAMES = require('./frames');

class Spinner {
  /**
   * Create a new Spinner instance
   * @param {Object} options - Configuration options
   * @param {string|string[]} [options.frames] - Animation frames (array or preset name)
   * @param {string} [options.prefix='Loading...'] - Prefix text
   * @param {string} [options.suffix=''] - Suffix text
   * @param {number} [options.interval=100] - Animation interval in ms
   * @param {boolean} [options.autoStart=false] - Auto start animation
   * @param {stream} [options.stream=process.stdout] - Output stream
   */
  constructor(options = {}) {
    this.frames = this._resolveFrames(options.frames || 'braille');
    this.prefix = options.prefix || 'Loading';
    this.suffix = options.suffix || '';
    this.interval = options.interval || 100;
    this.stream = options.stream || process.stdout;
    this.autoStart = options.autoStart || false;
    
    this._index = 0;
    this._intervalId = null;
    this._isRunning = false;
    this._lastLength = 0;
    
    if (this.autoStart) {
      this.start();
    }
  }
  
  /**
   * Resolve frames from preset name or use custom array
   * @private
   */
  _resolveFrames(frames) {
    if (Array.isArray(frames)) {
      return frames;
    }
    if (typeof frames === 'string' && FRAMES[frames]) {
      return FRAMES[frames];
    }
    // Default to braille if not found
    return FRAMES.braille;
  }
  
  /**
   * Get current frame
   */
  get frame() {
    return this.frames[this._index];
  }
  
  /**
   * Start the spinner animation
   */
  start() {
    if (this._isRunning) return this;
    
    this._isRunning = true;
    this._intervalId = setInterval(() => this._spin(), this.interval);
    
    return this;
  }
  
  /**
   * Stop the spinner animation
   */
  stop() {
    if (!this._isRunning) return this;
    
    clearInterval(this._intervalId);
    this._intervalId = null;
    this._isRunning = false;
    
    // Clear the spinner
    this._clear();
    
    return this;
  }
  
  /**
   * Pause the spinner (keeps last frame displayed)
   */
  pause() {
    if (!this._isRunning) return this;
    
    clearInterval(this._intervalId);
    this._intervalId = null;
    this._isRunning = false;
    
    return this;
  }
  
  /**
   * Resume the spinner
   */
  resume() {
    if (this._isRunning) return this;
    
    this._isRunning = true;
    this._intervalId = setInterval(() => this._spin(), this.interval);
    
    return this;
  }
  
  /**
   * Update prefix text
   * @param {string} prefix - New prefix
   */
  setPrefix(prefix) {
    this.prefix = prefix;
    return this;
  }
  
  /**
   * Update suffix text
   * @param {string} suffix - New suffix
   */
  setSuffix(suffix) {
    this.suffix = suffix;
    return this;
  }
  
  /**
   * Set progress percentage (0-100)
   * @param {number} percent - Progress percentage
   */
  setProgress(percent) {
    this.suffix = ` ${percent.toFixed(0)}%`;
    return this;
  }
  
  /**
   * Set custom message
   * @param {string} message - Message to display
   */
  setMessage(message) {
    this.prefix = message;
    return this;
  }
  
  /**
   * Update frames
   * @param {string|string[]} frames - New frames (array or preset name)
   */
  setFrames(frames) {
    this.frames = this._resolveFrames(frames);
    this._index = 0;
    return this;
  }
  
  /**
   * Print success message and stop
   * @param {string} [message='Done!'] - Success message
   */
  succeed(message = 'Done!') {
    this.stop();
    this.stream.write(`\r${' '.repeat(this._lastLength)}\r`);
    this.stream.write(`\x1b[32m✓\x1b[0m ${message}\n`);
    return this;
  }
  
  /**
   * Print error message and stop
   * @param {string} [message='Error!'] - Error message
   */
  fail(message = 'Error!') {
    this.stop();
    this.stream.write(`\r${' '.repeat(this._lastLength)}\r`);
    this.stream.write(`\x1b[31m✗\x1b[0m ${message}\n`);
    return this;
  }
  
  /**
   * Print warning message and stop
   * @param {string} [message='Warning!'] - Warning message
   */
  warn(message = 'Warning!') {
    this.stop();
    this.stream.write(`\r${' '.repeat(this._lastLength)}\r`);
    this.stream.write(`\x1b[33m⚠\x1b[0m ${message}\n`);
    return this;
  }
  
  /**
   * Print info message and stop
   * @param {string} [message='Info'] - Info message
   */
  info(message = 'Info') {
    this.stop();
    this.stream.write(`\r${' '.repeat(this._lastLength)}\r`);
    this.stream.write(`\x1b[36mℹ\x1b[0m ${message}\n`);
    return this;
  }
  
  /**
   * Clear previous spinner output
   * @private
   */
  _clear() {
    if (this._lastLength > 0) {
      this.stream.write(`\r${' '.repeat(this._lastLength)}\r`);
      this._lastLength = 0;
    }
  }
  
  /**
   * Render one frame
   * @private
   */
  _spin() {
    const frame = this.frames[this._index];
    const text = `${this.prefix} ${frame}${this.suffix}`;
    
    this._clear();
    this.stream.write(`\r${text}`);
    this._lastLength = text.length;
    
    this._index = (this._index + 1) % this.frames.length;
  }
  
  /**
   * Is spinner running
   */
  get isRunning() {
    return this._isRunning;
  }
  
  /**
   * Get available preset names
   */
  static get presets() {
    return Object.keys(FRAMES);
  }
  
  /**
   * Get preset frames
   */
  static preset(name) {
    return FRAMES[name] || FRAMES.braille;
  }
}

/**
 * Quick helper - create and start spinner in one call
 * @param {string|string[]} [frames] - Animation frames
 * @param {string} [prefix] - Prefix text
 * @param {number} [interval] - Animation interval
 */
Spinner.spin = function(frames, prefix = 'Loading', interval = 100) {
  return new Spinner({
    frames,
    prefix,
    interval,
    autoStart: true
  });
};

// Export for both CommonJS and ES modules
if (typeof module !== 'undefined' && module.exports) {
  module.exports = Spinner;
  module.exports.FRAMES = FRAMES;
  module.exports.default = Spinner;
}