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

   1 # concat-stream
   2
   3 Writable stream that concatenates strings or binary data and calls a callback with the result. Not a transform stream -- more of a stream sink.
   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 ### examples
  18
  19 #### Buffers
  20
  21 ```js
  22 var fs = require('fs')
  23 var concat = require('concat-stream')
  24
  25 var readStream = fs.createReadStream('cat.png')
  26 var concatStream = concat(gotPicture)
  27
  28 readStream.on('error', handleError)
  29 readStream.pipe(concatStream)
  30
  31 function gotPicture(imageBuffer) {
  32   // imageBuffer is all of `cat.png` as a node.js Buffer
  33 }
  34
  35 function handleError(err) {
  36   // handle your error appropriately here, e.g.:
  37   console.error(err) // print the error to STDERR
  38   process.exit(1) // exit program with non-zero exit code
  39 }
  40
  41 ```
  42
  43 #### Arrays
  44
  45 ```js
  46 var write = concat(function(data) {})
  47 write.write([1,2,3])
  48 write.write([4,5,6])
  49 write.end()
  50 // data will be [1,2,3,4,5,6] in the above callback
  51 ```
  52
  53 #### Uint8Arrays
  54
  55 ```js
  56 var write = concat(function(data) {})
  57 var a = new Uint8Array(3)
  58 a[0] = 97; a[1] = 98; a[2] = 99
  59 write.write(a)
  60 write.write('!')
  61 write.end(Buffer('!!1'))
  62 ```
  63
  64 See `test/` for more examples
  65
  66 # methods
  67
  68 ```js
  69 var concat = require('concat-stream')
  70 ```
  71
  72 ## var writable = concat(opts={}, cb)
  73
  74 Return a `writable` stream that will fire `cb(data)` with all of the data that
  75 was written to the stream. Data can be written to `writable` as strings,
  76 Buffers, arrays of byte integers, and Uint8Arrays.
  77
  78 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.
  79
  80 * `string` - get a string
  81 * `buffer` - get back a Buffer
  82 * `array` - get an array of byte integers
  83 * `uint8array`, `u8`, `uint8` - get back a Uint8Array
  84 * `object`, get back an array of Objects
  85
  86 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`.
  87
  88 # error handling
  89
  90 `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.
  91
  92 # license
  93
  94 MIT LICENSE