nickewing

Asynchronous line-by-line file reader for node.js

422 Stars 75 Forks Last release: Not found MIT License 63 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Readme

Line Reader

Name: line-reader
Brand: line-reader
SKU: //nickewing/line-reader
Rating: 1.1688 (422 reviews)

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);
}, 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

open

: *

separator

- a

string

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.

line-reader

by nickewing