f-readline

f-readline

For a long time, Node had no "easy" way to read a stream line by line. Until v11.4, when readline added support for async iteration.

This module is a thin layer over readline to provide functional programming constructs: filter(), forEach(), map(), reduce(). It also provides a convenient getAllLines().

Basic API

Note: Other than the constructor, all methods are async.

constructor(readable, interfaceOptions) constructor

• readable is the stream to be read
• interfaceOptions (optional, default = {}) will be passed to readline.createInterface(interfaceOptions)
  • crlfDelay defaults to 999999
  • input is set to the readable argument

async getAllLines()

Convenience method to just provide an array of all the lines. Obviously it must all fit in memory!

Functional API

The "functional" methods below accept a user function (or "predicate") fn as their first argument. This method is usually called with three arguments:

• the line
• the line count (starting at 0)
• the instance of f-readline. Generally useless but see notes at end

async filter(fn)

Returns an array of all lines passing the predicate fn(line, index, this)

async forEach(fn)

Calls fn(line, index, this) for each line.

async map(fn)

Returns an array obtained by calling fn(line, index, this) for each line

async reduce(fn, acc)

Reduces using fn(acc, line, index, this)

Notes, Todos, and Caveats

Since readline is clever on memory (?), this may save on memory

• if you are just counting lines or characters
• if you are filtering just a small subset of the input

What good is the 3rd argument to fn()?

• The interfaceOptions are available in .interfaceOptions
• The created interface is available in .rl
• If you want to pass other client specific info to fn, just add it to the FReadLine instance, e.g.

let frl = new FReadLine(readable, interfaceOptions);
frl.clientData = { your data here };

// then, during the call to fn(), you could access those

fn(line, index, frl) {
  do something with frl.clientData
}

This module has nothing to do with prompting the user, pausing the input, etc. Just reading a stream line by line.

Alternatives

All of these do their own twiddly buffering and eol parsing, instead of relying on a "robust" built-in library.

file-readline

• non-functional
• only reads a file, not any stream

n-readlines

• non-functional
• synchronous

readlines-ng

• non-functional
• looks pretty good otherwise and claims to be fast.