readme.md (4195B)
1 # get-stream 2 3 > Get a stream as a string, buffer, or array 4 5 ## Install 6 7 ``` 8 $ npm install get-stream 9 ``` 10 11 ## Usage 12 13 ```js 14 const fs = require('fs'); 15 const getStream = require('get-stream'); 16 17 (async () => { 18 const stream = fs.createReadStream('unicorn.txt'); 19 20 console.log(await getStream(stream)); 21 /* 22 ,,))))))));, 23 __)))))))))))))), 24 \|/ -\(((((''''((((((((. 25 -*-==//////(('' . `)))))), 26 /|\ ))| o ;-. '((((( ,(, 27 ( `| / ) ;))))' ,_))^;(~ 28 | | | ,))((((_ _____------~~~-. %,;(;(>';'~ 29 o_); ; )))(((` ~---~ `:: \ %%~~)(v;(`('~ 30 ; ''''```` `: `:::|\,__,%% );`'; ~ 31 | _ ) / `:|`----' `-' 32 ______/\/~ | / / 33 /~;;.____/;;' / ___--,-( `;;;/ 34 / // _;______;'------~~~~~ /;;/\ / 35 // | | / ; \;;,\ 36 (<_ | ; /',/-----' _> 37 \_| ||_ //~;~~~~~~~~~ 38 `\_| (,~~ 39 \~\ 40 ~~ 41 */ 42 })(); 43 ``` 44 45 ## API 46 47 The 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. 48 49 ### getStream(stream, options?) 50 51 Get the `stream` as a string. 52 53 #### options 54 55 Type: `object` 56 57 ##### encoding 58 59 Type: `string`\ 60 Default: `'utf8'` 61 62 [Encoding](https://nodejs.org/api/buffer.html#buffer_buffer) of the incoming stream. 63 64 ##### maxBuffer 65 66 Type: `number`\ 67 Default: `Infinity` 68 69 Maximum length of the returned string. If it exceeds this value before the stream ends, the promise will be rejected with a `getStream.MaxBufferError` error. 70 71 ### getStream.buffer(stream, options?) 72 73 Get the `stream` as a buffer. 74 75 It honors the `maxBuffer` option as above, but it refers to byte length rather than string length. 76 77 ### getStream.array(stream, options?) 78 79 Get the `stream` as an array of values. 80 81 It honors both the `maxBuffer` and `encoding` options. The behavior changes slightly based on the encoding chosen: 82 83 - 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). 84 85 - 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. 86 87 - 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. 88 89 ## Errors 90 91 If 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. 92 93 ```js 94 (async () => { 95 try { 96 await getStream(streamThatErrorsAtTheEnd('unicorn')); 97 } catch (error) { 98 console.log(error.bufferedData); 99 //=> 'unicorn' 100 } 101 })() 102 ``` 103 104 ## FAQ 105 106 ### How is this different from [`concat-stream`](https://github.com/maxogden/concat-stream)? 107 108 This 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. 109 110 ## Related 111 112 - [get-stdin](https://github.com/sindresorhus/get-stdin) - Get stdin as a string or buffer 113 114 --- 115 116 <div align="center"> 117 <b> 118 <a href="https://tidelift.com/subscription/pkg/npm-get-stream?utm_source=npm-get-stream&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a> 119 </b> 120 <br> 121 <sub> 122 Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies. 123 </sub> 124 </div>