# line-reader

> Asynchronous, buffered, line-by-line file/stream reader

Latest version **0.4.0** (published 2016-03-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install line-reader
pnpm add line-reader
yarn add line-reader
bun add line-reader
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2016-03-17 |
| First published | 2011-03-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/line-reader) |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 451 |
| Author | Nick Ewing |
| Maintainers | nickewing |
| Keywords | file, line, reader, scanner |

## Links

- npm: https://www.npmjs.com/package/line-reader
- Repository: https://nickewing@github.com/nickewing/line-reader
- Homepage: https://github.com/nickewing/line-reader#readme
- Issues: https://github.com/nickewing/line-reader/issues
- npm.io page: https://npm.io/package/line-reader

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 0.4.0 (latest) — 2016-03-17
- 0.3.1 — 2016-03-16
- 0.3.0 — 2015-10-13
- 0.2.4 — 2014-07-18
- 0.2.3 — 2012-09-05
- 0.2.2 — 2012-08-19
- 0.2.1 — 2012-07-13
- 0.2.0 — 2012-07-13
- 0.1.3 — 2011-03-20
- 0.1.2 — 2011-03-16
- 0.1.1 — 2011-03-16
- 0.1.0 — 2011-03-16

## 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](https://nodejs.org/api/readline.html) is probably a better choice.

Promises
--------

`eachLine` and `open` are compatible with `promisify` from [bluebird](https://github.com/petkaantonov/bluebird/blob/master/API.md#promisepromisifyfunction-nodefunction--dynamic-receiver---function):

    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](https://github.com/paul-em/reverse-line-reader).

Copyright 2011 Nick Ewing.

---
_Source: https://npm.io/package/line-reader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._