1# get-stream [](https://travis-ci.org/sindresorhus/get-stream) 2 3> Get a stream as a string, buffer, or array 4 5 6## Install 7 8``` 9$ npm install get-stream 10``` 11 12 13## Usage 14 15```js 16const fs = require('fs'); 17const getStream = require('get-stream'); 18 19(async () => { 20 const stream = fs.createReadStream('unicorn.txt'); 21 22 console.log(await getStream(stream)); 23 /* 24 ,,))))))));, 25 __)))))))))))))), 26 \|/ -\(((((''''((((((((. 27 -*-==//////(('' . `)))))), 28 /|\ ))| o ;-. '((((( ,(, 29 ( `| / ) ;))))' ,_))^;(~ 30 | | | ,))((((_ _____------~~~-. %,;(;(>';'~ 31 o_); ; )))(((` ~---~ `:: \ %%~~)(v;(`('~ 32 ; ''''```` `: `:::|\,__,%% );`'; ~ 33 | _ ) / `:|`----' `-' 34 ______/\/~ | / / 35 /~;;.____/;;' / ___--,-( `;;;/ 36 / // _;______;'------~~~~~ /;;/\ / 37 // | | / ; \;;,\ 38 (<_ | ; /',/-----' _> 39 \_| ||_ //~;~~~~~~~~~ 40 `\_| (,~~ 41 \~\ 42 ~~ 43 */ 44})(); 45``` 46 47 48## API 49 50The methods returns a promise that resolves when the `end` event fires on the stream, indicating that there is no more data to be read. The stream is switched to flowing mode. 51 52### getStream(stream, [options]) 53 54Get the `stream` as a string. 55 56#### options 57 58Type: `Object` 59 60##### encoding 61 62Type: `string`<br> 63Default: `utf8` 64 65[Encoding](https://nodejs.org/api/buffer.html#buffer_buffer) of the incoming stream. 66 67##### maxBuffer 68 69Type: `number`<br> 70Default: `Infinity` 71 72Maximum length of the returned string. If it exceeds this value before the stream ends, the promise will be rejected with a `getStream.MaxBufferError` error. 73 74### getStream.buffer(stream, [options]) 75 76Get the `stream` as a buffer. 77 78It honors the `maxBuffer` option as above, but it refers to byte length rather than string length. 79 80### getStream.array(stream, [options]) 81 82Get the `stream` as an array of values. 83 84It honors both the `maxBuffer` and `encoding` options. The behavior changes slightly based on the encoding chosen: 85 86- When `encoding` is unset, it assumes an [object mode stream](https://nodesource.com/blog/understanding-object-streams/) and collects values emitted from `stream` unmodified. In this case `maxBuffer` refers to the number of items in the array (not the sum of their sizes). 87 88- When `encoding` is set to `buffer`, it collects an array of buffers. `maxBuffer` refers to the summed byte lengths of every buffer in the array. 89 90- When `encoding` is set to anything else, it collects an array of strings. `maxBuffer` refers to the summed character lengths of every string in the array. 91 92 93## Errors 94 95If the input stream emits an `error` event, the promise will be rejected with the error. The buffered data will be attached to the `bufferedData` property of the error. 96 97```js 98(async () => { 99 try { 100 await getStream(streamThatErrorsAtTheEnd('unicorn')); 101 } catch (error) { 102 console.log(error.bufferedData); 103 //=> 'unicorn' 104 } 105})() 106``` 107 108 109## FAQ 110 111### How is this different from [`concat-stream`](https://github.com/maxogden/concat-stream)? 112 113This module accepts a stream instead of being one and returns a promise instead of using a callback. The API is simpler and it only supports returning a string, buffer, or array. It doesn't have a fragile type inference. You explicitly choose what you want. And it doesn't depend on the huge `readable-stream` package. 114 115 116## Related 117 118- [get-stdin](https://github.com/sindresorhus/get-stdin) - Get stdin as a string or buffer 119 120 121## License 122 123MIT © [Sindre Sorhus](https://sindresorhus.com) 124
){kind=link}