byline

What is byline?

The byline npm package is designed to help with reading lines from a stream, such as a file or stdin, efficiently. It wraps Node.js streams and allows for easy line-by-line processing without having to manage buffering or line splitting manually. This can be particularly useful for reading large files or processing real-time data feeds where handling data line-by-line is necessary.

What are byline's main functionalities?

Line-by-line Stream Reading

This feature allows you to read from a stream line-by-line. The code sample demonstrates how to create a readable stream from a file and use byline to process each line as it becomes available.

const byline = require('byline');
const fs = require('fs');

let stream = byline(fs.createReadStream('file.txt', { encoding: 'utf8' }));

stream.on('data', function(line) {
  console.log(line);
});

Other packages similar to byline

readline

The readline package is a core Node.js module that provides an interface for reading data from a Readable stream (such as process.stdin) one line at a time. It differs from byline in that it's built into Node.js and offers more complex features for input processing, such as prompting and history. However, byline is simpler for basic line-by-line stream reading.

split

Split is an npm package that allows you to split a stream of data into lines or any other arbitrary chunks based on a delimiter. It's similar to byline in its basic functionality but offers more flexibility in terms of customizing the delimiter and handling edge cases. Byline, on the other hand, is more focused on line-by-line processing with less configuration.

through2

Through2 is a tiny wrapper around Node.js streams.Transform (Streams2/3) to make defining custom transform streams easier. While not specifically designed for line-by-line processing like byline, it can be used in combination with other modules to achieve similar functionality. It provides a lower-level API for stream transformation, making it more versatile but also requiring more boilerplate code for simple tasks.

README

byline — buffered stream for reading lines

byline is a simple module providing a LineStream.

• node v0.10 streams2 (transform stream)
• supports pipe
• supports both UNIX and Windows line endings
• supports Unicode UTS #18 line boundaries
• can wrap any readable stream
• can be used as a readable-writable "through-stream" (transform stream)
• super-simple: stream = byline(stream);

Install

npm install byline

or from source:

git clone git://github.com/jahewson/node-byline.git
cd node-byline
npm link

Convenience API

The byline module can be used as a function to quickly wrap a readable stream:

var fs = require('fs'),
    byline = require('byline');

var stream = byline(fs.createReadStream('sample.txt', { encoding: 'utf8' }));

The data event then emits lines:

stream.on('data', function(line) {
  console.log(line);
});

Standard API

You just need to add one line to wrap your readable Stream with a LineStream.

var fs = require('fs'),	
    byline = require('byline');

var stream = fs.createReadStream('sample.txt');
stream = byline.createStream(stream);

stream.on('data', function(line) {
  console.log(line);
});

Piping

byline supports pipe (though it strips the line endings, of course).

var stream = fs.createReadStream('sample.txt');
stream = byline.createStream(stream);
stream.pipe(fs.createWriteStream('nolines.txt'));

Alternatively, you can create a readable/writable "through-stream" which doesn't wrap any specific stream:

var stream = fs.createReadStream('sample.txt');
stream = byline.createStream(stream);
stream.pipe(fs.createWriteStream('nolines.txt'));
	
var input = fs.createReadStream('LICENSE');
var lineStream = byline.createStream();
input.pipe(lineStream);

var output = fs.createWriteStream('test.txt');
lineStream.pipe(output);

Streams2 API

Node v0.10 added a new streams2 API. This allows the stream to be used in non-flowing mode and is preferred over the legacy pause() and resume() methods.

var stream = fs.createReadStream('sample.txt');
stream = byline.createStream(stream);

stream.on('readable', function() {
  var line;
  while (null !== (line = stream.read())) {
    console.log(line);
  }
});

Transform Stream

The byline transform stream can be directly manipulated like so:

var LineStream = require('byline').LineStream;

var input = fs.createReadStream('sample.txt');
var output = fs.createWriteStream('nolines.txt');

var lineStream = new LineStream();
input.pipe(lineStream);
lineStream.pipe(output);

Empty Lines

By default byline skips empty lines, if you want to keep them, pass the keepEmptyLines option in the call to byline.createStream(stream, options) or byline(stream, options).

Tests

npm test

v0.8

If you want to use node-byline with node v0.8 then you can use the 2.1.x series. Simply use the following in your package.json:

  "dependencies": {
  "byline": ">=2.1.0 <3.0.0"
},

Simple

Unlike other modules (of which there are many), byline contains no:

• monkeypatching
• dependencies
• non-standard 'line' events which break pipe
• limitations to only file streams
• CoffeeScript
• unnecessary code