www.aleph1.co.uk Git - yaffs-website/blob - node_modules/get-stream/readme.md

   1 # get-stream [![Build Status](https://travis-ci.org/sindresorhus/get-stream.svg?branch=master)](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 --save get-stream
  10 ```
  11
  12
  13 ## Usage
  14
  15 ```js
  16 const fs = require('fs');
  17 const getStream = require('get-stream');
  18 const stream = fs.createReadStream('unicorn.txt');
  19
  20 getStream(stream).then(str => {
  21         console.log(str);
  22         /*
  23                       ,,))))))));,
  24                    __)))))))))))))),
  25         \|/       -\(((((''''((((((((.
  26         -*-==//////((''  .     `)))))),
  27         /|\      ))| o    ;-.    '(((((                                  ,(,
  28                  ( `|    /  )    ;))))'                               ,_))^;(~
  29                     |   |   |   ,))((((_     _____------~~~-.        %,;(;(>';'~
  30                     o_);   ;    )))(((` ~---~  `::           \      %%~~)(v;(`('~
  31                           ;    ''''````         `:       `:::|\,__,%%    );`'; ~
  32                          |   _                )     /      `:|`----'     `-'
  33                    ______/\/~    |                 /        /
  34                  /~;;.____/;;'  /          ___--,-(   `;;;/
  35                 / //  _;______;'------~~~~~    /;;/\    /
  36                //  | |                        / ;   \;;,\
  37               (<_  | ;                      /',/-----'  _>
  38                \_| ||_                     //~;~~~~~~~~~
  39                    `\_|                   (,~~
  40                                            \~\
  41                                             ~~
  42         */
  43 });
  44 ```
  45
  46
  47 ## API
  48
  49 The methods returns a promise that is resolved 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.
  50
  51 ### getStream(stream, [options])
  52
  53 Get the `stream` as a string.
  54
  55 #### options
  56
  57 ##### encoding
  58
  59 Type: `string`<br>
  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`<br>
  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.
  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
  90 ## Errors
  91
  92 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.
  93
  94 ```js
  95 getStream(streamThatErrorsAtTheEnd('unicorn'))
  96         .catch(err => console.log(err.bufferedData));
  97 // unicorn
  98 ```
  99
 100
 101 ## FAQ
 102
 103 ### How is this different from [`concat-stream`](https://github.com/maxogden/concat-stream)?
 104
 105 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.
 106
 107
 108 ## Related
 109
 110 - [get-stdin](https://github.com/sindresorhus/get-stdin) - Get stdin as a string or buffer
 111
 112
 113 ## License
 114
 115 MIT © [Sindre Sorhus](https://sindresorhus.com)