nodejs-stream.md

   1 ---
   2 title: Node.js streams
   3 category: Node.js
   4 layout: 2017/sheet
   5 weight: -1
   6 updated: 2017-08-30
   7 ---
   8
   9 ### Types
  10
  11 | Stream      | Description                        |
  12 | ---         | ---                                |
  13 | `Readable`  | Data emitter                       |
  14 | `Writable`  | Data receiver                      |
  15 | `Transform` | Emitter and receiver               |
  16 | `Duplex`    | Emitter and receiver (independent) |
  17
  18 See: [Stream](https://nodejs.org/api/stream.html#stream_stream) _(nodejs.org)_
  19
  20 ### Streams
  21
  22 ```js
  23 const Readable = require('stream').Readable
  24 const Writable = require('stream').Writable
  25 const Transform = require('stream').Transform
  26 ```
  27
  28 ### Piping
  29
  30 ```js
  31 clock()              // Readable stream
  32   .pipe(xformer())   // Transform stream
  33   .pipe(renderer())  // Writable stream
  34 ```
  35
  36 ### Methods
  37
  38 ```js
  39 stream.push(/*...*/)         // Emit a chunk
  40 stream.emit('error', error)  // Raise an error
  41 stream.push(null)            // Close a stream
  42 ```
  43
  44 ### Events
  45
  46 ```js
  47 const st = source()
  48 st.on('data', (data) => { console.log('<-', data) })
  49 st.on('error', (err) => { console.log('!', err.message) })
  50 st.on('close', () => { console.log('** bye') })
  51 st.on('finish', () => { console.log('** bye') })
  52 ```
  53
  54 Assuming `source()` is a readable stream.
  55
  56 ### Flowing mode
  57
  58 ```js
  59 // Toggle flowing mode
  60 st.resume()
  61 st.pause()
  62 ```
  63
  64 ```js
  65 // Automatically turns on flowing mode
  66 st.on('data', /*...*/)
  67 ```
  68
  69 Stream types
  70 ------------
  71 {: .-three-column}
  72
  73 ### Readable
  74
  75 ```js
  76 function clock () {
  77   const stream = new Readable({
  78     objectMode: true,
  79     read() {}
  80   })
  81
  82   setInterval(() => {
  83     stream.push({ time: new Date() })
  84   }, 1000)
  85
  86   return stream
  87 }
  88
  89 // Implement read() if you
  90 // need on-demand reading.
  91 ```
  92
  93 Readable streams are generators of data. Write data using `stream.push()`.
  94
  95 ### Transform
  96
  97 ```js
  98 function xformer () {
  99   let count = 0
 100
 101   return new Transform({
 102     objectMode: true,
 103     transform: (data, _, done) => {
 104       done(null, { ...data, index: count++ })
 105     }
 106   })
 107 }
 108 ```
 109
 110 Pass the updated chunk to `done(null, chunk)`.
 111
 112 ### Writable
 113
 114 ```js
 115 function renderer () {
 116   return new Writable({
 117     objectMode: true,
 118     write: (data, _, done) => {
 119       console.log('<-', data)
 120       done()
 121     }
 122   })
 123 }
 124 ```
 125
 126 ### All together now
 127
 128 ```js
 129 clock()              // Readable stream
 130   .pipe(xformer())   // Transform stream
 131   .pipe(renderer())  // Writable stream
 132 ```
 133
 134 ## Also see
 135 {: .-one-column}
 136
 137 - <https://nodejs.org/api/stream.html>
 138 - <https://github.com/substack/stream-handbook>