flowprompt

A Node.js terminal interface library for building rich interactive CLI applications. It provides a persistent prompt with managed logging output above. It's like REPL interfaces but has the benefit of output and input being evaulated separately which means you can input while output is generated. It is inspired by debugger interfaces like gdb.

view /examples/demo-example.js

Table of Contents

• Key Features
• Installation
• Examples
  • TypeScript Example
  • Asynchronous Output Example
  • Debugger-like Interface Example
• Contributing

Key Features

1. Persistent Prompt - Always-visible input area with custom prompt symbol
2. Async-safe Logging - Write to output while waiting for user input without UI corruption
3. Multi-line Log Control - Continue writing to the same output line or create new lines
4. Piping Support - Supports piping into the output area
5. Advanced Input Handling - Supports most important keys and key combinations:
   • History navigation (↑/↓ keys)
   • Advanced Cursor movement (←/→/Home/End/Ctrl+←/Ctrl+→)
   • ANSI escape sequence support
   • Ctrl+C handling (with double-tap exit)
6. TypeScript Ready - Full type definitions included
7. Dual Module Support - Works with both CommonJS (require) and ESM (import)

Installation

npm install flowprompt

Examples

TypeScript Example

import { Console } from 'flowprompt';

const vm = new Console({
    input: process.stdin,
    output: process.stdout,
    prompt: '-> ',
    encoding: 'utf8',
});

vm.log('Welcome to the VM Console!', true);

vm.on('line', (line: string) => {
    vm.log(`You typed: ${line}`, true);
});

view /examples/typescript-example.ts

Or run it using the following command:

npx tsx examples/typescript-example.ts

Asynchronous Output Example

const { Console } = require('flowprompt');

const vm = new Console({
    input: process.stdin,
    output: process.stdout,
    prompt: 'my-app> ',
    encoding: 'utf8'
});

setInterval(() => {
    vm.log(String.fromCodePoint(Math.floor(Math.random() * (0x5a - 0x41) + 0x41)), false);
},Math.random() * 1000)

vm.on("line", (line) => {
    vm.log(`Received: ${line}`);
})

view /examples/async-example.cjs

Or run it using the following command:

node examples/async-example.cjs

Debugger-like Interface Example

import { Console } from 'flowprompt';

const debuggerConsole = new Console({
    input: process.stdin,
    output: process.stdout,
    prompt: '(debugger) '
});

debuggerConsole.on('line', (cmd) => {
    switch (cmd) {
        case 'b':
        case 'breakpoints':
            debuggerConsole.log('Active breakpoints:\n- main.js:12\n- utils.js:45');
            break;
        case 'c':
        case 'continue':
            debuggerConsole.log('Resuming execution...');
            break;
        case 'h':
        case 'help':
        default:
            debuggerConsole.log('Available commands:\n- breakpoints (b)\n- continue (c)\n- help (h)');
            break;
    }
});

const completions = ['breakpoints', 'continue', 'help'];

debuggerConsole.on('autocomplete', ({line, pos, callback}) => {
    const lineEnd = line.slice(line.lastIndexOf(' ', pos - 1), pos)
    const hits = completions.filter((c) => c.startsWith(lineEnd)).map((c) => c.slice(lineEnd.length));
    const ccompletions = hits.map((hit) => ({line: `${line.slice(0, pos)}${hit}${line.slice(pos)}`, pos: pos + hit.length}))
    debuggerConsole.log(ccompletions.toString())
    callback(ccompletions);
})

view /examples/debugger-example.mjs

Or run it using the following command:

node examples/debugger-example.mjs

Contributing

Contributions are welcome! Create a pull request or open an issue to discuss a feature request or bug report. Have a look at TODO.md for planned features and improvements if you want to help out.