The de facto standard input/output manager for Node.js

After a very long time, finally version 2 is here. The cool stdio module you cannot live without has been rewritten and improved a lot, with Typescript support, promise-based usage and much more.

Note: Version 2 stops supporting non promise-based usage. Some functions have been renamed, too. So it is not compatible with older versions. If you're using an older version of stdio please, read this documentation carefully before upgrading.

Table of contents:

• Installation
• Usage
  • getopt()
  • read()
  • readLine()
  • ask()
  • ProgressBar

Installation

To install this module you can use npm:

$ npm install stdio

Then you can import it from your project, as a whole module or any of its parts independently:

import stdio from 'stdio';

import { getopt, read } from 'stdio';

Usage

This module contains the following static functions:

• getopt(): a function to parse command-line arguments.
• read(): an async function to read the standard input (or huge files) by lines, without having to worry about system resources.
• readLine(): an async function to read a single line from the standard input.
• ask(): an async function to ask questions in a terminal and wait for a user's response.

And the following classes:

• ProgressBar: a class to create command-line progress bars.

Next sections will show how to use all of them.

getopt()

This function gives parsed UNIX-like command-line and options, preprocessed and ready to be used in an easy way. It is inspired by C standard library under UNIX.

import { getopt } from 'stdio';
const options = getopt({
  <option_name_1>: {<definition>},
  <option_name_2>: {<definition>},
  <option_name_3>: {<definition>},
  ...
});

Where <definition> is an object describing each option. These are the supported fields to define an option:

• key (string): The short name for the option. It is a single-letter string.
• description (string): The option description. A text for humans to understand what the option means.
• required (boolean): If the option is mandatory or not.
• args (number|string): The expected arguments count for the option (if the option expects arguments). This can be a number or the special string "*" when it is variable.
• multiple (boolean): If the option should be specified for each value. This makes it mandatory to write things like -m 1 -m 2 -m 3 instead of -m 1 2 3.
• default: (string[] or string): The default value for an option, in case it is not provided in the command.

Positional arguments (those not precedeed by an option) can be customized, too, using the special option _meta_, which supports some limits in the amount of required args:

import { getopt } from 'stdio';
const options = getopt({
  <option_name_1>: {<definition>},
  <option_name_2>: {<definition>},
  <option_name_3>: {<definition>},
  ...
  _meta_: { minArgs: <number>, maxArgs: <number>, args: <number> },
});

In case a required option is not defined or any option is not well used at runtime, an automatic help/usage message is printed, aborting the execution. This message is also shown automatically in case one of the special options -h, --help is provided.

USAGE: node example.js [OPTION1] [OPTION2]... arg1 arg2...
The following options are supported:
  -<key_1>, --<option_name_1>
  -<key_2>, --<option_name_2>
  ...

const options = getopt({...}, {<behavior_customizations>});

The response of a getopt() call is a simple plain object with a value per option specified in the command. Each value can be one of the following:

• boolean, for options not needing arguments.
• string, for options expecting a single argument.
• string[], for options expecting more than one argument.

See the following example for a better understanding of how to use getopt() and the expected resoponse:

import { getopt } from 'stdio';

const options = getopt({
  name: { key: 'n', description: 'A name for the project', args: 1, required: true },
  keywords: { key: 'k', description: 'Some keywords to describe something', args: '*', multiple: true },
  languages: { args: '*' },
  finished: { description: 'If the project is finished' },
});

console.log('Stdio rocks!\n', options);

$ node example.js -n 'hello world' -k leisure -k health -k sport --languages javascript typescript c++ --finished

Stdio rocks!
 {
  name: 'hello world',
  keywords: [ 'leisure', 'health', 'sport' ],
  languages: [ 'javascript', 'typescript', 'c++' ],
  finished: true
}

$ node example.js -k leisure -k health -k sport --languages javascript typescript c++ --finished

Missing option: "--name"
USAGE: node example.js [OPTION1] [OPTION2]... arg1 arg2...
The following options are supported:
  -n, --name <ARG1>          	A name for the project (required)
  -k, --keywords <ARG1>      	Some keywords to describe something (multiple)
  --languages <ARG1>...<ARGN>
  --finished                 	If the project is finished

read()

This function reads the whole standard input by lines, waiting for a line to be processed successfully before reading the next one. This is perfect for huge files as lines are read only as you process them, so you don't have to worry about system resources.

import { read } from 'stdio';

async function onLine (line, index) {
  console.log('Processing line %d: %s', index, line);
  // Do your async stuff
}

read(onLine)
  .then(stats => console.log('Finished', stats))
  .catch(error => console.warn('Error', error));

Note that onLine is an async function, what means it returns a promise. read() call itself also returns a promise. In case one line fails being processed (its promise is rejected) the full read() promise will be rejected, too.

Once a read() successful call finishes (when all lines have been processed successfully), a small object with some stats is returned:

{
  length: number; // Number of lines
  times: Array<number>; // Duration of each line processor
  timesAverage: number; // Average duration of line processing
}

$ cat hugefile.txt | node myprogram.js

import { read } from 'stdio';

function sleep (delay) {
  return new Promise((resolve) => {
    setTimeout(resolve, delay);
  });
}

async function onLine (line, index) {
  console.log(`#${index}: ${line}`);
  await sleep(1000);
}

read(onLine)
  .then((stats) => console.log('Finished', stats))
  .catch((error) => console.warn('Error', error));

#1: This is the first line of hugefile.txt
#2: Here the second one
#3: A third line...

readLine()

This function reads a single line from standard input. This is perfect for interactive terminal-based programs or just to read standard input on demand.

import { readLine } from 'stdio';

(async () => {
  ...
  const line = await readLine(<options>);
  ...
})()

Where <options> is an optional object with the following properties:

• stream (Readable): An object implementing NodeJS.Readable interface, like a stream. By default, process.stdin is used.
• close (boolean): An optional flag to close the reader after returning the line. This is useful if you want to stop listening before finishing your program execution.

import { readLine } from 'stdio';

(async () => {
  let command;
  do {
    command = await readLine();
    if (command === 'SAY_A') {
      console.log('A');
    } else if (command === 'SAY_B') {
      console.log('B');
    } else if (command === 'EXIT') {
      console.log('Good bye');
      await readLine({ close: true });
    }
  } while (command !== 'EXIT')
})()

ask()

This simple function let you ask questions to the user through the command line and wait for an answer:

import { ask } from 'stdio';
...
const answer = await ask(QUESTION_STRING, QUESTION_CONFIG);
...

Where QUESTION_STRING is just a string and QUESTION_CONFIG is an optional object including the following properties:

• options (string[]): List of allowed values for the answer. If it is not provided, then any answer is accepted.
• maxRetries (number): Only makes sense when options is provided. After maxRetries of wrong answers, the ask() returning promise is rejected with an error explaining that all retries have been spent with no successfull answer.

import { ask } from 'stdio';

async function main () {
	const name = await ask('What is your name?');
	const age = await ask('How old are you?');
	const gender = await ask('What is your gender?', { options: ['male', 'female'] });
	console.log('Your name is "%s". You are a "%s" "%s" years old.', name, gender, age);
}

main()
  .then(() => console.log('Finished'))
  .catch(error => console.warn(error));

$ node example.js

What is your name?: John Doe
How old are you?: 34
What is your gender? [male/female]: other
Unexpected answer. 2 retries left.
What is your gender? [male/female]: male
Your name is "john doe". You are a "male" "34" years old.
Finished

ProgressBar

This utility let you create progress bar instances that are printed automatically in the terminal, using a beautiful format and estimating the remaining time of a task. Using it is as simple as follows:

import { ProgressBar } from 'stdio';

const bar = new ProgressBar(BAR_SIZE);
...
bar.tick();
bar.onFinish(() => console.log('FINISHED'));

Note that progress bars take the 100% of the terminal width where your code runs. No matter if you use a size of 10 or 10000 ticks. stdio takes care about the formatting so you don't have to worry about it. Your terminal will show something like the following:

00:01:12 23% [##############······················································] ETA 08:10:48

import { ProgressBar } from 'stdio';

var pbar = new ProgressBar(345);
var i = setInterval(() => pbar.tick(), 1000);
pbar.onFinish(() => {
	console.log('Finished!');
	clearInterval(i);
});

00:00:12 3% [###··································································] ETA 00:05:35