UNPKG

3.02 kBMarkdownView Raw
1# pull-stream/pull
2
3> pipe many pull streams into a pipeline
4
5## Background
6
7In pull-streams, you need a complete pipeline before data will flow.
8
9That means: a source, zero or more throughs, and a sink.
10
11But you can still create a _partial_ pipeline, which is a great for tiny pull-stream modules.
12
13## Usage
14
15```js
16var pull = require('pull-stream/pull')
17```
18
19Create a simple complete pipeline:
20
21```js
22pull(source, sink) => undefined
23```
24
25Create a source modified by a through:
26
27```js
28pull(source, through) => source
29```
30
31Create a sink, but modify it's input before it goes.
32
33```js
34pull(through, sink) => sink
35```
36
37Create a through, by chainging several throughs:
38
39```js
40pull(through1, through2) => through
41```
42
43These streams combine just like normal streams.
44
45```js
46pull(
47 pull(source, through),
48 pull(through1, through2),
49 pull(through, sink)
50) => undefined
51```
52
53The complete pipeline returns undefined, because it cannot be piped to anything else.
54
55Pipe duplex streams like this:
56
57```js
58var a = duplex()
59var b = duplex()
60
61pull(a.source, b.sink)
62pull(b.source, a.sink)
63
64//which is the same as
65
66b.sink(a.source); a.sink(b.source)
67
68//but the easiest way is to allow pull to handle this
69
70pull(a, b, a)
71
72//"pull from a to b and then back to a"
73```
74
75## Continuable
76
77[Continuables](https://github.com/Raynos/continuable) let you defer a stream and handle the completion of the sink stream. For example:
78
79```js
80var cont = pull(...streams, sink)
81
82// ...
83
84cont(function (err) {
85 // stream finished
86})
87```
88
89Or call beside it if you are not deferring:
90
91```js
92pull(...streams, sink)(function (err) {
93 // stream finished
94})
95```
96
97They are created by making a sink stream return a continuable, which uses it's callback and reads:
98
99```js
100function sink (read) {
101 return function continuable (done) {
102 // Do reads and eventually call `done`
103 read(null, function (end, data) {
104 if (end === true) return done(null)
105 if (end) return done(end)
106 // ... otherwise use `data`
107 })
108 }
109}
110```
111
112## API
113
114```js
115var pull = require('pull-stream/pull')
116```
117
118### `pull(...streams)`
119
120`pull` is a function that receives n-arity stream arguments and connects them into a pipeline.
121
122`pull` detects the type of stream by checking function arity, if the function takes only one argument it's either a sink or a through. Otherwise it's a source. A duplex stream is an object with the shape `{ source, sink }`.
123
124If the pipeline is complete (reduces into a source being passed into a sink), then `pull` returns `undefined`, as the data is flowing.
125
126If the pipeline is partial (reduces into either a source, a through, or a sink), then `pull` returns the partial pipeline, as it must be composed with other streams before the data will flow.
127
128## Install
129
130With [npm](https://npmjs.org/) installed, run
131
132```sh
133$ npm install pull-stream
134```
135
136## See Also
137
138- [`mafintosh/pump`](https://github.com/mafintosh/pump)
139- [`mafintosh/pumpify`](https://github.com/mafintosh/pumpify)
140
141## License
142
143[MIT](https://tldrlegal.com/license/mit-license)