split2

split2 is a small Node.js library that turns a stream of text into a stream of discrete records — by default splitting on line breaks, but configurable with any regex/string matcher and an optional mapper function to transform each record before it’s emitted. It’s a Streams3-native rewrite of the older split module, built directly on Node’s stream.Transform rather than a legacy stream API, and is commonly piped after readline-style sources (child process stdout, log files, network sockets) to turn raw byte/text chunks into line-by-line data.

The implementation buffers partial lines across chunk boundaries, guards against unbounded memory growth with a configurable maxLength/skipOverflow option, and correctly decodes multi-byte UTF-8 sequences that may be split across chunk boundaries via Node’s StringDecoder.

What You Get

• A split(matcher, mapper, options) factory that returns a ready-to-pipe Transform stream
• Configurable line matcher (default /\r?\n/) so any string or regex delimiter can be used instead of newlines
• An optional per-line mapper function (e.g. JSON.parse) applied to each record before it’s pushed downstream
• maxLength/skipOverflow options to bound memory usage when no delimiter is found in a long stream
• Correct handling of multi-byte UTF-8 characters split across chunk boundaries via Node’s built-in StringDecoder

Common Use Cases

• Piping a child process’s stdout/stderr through split2 to process output line by line
• Parsing newline-delimited JSON (NDJSON) log streams by combining split2 with a JSON.parse mapper
• Reading large log files as a stream of lines without loading the whole file into memory
• Building CLI tools that consume piped stdin text a line at a time

Under The Hood

Architecture The entire library is a single 141-line module (index.js) exporting a split() factory: it constructs a stream.Transform configured with custom transform() and flush() functions, tracks unconsumed trailing text in a Symbol-keyed kLast property between chunks, decodes incoming buffers via a Symbol-keyed StringDecoder instance (kDecoder) to correctly handle multi-byte characters split across chunk boundaries, and splits the accumulated text against a matcher (default /\r?\n/) on each transform call, pushing every complete line except the last (possibly incomplete) fragment, which is carried into the next chunk.

Tech Stack Zero-dependency Node.js core code, using only the built-in stream and string_decoder modules; ships as plain CommonJS with no build/transpilation step, targeting Node >=12.

Code Quality The project enforces 100% line/branch/function coverage via its unit script (nyc —lines 100 —branches 100 —functions 100 —check-coverage), tested against tape in test.js, and lints with standard — an unusually strict bar reflecting the library’s role as low-level, widely-depended-upon stream plumbing where a subtle bug (e.g. mishandling a split multi-byte character or overflow condition) would silently corrupt output for every downstream consumer.

API Design The split(matcher, mapper, options) signature overloads its arguments based on type (a lone function argument is treated as mapper, a lone object as options), which keeps common calls terse (require(‘split2’)() for line splitting) but means less-common combinations benefit from checking the README’s argument-detection table.