split

What is split?

The 'split' npm package is a stream utility that splits a stream of data into a stream of lines or any other delimited chunks. It's useful for processing streams of text data, such as logs or other outputs that are line-delimited.

What are split's main functionalities?

Splitting stream by newlines

This code sample demonstrates how to use the 'split' package to read data from the standard input and split it into lines. Each line is then logged to the console.

"use strict";
const split = require('split');
process.stdin.pipe(split()).on('data', function (line) {
  console.log('Line: ' + line);
});

Custom delimiter

This code sample shows how to use a custom delimiter (';') to split the stream into chunks. Each chunk is logged to the console.

"use strict";
const split = require('split');
process.stdin.pipe(split(';')).on('data', function (chunk) {
  console.log('Chunk: ' + chunk);
});

Mapping lines

This code sample uses the 'split' package to map each line of the input to uppercase before emitting it. The mapped lines are logged to the console.

"use strict";
const split = require('split');
function map(line) {
  return line.toUpperCase();
}
process.stdin.pipe(split(map)).on('data', function (line) {
  console.log('Mapped Line: ' + line);
});

Other packages similar to split

byline

The 'byline' package is similar to 'split' in that it also provides a way to read a stream line by line. However, 'byline' is specifically focused on lines and does not support custom delimiters.

binary-split

The 'binary-split' package is another alternative to 'split' that is optimized for splitting binary streams. It is similar in functionality but may perform better with binary data.

through2

While 'through2' is not a direct alternative to 'split', it can be used in combination with other stream transformers to achieve similar line splitting functionality. It provides a simple wrapper around Node.js streams Transform to make creating custom transform streams easier.

README

Split (matcher)

Break up a stream and reassemble it so that each line is a chunk. matcher may be a String, or a RegExp

Example, read every line in a file ...

  fs.createReadStream(file)
    .pipe(split())
    .on('data', function (line) {
      //each chunk now is a seperate line!
    })

split takes the same arguments as string.split except it defaults to '/\r?\n/' instead of ',', and the optional limit paremeter is ignored. String#split

split takes an optional options object on it's third argument.

  split(matcher, mapper, options)

Valid options:

• maxLength - The maximum buffer length without seeing a newline or matcher, if a single line exceeds this, the split stream will emit an error.

  split(JSON.parse, null, { maxLength: 2})

• trailing - By default the last buffer not delimited by a newline or matcher will be emitted. To prevent this set options.trailing to false.

  split(JSON.parse, null, { trailing: false })

keep matched splitter

As with Array#split, if you split by a regular expression with a matching group, the matches will be retained in the collection.

stdin
.pipe(split(/(\r?\n)/))
... //lines + separators.

NDJ - Newline Delimited Json

split accepts a function which transforms each line.

fs.createReadStream(file)
  .pipe(split(JSON.parse))
  .on('data', function (obj) {
    //each chunk now is a a js object
  })
  .on('error', function (err) {
    //syntax errors will land here
    //note, this ends the stream.
  })

License

MIT