Node.js Readline Module Guide

The readline module enables interactive command-line interfaces and line-by-line input processing.

Basic Usage#

const readline = require('readline');

// Create interface
const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});

// Ask a question
rl.question('What is your name? ', (answer) => {
  console.log(`Hello, ${answer}!`);
  rl.close();
});

// With promise wrapper
function askQuestion(query) {
  return new Promise((resolve) => {
    rl.question(query, resolve);
  });
}

// Using promises
async function main() {
  const name = await askQuestion('Name: ');
  const age = await askQuestion('Age: ');
  console.log(`${name} is ${age} years old`);
  rl.close();
}

main();

Promises API (Node 17+)#

const readline = require('readline/promises');

async function main() {
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });

  const name = await rl.question('What is your name? ');
  const age = await rl.question('How old are you? ');

  console.log(`${name} is ${age} years old`);

  rl.close();
}

main();

Event-Based Interface#

const readline = require('readline');

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: '> ',
});

// Display prompt
rl.prompt();

// Handle each line
rl.on('line', (line) => {
  const input = line.trim();

  switch (input) {
    case 'hello':
      console.log('Hello!');
      break;
    case 'exit':
      console.log('Goodbye!');
      rl.close();
      return;
    default:
      console.log(`You said: ${input}`);
  }

  rl.prompt();
});

// Handle close
rl.on('close', () => {
  console.log('Interface closed');
  process.exit(0);
});

// Handle SIGINT (Ctrl+C)
rl.on('SIGINT', () => {
  rl.question('Are you sure you want to exit? (y/n) ', (answer) => {
    if (answer.toLowerCase() === 'y') {
      rl.close();
    } else {
      rl.prompt();
    }
  });
});

Reading Files Line by Line#

const readline = require('readline');
const fs = require('fs');

async function processFile(filename) {
  const fileStream = fs.createReadStream(filename);

  const rl = readline.createInterface({
    input: fileStream,
    crlfDelay: Infinity, // Recognize all CR LF sequences
  });

  let lineNumber = 0;

  for await (const line of rl) {
    lineNumber++;
    console.log(`Line ${lineNumber}: ${line}`);
  }

  console.log(`Total lines: ${lineNumber}`);
}

processFile('data.txt');

// With error handling
async function processFileWithErrors(filename) {
  try {
    const fileStream = fs.createReadStream(filename);

    fileStream.on('error', (error) => {
      console.error('File error:', error.message);
    });

    const rl = readline.createInterface({
      input: fileStream,
      crlfDelay: Infinity,
    });

    for await (const line of rl) {
      // Process line
      processLine(line);
    }
  } catch (error) {
    console.error('Processing error:', error.message);
  }
}

const readline = require('readline');

class Menu {
  constructor(options) {
    this.options = options;
    this.rl = readline.createInterface({
      input: process.stdin,
      output: process.stdout,
    });
  }

  display() {
    console.log('\n=== Main Menu ===');
    this.options.forEach((option, index) => {
      console.log(`${index + 1}. ${option.label}`);
    });
    console.log('0. Exit\n');
  }

  async run() {
    while (true) {
      this.display();

      const choice = await this.askQuestion('Select option: ');
      const index = parseInt(choice, 10);

      if (index === 0) {
        console.log('Goodbye!');
        this.rl.close();
        break;
      }

      if (index > 0 && index <= this.options.length) {
        await this.options[index - 1].action();
      } else {
        console.log('Invalid option');
      }
    }
  }

  askQuestion(query) {
    return new Promise((resolve) => {
      this.rl.question(query, resolve);
    });
  }
}

// Usage
const menu = new Menu([
  {
    label: 'Say Hello',
    action: () => console.log('Hello, World!'),
  },
  {
    label: 'Show Date',
    action: () => console.log(new Date().toLocaleDateString()),
  },
  {
    label: 'Calculate',
    action: async () => {
      // Can do async operations
    },
  },
]);

menu.run();

Password Input#

const readline = require('readline');

function askPassword(prompt) {
  return new Promise((resolve) => {
    const rl = readline.createInterface({
      input: process.stdin,
      output: process.stdout,
    });

    // Mute output
    const stdin = process.stdin;
    stdin.on('data', (char) => {
      char = char.toString();
      switch (char) {
        case '\n':
        case '\r':
        case '\u0004':
          stdin.pause();
          break;
        default:
          process.stdout.write('*'); // Show asterisks
          break;
      }
    });

    rl.question(prompt, (answer) => {
      console.log(); // New line after password
      rl.close();
      resolve(answer);
    });
  });
}

// Simpler approach with readline directly
function askPasswordSimple(prompt) {
  return new Promise((resolve) => {
    const rl = readline.createInterface({
      input: process.stdin,
      output: new (require('stream').Writable)({
        write: (chunk, encoding, callback) => callback(),
      }),
      terminal: true,
    });

    process.stdout.write(prompt);

    rl.question('', (answer) => {
      console.log();
      rl.close();
      resolve(answer);
    });
  });
}

Auto-Complete#

const readline = require('readline');

const commands = ['help', 'hello', 'history', 'exit', 'clear', 'status'];

function completer(line) {
  const hits = commands.filter((c) => c.startsWith(line));
  return [hits.length ? hits : commands, line];
}

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  completer: completer,
});

rl.prompt();

rl.on('line', (line) => {
  const cmd = line.trim();

  switch (cmd) {
    case 'help':
      console.log('Available commands:', commands.join(', '));
      break;
    case 'exit':
      rl.close();
      return;
    case 'clear':
      console.clear();
      break;
    default:
      console.log(`Unknown command: ${cmd}`);
  }

  rl.prompt();
});

// Async completer
function asyncCompleter(line, callback) {
  // Could fetch from database, API, etc.
  setTimeout(() => {
    const hits = commands.filter((c) => c.startsWith(line));
    callback(null, [hits.length ? hits : commands, line]);
  }, 100);
}

Cursor Control#

const readline = require('readline');

// Move cursor
readline.cursorTo(process.stdout, 0, 0); // Move to position
readline.moveCursor(process.stdout, 2, 0); // Move relative

// Clear lines
readline.clearLine(process.stdout, 0); // Clear current line
readline.clearScreenDown(process.stdout); // Clear screen below

// Progress indicator
function showProgress(current, total) {
  readline.cursorTo(process.stdout, 0);
  const percent = Math.round((current / total) * 100);
  const bar = '█'.repeat(percent / 2) + '░'.repeat(50 - percent / 2);
  process.stdout.write(`Progress: [${bar}] ${percent}%`);
}

// Usage
let progress = 0;
const interval = setInterval(() => {
  progress += 5;
  showProgress(progress, 100);

  if (progress >= 100) {
    clearInterval(interval);
    console.log('\nDone!');
  }
}, 100);

History#

const readline = require('readline');

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  historySize: 100,
  removeHistoryDuplicates: true,
});

// History is available via arrow keys automatically

// Access history programmatically
rl.on('line', (line) => {
  console.log('History:', rl.history);
  rl.prompt();
});

// Save/load history
const fs = require('fs');

function saveHistory(rl, filename) {
  fs.writeFileSync(filename, rl.history.join('\n'));
}

function loadHistory(filename) {
  try {
    return fs.readFileSync(filename, 'utf8').split('\n').filter(Boolean);
  } catch {
    return [];
  }
}

// Initialize with saved history
const savedHistory = loadHistory('.history');
const rlWithHistory = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  history: savedHistory,
});

Best Practices#

Interface:
✓ Use promises API when available
✓ Handle close events properly
✓ Implement SIGINT handling
✓ Clean up resources

File Processing:
✓ Use async iterator for large files
✓ Set crlfDelay for cross-platform
✓ Handle stream errors
✓ Process in chunks if needed

CLI:
✓ Provide clear prompts
✓ Implement auto-complete
✓ Support command history
✓ Handle edge cases

Avoid:
✗ Forgetting to close interface
✗ Blocking event loop
✗ Ignoring input validation
✗ Memory issues with large files

The readline module enables interactive CLI applications and efficient line-by-line file processing. Use the promises API for cleaner async code, implement auto-complete for better UX, and leverage cursor control for progress indicators. Always handle cleanup and edge cases properly.