1 | # concat-stream
|
2 |
|
3 | Writable stream that concatenates all the data from a stream and calls a callback with the result. Use this when you want to collect all the data from a stream into a single buffer.
|
4 |
|
5 | [![Build Status](https://travis-ci.org/maxogden/concat-stream.svg?branch=master)](https://travis-ci.org/maxogden/concat-stream)
|
6 |
|
7 | [![NPM](https://nodei.co/npm/concat-stream.png)](https://nodei.co/npm/concat-stream/)
|
8 |
|
9 | ### description
|
10 |
|
11 | Streams emit many buffers. If you want to collect all of the buffers, and when the stream ends concatenate all of the buffers together and receive a single buffer then this is the module for you.
|
12 |
|
13 | Only use this if you know you can fit all of the output of your stream into a single Buffer (e.g. in RAM).
|
14 |
|
15 | There are also `objectMode` streams that emit things other than Buffers, and you can concatenate these too. See below for details.
|
16 |
|
17 | ## Related
|
18 |
|
19 | `concat-stream` is part of the [mississippi stream utility collection](https://github.com/maxogden/mississippi) which includes more useful stream modules similar to this one.
|
20 |
|
21 | ### examples
|
22 |
|
23 | #### Buffers
|
24 |
|
25 | ```js
|
26 | var fs = require('fs')
|
27 | var concat = require('concat-stream')
|
28 |
|
29 | var readStream = fs.createReadStream('cat.png')
|
30 | var concatStream = concat(gotPicture)
|
31 |
|
32 | readStream.on('error', handleError)
|
33 | readStream.pipe(concatStream)
|
34 |
|
35 | function gotPicture(imageBuffer) {
|
36 | // imageBuffer is all of `cat.png` as a node.js Buffer
|
37 | }
|
38 |
|
39 | function handleError(err) {
|
40 | // handle your error appropriately here, e.g.:
|
41 | console.error(err) // print the error to STDERR
|
42 | process.exit(1) // exit program with non-zero exit code
|
43 | }
|
44 |
|
45 | ```
|
46 |
|
47 | #### Arrays
|
48 |
|
49 | ```js
|
50 | var write = concat(function(data) {})
|
51 | write.write([1,2,3])
|
52 | write.write([4,5,6])
|
53 | write.end()
|
54 | // data will be [1,2,3,4,5,6] in the above callback
|
55 | ```
|
56 |
|
57 | #### Uint8Arrays
|
58 |
|
59 | ```js
|
60 | var write = concat(function(data) {})
|
61 | var a = new Uint8Array(3)
|
62 | a[0] = 97; a[1] = 98; a[2] = 99
|
63 | write.write(a)
|
64 | write.write('!')
|
65 | write.end(Buffer.from('!!1'))
|
66 | ```
|
67 |
|
68 | See `test/` for more examples
|
69 |
|
70 | # methods
|
71 |
|
72 | ```js
|
73 | var concat = require('concat-stream')
|
74 | ```
|
75 |
|
76 | ## var writable = concat(opts={}, cb)
|
77 |
|
78 | Return a `writable` stream that will fire `cb(data)` with all of the data that
|
79 | was written to the stream. Data can be written to `writable` as strings,
|
80 | Buffers, arrays of byte integers, and Uint8Arrays.
|
81 |
|
82 | By default `concat-stream` will give you back the same data type as the type of the first buffer written to the stream. Use `opts.encoding` to set what format `data` should be returned as, e.g. if you if you don't want to rely on the built-in type checking or for some other reason.
|
83 |
|
84 | * `string` - get a string
|
85 | * `buffer` - get back a Buffer
|
86 | * `array` - get an array of byte integers
|
87 | * `uint8array`, `u8`, `uint8` - get back a Uint8Array
|
88 | * `object`, get back an array of Objects
|
89 |
|
90 | If you don't specify an encoding, and the types can't be inferred (e.g. you write things that aren't in the list above), it will try to convert concat them into a `Buffer`.
|
91 |
|
92 | If nothing is written to `writable` then `data` will be an empty array `[]`.
|
93 |
|
94 | # error handling
|
95 |
|
96 | `concat-stream` does not handle errors for you, so you must handle errors on whatever streams you pipe into `concat-stream`. This is a general rule when programming with node.js streams: always handle errors on each and every stream. Since `concat-stream` is not itself a stream it does not emit errors.
|
97 |
|
98 | We recommend using [`end-of-stream`](https://npmjs.org/end-of-stream) or [`pump`](https://npmjs.org/pump) for writing error tolerant stream code.
|
99 |
|
100 | # license
|
101 |
|
102 | MIT LICENSE
|