BuuReadline

🚀 Features

• 🎨 Optional Color Support - Integrates with @buucolors/buucolors
• 📋 Interactive Menus - Numbered selection options
• ❓ Simple Questions - Promise-based input prompts
• ✅ Yes/No Queries - German and English input support
• 🎯 Fallback System - Works without color package
• ⚡ Lightweight - Minimal dependencies
• 🔗 Simple API - Intuitive methods
• 🌈 Automatic Color Detection - Loads BuuColors automatically
• 🚫 Zero Dependencies - Works standalone without any requirements

📦 Installation

# Basic installation (works standalone)
npm install @buureadline/buu-readline

# With color support (recommended)
npm install @buureadline/buu-readline @buucolors/buucolors

# Using yarn
yarn add @buureadline/buu-readline @buucolors/buucolors

# Using pnpm
pnpm add @buureadline/buu-readline @buucolors/buucolors

Note: BuuReadline works perfectly without any dependencies. Colors are automatically enabled if @buucolors/buucolors is installed, otherwise it falls back to plain text.

💡 Quick Start

const { createBuuRl } = require('@buureadline/buu-readline');

// Create readline interface (with automatic color detection)
const rl = createBuuRl();

async function quickDemo() {
  // Simple question
  const name = await rl.question('What is your name? ');
  console.log(`Hello ${name}! 👋`);

  // Interactive menu
  const choice = await rl.menu('What would you like to do?', [
    '📂 Open file',
    '💾 Save file', 
    '🚪 Exit'
  ]);
  console.log(`You chose: ${choice}`);

  // Yes/No question
  const confirm = await rl.choose('Do you want to continue? (y/n): ');
  console.log(confirm ? '✅ Let\'s go!' : '❌ Cancelled.');

  rl.close();
}

quickDemo();

🎨 With BuuColors (Recommended)

const { createBuuRl } = require('@buureadline/buu-readline');

const rl = createBuuRl(); // Loads BuuColors automatically if available

async function colorfulExample() {
  // Colorful input prompts
  const project = await rl.question('🚀 Project name: ');
  
  // Colorful menu with options
  const framework = await rl.menu('🛠️ Choose framework:', [
    'React.js',
    'Vue.js', 
    'Angular',
    'Vanilla JS'
  ]);
  
  // Confirmation with colors
  const useTS = await rl.choose('📝 Use TypeScript? ');
  
  console.log(`
🎉 Project Setup:
📦 Name: ${project}
⚡ Framework: ${framework} 
📘 TypeScript: ${useTS ? 'Yes' : 'No'}
  `);
  
  rl.close();
}

colorfulExample();

🔧 Without BuuColors (Plaintext)

The package works automatically without colors when @buucolors/buucolors is not installed:

const { createBuuRl } = require('@buureadline/buu-readline');

// Works without BuuColors - uses plaintext
const rl = createBuuRl();

async function plaintextExample() {
  const name = await rl.question('Enter name: ');
  
  const choice = await rl.menu('Select option:', [
    'Option A',
    'Option B', 
    'Option C'
  ]);
  
  const confirm = await rl.choose('Confirm? (y/n): ');
  
  console.log(`Name: ${name}, Choice: ${choice}, Confirmed: ${confirm}`);
  rl.close();
}

plaintextExample();

Perfect for environments where:

• You don't want color dependencies
• Running in CI/CD pipelines
• Building lightweight CLI tools
• Colors are not supported

🎨 Custom Colors

You can define your own color functions:

const { createBuuRl } = require('@buureadline/buu-readline');

// Custom color definitions
const customColors = {
  gradientCmd_yellow2orange: Object.assign(
    (text) => `\x1b[38;5;214m${text}\x1b[0m`, 
    { bold: (text) => `\x1b[1;38;5;214m${text}\x1b[0m` }
  ),
  cmdMagenta: Object.assign(
    (text) => `\x1b[35m${text}\x1b[0m`,
    { bold: (text) => `\x1b[1;35m${text}\x1b[0m` }
  ),
  cmdBrightMagenta: (text) => `\x1b[95m${text}\x1b[0m`,
  cmdRed: (text) => `\x1b[31m${text}\x1b[0m`
};

const rl = createBuuRl(customColors);

async function customColorExample() {
  const answer = await rl.question('With custom colors: ');
  console.log(`Input: ${answer}`);
  rl.close();
}

customColorExample();

Use cases for custom colors:

• Brand-specific color schemes
• Terminal-specific optimizations
• Custom styling requirements
• Integration with other color libraries

📋 API Reference

createBuuRl(buuColor?): BuuReadlineInterface

Creates a new readline instance with automatic color detection.

const { createBuuRl } = require('@buureadline/buu-readline');

// Automatic color detection
const rl = createBuuRl();

// With custom colors
const rl2 = createBuuRl(customColors);

BuuReadlineInterface Methods

question(query): Promise<string>

Asks a simple question and waits for input.

const name = await rl.question('What is your name? ');
const email = await rl.question('📧 Email address: ');

menu(query, options): Promise<string>

Shows a numbered menu and returns the selected option.

const choice = await rl.menu('Choose framework:', [
  'React.js',
  'Vue.js',
  'Angular'
]);
// Returns the selected option (e.g. "React.js")

choose(query): Promise<boolean>

Asks a yes/no question with multilingual support.

const confirm = await rl.choose('Continue? (y/n): ');
// true for: j, ja, y, yes
// false for: n, nein, no

close(): void

Closes the interface and frees resources.

rl.close(); // Always call at the end

⚡ Advanced Features

• ✅ JavaScript Compatible - Fully compatible
• ✅ CommonJS Module - Standard require() syntax
• ✅ Automatic Color Detection - Loads BuuColors if available
• ✅ Fallback System - Plaintext without color package
• ✅ Multilingual Input - German and English for yes/no
• ✅ Promise-based - Modern async/await syntax
• ✅ Robust Validation - Safe input handling
• ✅ Lightweight - Minimal overhead
• ✅ Zero Dependencies - Works completely standalone

🔥 Real-World Examples

CLI Tool Setup Wizard

const { createBuuRl } = require('@buureadline/buu-readline');

async function setupWizard() {
  const rl = createBuuRl();
  
  console.log('🎉 Setup wizard started!\n');
  
  // Collect project information
  const projectName = await rl.question('📦 Project name: ');
  const description = await rl.question('📝 Description: ');
  
  // Select technology stack
  const frontend = await rl.menu('🎨 Frontend framework:', [
    'React.js',
    'Vue.js', 
    'Angular',
    'Svelte',
    'Vanilla JS'
  ]);
  
  const backend = await rl.menu('⚙️ Backend framework:', [
    'Express.js',
    'Fastify',
    'Koa.js',
    'NestJS',
    'Frontend only'
  ]);
  
  // Additional features
  const useTS = await rl.choose('📘 Use TypeScript? ');
  const useESLint = await rl.choose('🔍 Setup ESLint? ');
  const usePrettier = await rl.choose('💄 Setup Prettier? ');
  
  // Summary
  console.log('\n✨ Project Configuration:');
  console.log(`├─ 📦 Name: ${projectName}`);
  console.log(`├─ 📝 Description: ${description}`);
  console.log(`├─ 🎨 Frontend: ${frontend}`);
  console.log(`├─ ⚙️ Backend: ${backend}`);
  console.log(`├─ 📘 TypeScript: ${useTS ? 'Yes' : 'No'}`);
  console.log(`├─ 🔍 ESLint: ${useESLint ? 'Yes' : 'No'}`);
  console.log(`└─ 💄 Prettier: ${usePrettier ? 'Yes' : 'No'}`);
  
  const confirm = await rl.choose('\n🚀 Create project? ');
  console.log(confirm ? '✅ Creating project...' : '❌ Setup cancelled.');
  
  rl.close();
}

setupWizard();

Interactive CLI Menu System

const { createBuuRl } = require('@buureadline/buu-readline');

async function mainMenu() {
  const rl = createBuuRl();
  
  while (true) {
    console.clear();
    console.log('🌟 Main Menu 🌟\n');
    
    const action = await rl.menu('What would you like to do?', [
      '📊 Show data',
      '✏️ Edit data', 
      '🗑️ Delete data',
      '⚙️ Settings',
      '🚪 Exit'
    ]);
    
    switch (action) {
      case '📊 Show data':
        await showData(rl);
        break;
      case '✏️ Edit data':
        await editData(rl);
        break;
      case '🗑️ Delete data':
        await deleteData(rl);
        break;
      case '⚙️ Settings':
        await settings(rl);
        break;
      case '🚪 Exit':
        const confirm = await rl.choose('Really exit? ');
        if (confirm) {
          console.log('👋 Goodbye!');
          rl.close();
          return;
        }
        break;
    }
    
    await rl.question('\n⏸️ Press Enter to continue...');
  }
}

async function showData(rl) {
  console.log('\n📊 Displaying data...');
  // Data logic here
}

async function editData(rl) {
  const field = await rl.menu('Which field to edit?', [
    'Name',
    'Email',
    'Phone'
  ]);
  const newValue = await rl.question(`New value for ${field}: `);
  console.log(`✅ ${field} updated to "${newValue}".`);
}

async function deleteData(rl) {
  const confirm = await rl.choose('⚠️ Really delete data? ');
  console.log(confirm ? '🗑️ Data deleted.' : '❌ Operation cancelled.');
}

async function settings(rl) {
  const setting = await rl.menu('Choose setting:', [
    'Change language',
    'Change theme',
    'Back'
  ]);
  console.log(`⚙️ ${setting} selected.`);
}

mainMenu();

Standalone Usage (No Dependencies)

const { createBuuRl } = require('@buureadline/buu-readline');

// Works perfectly without any other packages installed
async function standaloneExample() {
  const rl = createBuuRl(); // No colors, pure functionality
  
  console.log('This works without any dependencies!\n');
  
  const name = await rl.question('Enter your name: ');
  const age = await rl.question('Enter your age: ');
  
  const language = await rl.menu('Choose your preferred language:', [
    'JavaScript',
    'TypeScript',
    'Python',
    'Go',
    'Rust'
  ]);
  
  const isExperienced = await rl.choose('Are you an experienced developer? (y/n): ');
  
  console.log('\n--- Profile Summary ---');
  console.log(`Name: ${name}`);
  console.log(`Age: ${age}`);
  console.log(`Preferred Language: ${language}`);
  console.log(`Experience Level: ${isExperienced ? 'Experienced' : 'Beginner'}`);
  
  rl.close();
}

standaloneExample();

📋 Package Contents

• 📃 buuReadlineApi.js - Main API file
• 📖 README.md - This beautiful documentation
• 📜 package.json - Package configuration

🤝 Contributing

We welcome contributions! You can:

• 🐛 Report bugs
• 💡 Suggest new features
• 🔧 Submit improvements
• 🌟 Rate and share the package

🎯 Use Cases

Perfect for:

• 🛠️ CLI tool creation
• � Interactive setup wizards
• 🎮 Terminal-based games
• 📊 Data collection scripts
• ⚙️ Configuration managers
• 🔧 Development tools
• 📝 Survey applications
• 🎨 Interactive demonstrations

📄 License

MIT License - Free and Open Source

This project is licensed under the MIT License, which means you are free to:

• ✅ Use - Use this library in personal and commercial projects
• ✅ Modify - Change and customize the code to fit your needs
• ✅ Distribute - Share and redistribute the library
• ✅ Private Use - Use in private projects without restrictions
• ✅ Commercial Use - Use in commercial applications and products

The only requirement is to include the original copyright notice and license terms.

🌐 Connect with Us