1 | # pull-stream/pull
|
2 |
|
3 | > pipe many pull streams into a pipeline
|
4 |
|
5 | ## Background
|
6 |
|
7 | In pull-streams, you need a complete pipeline before data will flow.
|
8 |
|
9 | That means: a source, zero or more throughs, and a sink.
|
10 |
|
11 | But you can still create a _partial_ pipeline, which is a great for tiny pull-stream modules.
|
12 |
|
13 | ## Usage
|
14 |
|
15 | ```js
|
16 | var pull = require('pull-stream/pull')
|
17 | ```
|
18 |
|
19 | Create a simple complete pipeline:
|
20 |
|
21 | ```js
|
22 | pull(source, sink) => undefined
|
23 | ```
|
24 |
|
25 | Create a source modified by a through:
|
26 |
|
27 | ```js
|
28 | pull(source, through) => source
|
29 | ```
|
30 |
|
31 | Create a sink, but modify it's input before it goes.
|
32 |
|
33 | ```js
|
34 | pull(through, sink) => sink
|
35 | ```
|
36 |
|
37 | Create a through, by chainging several throughs:
|
38 |
|
39 | ```js
|
40 | pull(through1, through2) => through
|
41 | ```
|
42 |
|
43 | These streams combine just like normal streams.
|
44 |
|
45 | ```js
|
46 | pull(
|
47 | pull(source, through),
|
48 | pull(through1, through2),
|
49 | pull(through, sink)
|
50 | ) => undefined
|
51 | ```
|
52 |
|
53 | The complete pipeline returns undefined, because it cannot be piped to anything else.
|
54 |
|
55 | Pipe duplex streams like this:
|
56 |
|
57 | ```js
|
58 | var a = duplex()
|
59 | var b = duplex()
|
60 |
|
61 | pull(a.source, b.sink)
|
62 | pull(b.source, a.sink)
|
63 |
|
64 | //which is the same as
|
65 |
|
66 | b.sink(a.source); a.sink(b.source)
|
67 |
|
68 | //but the easiest way is to allow pull to handle this
|
69 |
|
70 | pull(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
|
80 | var cont = pull(...streams, sink)
|
81 |
|
82 | // ...
|
83 |
|
84 | cont(function (err) {
|
85 | // stream finished
|
86 | })
|
87 | ```
|
88 |
|
89 | Or call beside it if you are not deferring:
|
90 |
|
91 | ```js
|
92 | pull(...streams, sink)(function (err) {
|
93 | // stream finished
|
94 | })
|
95 | ```
|
96 |
|
97 | They are created by making a sink stream return a continuable, which uses it's callback and reads:
|
98 |
|
99 | ```js
|
100 | function 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
|
115 | var 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 |
|
124 | If the pipeline is complete (reduces into a source being passed into a sink), then `pull` returns `undefined`, as the data is flowing.
|
125 |
|
126 | If 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 |
|
130 | With [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)
|