stream-splice

1.1.0 • Public • Published

stream-splice

NPM

Compose multi-step streams into a single pipeline segment.

E.g. your transform module is actually two consecutive transform operations, but you want it exposed as a single "stream.Transform" object.

// In your module
module.exports = tx
var filter = require("through2-filter")
var map = require("through2-map")
var splice = require("stream-splice")
 
function tx() {
  var noBs = filter(function (chunk) { return /[^bB]/.exec(chunk) })
  var uc = map(function (chunk) { return chunk.toString().toUpperCase() })
  var zz = map(function (chunk) { return chunk.toString() + "z" })
 
  return splice(noBs, uc, zz)
}
 
// Using your module:
var tx = require("my-module")
 
source.pipe(tx()).pipe(/* ... */)
 
// That is equivalent to:
source.pipe(noBs)
  .pipe(uc)
  .pipe(zz)
  .pipe(/* ... */)
 
// A less contrived example:
// catLines is equivalent to fs.createReadStream except stream chunks
// will be the lines of the file
module.exports = catLines
 
var fs = require("fs")
var split = require("split")
var map = require("through2-map")
var splice = require("stream-splice")
 
function catLines(filename, options) {
  var rs = fs.createReadStream(filename, options)
  var reAddNewline = map(function (chunk) { return chunk.toString() + "\n" })
  return splice(rs, split(), reAddNewline)
}
 
 

API

splice(stream1 [,stream2] [,...streamN])

Creates a pipeline that can be piped into/out of which is composed of all of the spliced streams piped together.

E.g.

source.pipe(splice(a, b, c)).pipe(drain)
 
// is roughly equivalent to
 
source.pipe(a)
  .pipe(b)
  .pipe(c)
  .pipe(drain)
 

Error Handling:

Just like pipe, splice does NOT attempt to do error forwarding. Sure, it could do something where all the errors in the pipeline are forwarded onto the topmost stream, however this would create a hidden requirement of code organization where your error handlers would have to be above the splice call to avoid double-handled errors.

So do this:

a.on("error", someErrHandler)
b.on("error", someErrHandler)
c.on("error", someErrHandler)
 
source.pipe(splice(a, b, c)).pipe(drain)

This will let you keep the maximum flexibility with your error handling.

LICENSE

MIT

Package Sidebar

Install

npm i stream-splice

Weekly Downloads

10

Version

1.1.0

License

MIT

Last publish

Collaborators

  • bryce