@terminal/terminal-formatting

Terminal formatting and display utilities for Node.js applications. Provides comprehensive text styling, formatting, logging, and display components for CLI applications.

Installation

npm install @terminal/terminal-formatting

Features

🎨 Color & Styling

Complete terminal color support including:

• Basic colors (red, green, blue, yellow, magenta, cyan, white, gray)
• Background colors
• Text modifiers (bold, dim, italic, underline, strikethrough)
• RGB and Hex color support
• Semantic colors (success, error, warning, info, muted, highlight)

📐 Text Formatting

Advanced text manipulation utilities:

• box() - Wrap text in customizable boxes with various border styles
• center() - Center text within a specified width
• pad() - Pad text to a specific length
• truncate() - Truncate text with custom suffixes

📝 Logging

Structured logging with semantic levels:

• Default logger with success, error, warning, info, and debug levels
• createLogger() - Create loggers with custom prefixes
• Automatic icons and color coding for each level

⏳ Spinners

Loading indicators with multiple styles:

• Various spinner animations (dots, line, star, hamburger)
• State management (start, stop, succeed, fail, warn, info)
• Dynamic text updates during operation

📊 Tables

Flexible table rendering:

• Customizable column widths
• Header styling
• Border customization
• Compact borderless mode

Usage

Colors & Styling

const { chalk, red, green, bold, italic } = require('@terminal/terminal-formatting')

console.log(red('Error message'))
console.log(green('Success!'))
console.log(bold.blue('Important text'))
console.log(chalk.rgb(255, 136, 0)('Custom RGB color'))

Text Formatting

const { box, center, pad, truncate } = require('@terminal/terminal-formatting')

console.log(box('Hello World', {
  borderStyle: 'double',
  borderColor: 'cyan',
  padding: 1
}))

console.log(center('Centered Text', 50))
console.log(truncate('Very long text that needs truncation', 20))

Logging

const { logger, createLogger } = require('@terminal/terminal-formatting')

logger.success('Operation completed')
logger.error('Something went wrong')
logger.warning('Deprecation notice')
logger.info('FYI')

const apiLogger = createLogger('API')
apiLogger.info('Request received')

Spinners

const { createSpinner } = require('@terminal/terminal-formatting')

async function loadData() {
  const spinner = createSpinner('Loading data...')
  spinner.start()

  // Simulate async operation
  await someAsyncOperation()

  spinner.succeed('Data loaded successfully!')
}

Tables

const { createTable } = require('@terminal/terminal-formatting')

const table = createTable({
  head: ['Name', 'Age', 'City'],
  colWidths: [20, 10, 20]
})

table.push(['Alice', '28', 'New York'])
table.push(['Bob', '32', 'San Francisco'])

console.log(table.toString())

Architecture

This package follows SOLID principles:

• Single Responsibility: Each module handles one specific concern
• Open/Closed: Extensible through composition, not modification
• Dependency Inversion: Depends on abstractions (chalk, ora) not concrete implementations

API Reference

Colors

• red, green, blue, yellow, magenta, cyan, white, gray
• bold, dim, italic, underline, strikethrough
• success, error, warning, info, muted, highlight
• chalk - Full chalk instance for advanced usage

Formatting

• box(text, options?) - Wrap text in a box
• center(text, width) - Center text within width
• pad(text, length, char?) - Pad text to length
• truncate(text, maxLength, suffix?) - Truncate text

Logger

• logger - Default logger instance
• createLogger(prefix?) - Create logger with prefix

Spinner

• createSpinner(text?, options?) - Create spinner instance
• ora - Full ora instance for advanced usage

Table

• createTable(options?) - Create table instance
• Table - Table class for advanced usage

Examples

See the comprehensive showcase demo:

node showcase/demos/terminal-formatting-demo.js menu

License

MIT