Debian Codegraph @

readme.markdown

raw
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 [![build status](https://travis-ci.org/browserify/stream-splicer.png?branch=master)](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