Yosay

Yosay creates ASCII art speech bubbles with the Yeoman mascot character for command-line interfaces. Like cowsay but less cow, it provides a JavaScript API and CLI tool for displaying messages in a distinctive, branded format that has become iconic in the JavaScript development ecosystem.

Package Information

• Package Name: yosay
• Package Type: npm
• Language: JavaScript (ES modules)
• Installation: npm install yosay
• Node.js Version: >=18

Core Imports

import yosay from "yosay";

For global CLI installation:

npm install --global yosay

Basic Usage

import yosay from "yosay";

// Simple message
console.log(yosay('Hello, world!'));

// With custom line length
console.log(yosay('Hello, world!', { maxLength: 10 }));

// With ANSI styling (using chalk)
import chalk from 'chalk';
console.log(yosay(chalk.red('Error: ') + 'Something went wrong!'));

CLI Usage

# Basic usage
$ yosay "Hello, world!"

# With custom line length
$ yosay "Hello, world!" --maxLength 10

# From stdin
$ echo "Hello, world!" | yosay

Capabilities

Speech Bubble Generation

Creates ASCII art speech bubbles with the Yeoman mascot character.

/**
 * Creates ASCII art speech bubbles with Yeoman mascot character
 * @param message - Text to display in speech bubble (optional, defaults to welcome message)
 * @param options - Configuration options (optional)
 * @returns String containing ASCII art with Yeoman character and formatted speech bubble
 */
function yosay(message?: string, options?: YosayOptions): string;

interface YosayOptions {
  /** Maximum line length for word wrapping */
  maxLength?: number;
}

Features:

• Automatic word wrapping with configurable line length
• ANSI styling support with proper escape sequence handling
• Fullwidth character support (e.g., Chinese, Japanese characters)
• Automatic vertical centering for long messages
• Speech bubble overflow handling for very long messages
• Default Yeoman mascot greeting when no message provided

Usage Examples:

import yosay from "yosay";
import chalk from "chalk";

// Default message
console.log(yosay());
// Displays: "Welcome to Yeoman, ladies and gentlemen!"

// Custom message
console.log(yosay('Sindre is a horse'));

// With line length customization
console.log(yosay('This is a long message that will wrap', { maxLength: 8 }));

// With ANSI styling
console.log(yosay(chalk.red('Error: ') + chalk.yellow('Build failed!')));

// Mixed styling across multiple lines
console.log(yosay(
  chalk.red('Hi') + ' there, sir! ' + 
  chalk.bgBlue.white('you are looking') + ' swell today!'
));

// Handling newlines
console.log(yosay('first line\nsecond line\n\nfourth line'));

// Fullwidth characters
console.log(yosay('项目可以更新了'));

Command Line Interface

Command-line interface for yosay functionality.

# Usage patterns
yosay <string>
yosay <string> --maxLength <number>
echo <string> | yosay

# Options
--maxLength    Set maximum line length for word wrapping

CLI Examples:

# Basic message
$ yosay 'Sindre is a horse'

# Custom line length
$ yosay 'Hello world' --maxLength 8

# From stdin
$ echo 'Hello from pipe' | yosay

# Help
$ yosay --help

Architecture

Yosay is built around several key components:

• Message Processing: Handles ANSI escape sequences and preserves styling during word wrapping
• ASCII Art Rendering: Uses Unicode box drawing characters for speech bubble frames
• Text Layout Engine: Manages word wrapping, padding, and vertical alignment
• ANSI Preservation: Complex algorithm to maintain color and styling across line breaks

Types

interface YosayOptions {
  /** 
   * Maximum line length for word wrapping
   * If provided but smaller than the longest word, automatically adjusts to fit
   */
  maxLength?: number;
}

Dependencies

• chalk: Terminal text styling (used internally for Yeoman character colors)
• ansi-regex: ANSI escape sequence detection
• ansi-styles: ANSI styling utilities
• cli-boxes: Unicode box drawing characters
• meow: CLI helper (CLI only)
• pad-component: Text padding utility
• string-width: String width calculation with Unicode support
• strip-ansi: Remove ANSI escape sequences
• wrap-ansi: Word wrapping with ANSI support

Error Handling

The function handles various edge cases gracefully:

• Null/undefined message: Uses default Yeoman welcome message
• Empty string: Creates empty speech bubble
• Very long words: Automatically adjusts maxLength to accommodate
• Mixed ANSI sequences: Preserves styling across line wraps
• Unicode characters: Proper width calculation for fullwidth characters