strong-tie/inbound-calls

1# Split2(matcher, mapper, options)2 3![ci](https://github.com/mcollina/split2/workflows/ci/badge.svg)4 5Break up a stream and reassemble it so that each line is a chunk.6`split2` is inspired by [@dominictarr](https://github.com/dominictarr) [`split`](https://github.com/dominictarr/split) module,7and it is totally API compatible with it.8However, it is based on Node.js core [`Transform`](https://nodejs.org/api/stream.html#stream_new_stream_transform_options).9 10`matcher` may be a `String`, or a `RegExp`. Example, read every line in a file ...11 12``` js13  fs.createReadStream(file)14    .pipe(split2())15    .on('data', function (line) {16      //each chunk now is a separate line!17    })18 19```20 21`split` takes the same arguments as `string.split` except it defaults to '/\r?\n/', and the optional `limit` paremeter is ignored.22[String#split](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String/split)23 24`split` takes an optional options object on it's third argument, which25is directly passed as a26[Transform](https://nodejs.org/api/stream.html#stream_new_stream_transform_options)27option.28 29Additionally, the `.maxLength` and `.skipOverflow` options are implemented, which set limits on the internal30buffer size and the stream's behavior when the limit is exceeded. There is no limit unless `maxLength` is set. When31the internal buffer size exceeds `maxLength`, the stream emits an error by default. You may also set `skipOverflow` to32true to suppress the error and instead skip past any lines that cause the internal buffer to exceed `maxLength`.33 34Calling `.destroy` will make the stream emit `close`. Use this to perform cleanup logic35 36``` js37var splitFile = function(filename) {38  var file = fs.createReadStream(filename)39 40  return file41    .pipe(split2())42    .on('close', function() {43      // destroy the file stream in case the split stream was destroyed44      file.destroy()45    })46}47 48var stream = splitFile('my-file.txt')49 50stream.destroy() // will destroy the input file stream51```52 53# NDJ - Newline Delimited Json54 55`split2` accepts a function which transforms each line.56 57``` js58fs.createReadStream(file)59  .pipe(split2(JSON.parse))60  .on('data', function (obj) {61    //each chunk now is a js object62  })63  .on("error", function(error) {64    //handling parsing errors65  })66```67 68However, in [@dominictarr](https://github.com/dominictarr) [`split`](https://github.com/dominictarr/split) the mapper69is wrapped in a try-catch, while here it is not: if your parsing logic can throw, wrap it yourself. Otherwise, you can also use the stream error handling when mapper function throw.70 71# License72 73Copyright (c) 2014-2021, Matteo Collina <hello@matteocollina.com>74 75Permission to use, copy, modify, and/or distribute this software for any76purpose with or without fee is hereby granted, provided that the above77copyright notice and this permission notice appear in all copies.78 79THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES80WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF81MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR82ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES83WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN84ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR85IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.86