| 1 |
# stream-splicer |
| 2 |
|
| 3 |
streaming pipeline with a mutable configuration |
| 4 |
|
| 5 |
This module is similar to |
| 6 |
[stream-combiner](https://npmjs.org/package/stream-combiner), |
| 7 |
but with a pipeline configuration that can be changed at runtime. |
| 8 |
|
| 9 |
[](http://travis-ci.org/browserify/stream-splicer) |
| 10 |
|
| 11 |
# example |
| 12 |
|
| 13 |
This example begins with an HTTP header parser that waits for an empty line to |
| 14 |
signify the end of the header. At that point, it switches to a streaming json |
| 15 |
parser to operate on the HTTP body. |
| 16 |
|
| 17 |
``` js |
| 18 |
var splicer = require('stream-splicer'); |
| 19 |
var through = require('through2'); |
| 20 |
var jsonStream = require('jsonstream2'); |
| 21 |
var split = require('split2'); |
| 22 |
|
| 23 |
var headerData = {}; |
| 24 |
var headers = through.obj(function (buf, enc, next) { |
| 25 |
var line = buf.toString('utf8'); |
| 26 |
if (line === '') { |
| 27 |
this.push(headerData); |
| 28 |
pipeline.splice(1, 1, jsonStream.parse([ 'rows', true ])); |
| 29 |
} |
| 30 |
else { |
| 31 |
var m = /^(\S+):(.+)/.exec(line); |
| 32 |
var key = m && m[1].trim(); |
| 33 |
var value = m && m[2].trim(); |
| 34 |
if (m) headerData[key] = value; |
| 35 |
} |
| 36 |
next(); |
| 37 |
}); |
| 38 |
var pipeline = splicer([ split(), headers, jsonStream.stringify() ]); |
| 39 |
process.stdin.pipe(pipeline).pipe(process.stdout); |
| 40 |
``` |
| 41 |
|
| 42 |
intput: |
| 43 |
|
| 44 |
``` |
| 45 |
GET / HTTP/1.1 |
| 46 |
Host: substack.net |
| 47 |
User-Agent: echo |
| 48 |
|
| 49 |
{"rows":["beep","boop"]} |
| 50 |
``` |
| 51 |
|
| 52 |
output: |
| 53 |
|
| 54 |
``` |
| 55 |
$ echo -ne 'GET / HTTP/1.1\nHost: substack.net\nUser-Agent: echo\n\n{"rows":["beep","boop"]}\n' | node example/header.js |
| 56 |
[ |
| 57 |
{"Host":"substack.net","User-Agent":"echo"} |
| 58 |
, |
| 59 |
"beep" |
| 60 |
, |
| 61 |
"boop" |
| 62 |
] |
| 63 |
``` |
| 64 |
|
| 65 |
# methods |
| 66 |
|
| 67 |
``` js |
| 68 |
var splicer = require('stream-splicer') |
| 69 |
``` |
| 70 |
|
| 71 |
## var pipeline = splicer(streams, opts) |
| 72 |
|
| 73 |
Create a `pipeline` duplex stream given an array of `streams`. Each `stream` |
| 74 |
will be piped to the next. Writes to `pipeline` get written to the first stream |
| 75 |
and data for reads from `pipeline` come from the last stream. |
| 76 |
|
| 77 |
For example, for streams `[ a, b, c, d ]`, this pipeline is constructed |
| 78 |
internally: |
| 79 |
|
| 80 |
``` |
| 81 |
a.pipe(b).pipe(c).pipe(d) |
| 82 |
``` |
| 83 |
|
| 84 |
Input will get written into `a`. Output will be read from `d`. |
| 85 |
|
| 86 |
If any of the elements in `streams` are arrays, they will be converted into |
| 87 |
nested pipelines. This is useful if you want to expose a hookable pipeline with |
| 88 |
grouped insertion points. |
| 89 |
|
| 90 |
## var pipeline = splicer.obj(streams, opts) |
| 91 |
|
| 92 |
Create a `pipeline` with `opts.objectMode` set to true for convenience. |
| 93 |
|
| 94 |
## var removed = pipeline.splice(index, howMany, stream, ...) |
| 95 |
|
| 96 |
Splice the pipeline starting at `index`, removing `howMany` streams and |
| 97 |
replacing them with each additional `stream` argument provided. |
| 98 |
|
| 99 |
The streams that were removed from the splice and returned. |
| 100 |
|
| 101 |
## pipeline.push(stream, ...) |
| 102 |
|
| 103 |
Push one or more streams to the end of the pipeline. |
| 104 |
|
| 105 |
## var stream = pipeline.pop() |
| 106 |
|
| 107 |
Pop a stream from the end of the pipeline. |
| 108 |
|
| 109 |
## pipeline.unshift(stream, ...) |
| 110 |
|
| 111 |
Unshift one or more streams to the begining of the pipeline. |
| 112 |
|
| 113 |
## var stream = pipeline.shift() |
| 114 |
|
| 115 |
Shift a stream from the begining of the pipeline. |
| 116 |
|
| 117 |
## var stream = pipeline.get(index, ...) |
| 118 |
|
| 119 |
Return the stream at index `index, ...`. Indexes can be negative. |
| 120 |
|
| 121 |
Multiple indexes will traverse into nested pipelines. |
| 122 |
|
| 123 |
# attributes |
| 124 |
|
| 125 |
## pipeline.length |
| 126 |
|
| 127 |
The number of streams in the pipeline |
| 128 |
|
| 129 |
# install |
| 130 |
|
| 131 |
With [npm](https://npmjs.org) do: |
| 132 |
|
| 133 |
``` |
| 134 |
npm install stream-splicer |
| 135 |
``` |
| 136 |
|
| 137 |
# license |
| 138 |
|
| 139 |
MIT |