line-reader

What is line-reader?

The line-reader npm package is a simple utility for reading lines from a readable stream one at a time. It is particularly useful for processing large files line by line without loading the entire file into memory.

What are line-reader's main functionalities?

Reading lines synchronously

This feature allows you to read lines from a file synchronously. The `eachLine` method reads each line of the file and executes a callback function for each line. The callback receives the line content and a boolean indicating if it is the last line.

const lineReader = require('line-reader');

lineReader.eachLine('file.txt', function(line, last) {
  console.log(line);
  if (last) {
    console.log('End of file reached');
  }
});

Reading lines asynchronously

This feature allows you to read lines from a file asynchronously. The `open` method opens the file and provides a reader object. The reader object has methods like `hasNextLine` and `nextLine` to read lines asynchronously.

const lineReader = require('line-reader');

lineReader.open('file.txt', function(reader) {
  if (reader.hasNextLine()) {
    reader.nextLine(function(line) {
      console.log(line);
    });
  }
});

Reading lines with promises

This feature allows you to read lines using promises. By using Node.js's `util.promisify`, you can convert the callback-based `eachLine` method into a promise-based one, making it easier to work with async/await.

const lineReader = require('line-reader');
const { promisify } = require('util');

const eachLine = promisify(lineReader.eachLine);

async function readLines() {
  await eachLine('file.txt', function(line) {
    console.log(line);
  });
}

readLines();

Other packages similar to line-reader

readline

The `readline` module is a built-in Node.js module that provides an interface for reading data from a Readable stream (such as process.stdin) one line at a time. It is more versatile and is part of the Node.js standard library, making it a good alternative to line-reader.

byline

The `byline` package is a simple line-by-line stream reader. It can be used to create a transform stream that splits input into lines. It is similar to line-reader but offers a more stream-oriented approach.

split

The `split` package is a transform stream that splits input into lines or other delimiters. It is highly configurable and can be used in a pipeline with other streams. It is a good alternative for those who prefer working with streams.

README

Line Reader

Asynchronous, buffered, line-by-line file/stream reader with support for user-defined line separators.

Install

npm install line-reader

Usage

The eachLine function reads each line of the given file. Upon each new line, the given callback function is called with two parameters: the line read and a boolean value specifying whether the line read was the last line of the file. If the callback returns false, reading will stop and the file will be closed.

var lineReader = require('line-reader');

lineReader.eachLine('file.txt', function(line, last) {
  console.log(line);

  if (/* done */) {
    return false; // stop reading
  }
});

eachLine can also be used in an asynchronous manner by providing a third callback parameter like so:

var lineReader = require('line-reader');

lineReader.eachLine('file.txt', function(line, last, cb) {
  console.log(line);

  if (/* done */) {
    cb(false); // stop reading
  } else {
    cb();
  }
});

You can provide an optional second node-style callback that will be called with (err) on failure or () when finished (even if you manually terminate iteration by returning false from the iteratee):

var lineReader = require('line-reader');

// read all lines:
lineReader.eachLine('file.txt', function(line) {
  console.log(line);
}).then(function (err) {
  if (err) throw err;
  console.log("I'm done!!");
});

For more granular control, open, hasNextLine, and nextLine maybe be used to iterate a file (but you must close it yourself):

// or read line by line:
lineReader.open('file.txt', function(err, reader) {
  if (err) throw err;
  if (reader.hasNextLine()) {
    reader.nextLine(function(err, line) {
      try {
        if (err) throw err;
        console.log(line);
      } finally {
        reader.close(function(err) {
          if (err) throw err;          
        });
      }
    });
  }
  else {
    reader.close(function(err) {
      if (err) throw err;          
    });
  }
});

You may provide additional options in a hash before the callbacks to eachLine or open:

• separator - a string or RegExp separator (defaults to /\r\n?|\n/)
• encoding - file encoding (defaults to 'utf8')
• bufferSize - amount of bytes to buffer (defaults to 1024)

For example:

lineReader.eachLine('file.txt', {separator: ';', encoding: 'utf8'}, function(line, last, cb) {
  console.log(line);
});
lineReader.open('file.txt', {bufferSize: 1024}, function(err, reader) {
  ...
}); 

Streams

Both eachLine and open support passing either a file name or a read stream:

// reading from stdin
lineReader.eachLine(process.stdin, function(line) {});

// reading with file position boundaries
var readStream = fs.createReadStream('test.log', { start: 0, end: 10000 });
lineReader.eachLine(readStream, function(line) {});

Note however that if you're reading user input from stdin then the readline module is probably a better choice.

Promises

eachLine and open are compatible with promisify from bluebird:

var lineReader = require('line-reader'),
    Promise = require('bluebird');

var eachLine = Promise.promisify(lineReader.eachLine);
eachLine('file.txt', function(line) {
  console.log(line);
}).then(function() {
  console.log('done');
}).catch(function(err) {
  console.error(err);
});

If you're using a promise library that doesn't have a promisify function, here's how you can do it:

var lineReader = require('line-reader'),
    Promise = require(...);

var eachLine = function(filename, options, iteratee) {
  return new Promise(function(resolve, reject) {
    lineReader.eachLine(filename, options, iteratee, function(err) {
      if (err) {
        reject(err);
      } else {
        resolve();
      }
    });
  });
}
eachLine('file.txt', function(line) {
  console.log(line);
}).then(function() {
  console.log('done');
}).catch(function(err) {
  console.error(err);
});

Contributors

• Nick Ewing
• Andy Edwards (jedwards1211)
• Jameson Little (beatgammit)
• Masum (masumsoft)
• Matthew Caruana Galizia (mattcg)
• Ricardo Bin (ricardohbin)

Paul Em has also written a reverse-version of this gem to read files from bottom to top: reverse-line-reader.

Copyright 2011 Nick Ewing.