doc/api/stream.markdown

   1 # Stream
   2
   3     Stability: 2 - Unstable
   4
   5 A stream is an abstract interface implemented by various objects in Node.
   6 For example a request to an HTTP server is a stream, as is stdout. Streams
   7 are readable, writable, or both. All streams are instances of `EventEmitter`.
   8
   9 You can load up the Stream base class by doing `require('stream')`.
  10
  11 ## Readable Stream
  12
  13 <!--type=class-->
  14
  15 A `Readable Stream` has the following methods, members, and events.
  16
  17 ### Event: 'data'
  18
  19 `function (data) { }`
  20
  21 The `'data'` event emits either a `Buffer` (by default) or a string if
  22 `setEncoding()` was used.
  23
  24 Note that the __data will be lost__ if there is no listener when a
  25 `Readable Stream` emits a `'data'` event.
  26
  27 ### Event: 'end'
  28
  29 `function () { }`
  30
  31 Emitted when the stream has received an EOF (FIN in TCP terminology).
  32 Indicates that no more `'data'` events will happen. If the stream is also
  33 writable, it may be possible to continue writing.
  34
  35 ### Event: 'error'
  36
  37 `function (exception) { }`
  38
  39 Emitted if there was an error receiving data.
  40
  41 ### Event: 'close'
  42
  43 `function () { }`
  44
  45 Emitted when the underlying file descriptor has been closed. Not all streams
  46 will emit this.  (For example, an incoming HTTP request will not emit
  47 `'close'`.)
  48
  49 ### stream.readable
  50
  51 A boolean that is `true` by default, but turns `false` after an `'error'`
  52 occurred, the stream came to an `'end'`, or `destroy()` was called.
  53
  54 ### stream.setEncoding([encoding])
  55
  56 Makes the `'data'` event emit a string instead of a `Buffer`. `encoding` can be
  57 `'utf8'`, `'utf16le'` (`'ucs2'`), `'ascii'`, or `'hex'`. Defaults to `'utf8'`.
  58
  59 ### stream.pause()
  60
  61 Issues an advisory signal to the underlying communication layer, requesting
  62 that no further data be sent until `resume()` is called.
  63
  64 Note that, due to the advisory nature, certain streams will not be paused
  65 immediately, and so `'data'` events may be emitted for some indeterminate
  66 period of time even after `pause()` is called. You may wish to buffer such
  67 `'data'` events.
  68
  69 ### stream.resume()
  70
  71 Resumes the incoming `'data'` events after a `pause()`.
  72
  73 ### stream.destroy()
  74
  75 Closes the underlying file descriptor. Stream will not emit any more events.
  76
  77 ### stream.pipe(destination, [options])
  78
  79 This is a `Stream.prototype` method available on all `Stream`s.
  80
  81 Connects this read stream to `destination` WriteStream. Incoming
  82 data on this stream gets written to `destination`. The destination and source
  83 streams are kept in sync by pausing and resuming as necessary.
  84
  85 This function returns the `destination` stream.
  86
  87 Emulating the Unix `cat` command:
  88
  89     process.stdin.resume();
  90     process.stdin.pipe(process.stdout);
  91
  92
  93 By default `end()` is called on the destination when the source stream emits
  94 `end`, so that `destination` is no longer writable. Pass `{ end: false }` as
  95 `options` to keep the destination stream open.
  96
  97 This keeps `process.stdout` open so that "Goodbye" can be written at the end.
  98
  99     process.stdin.resume();
 100
 101     process.stdin.pipe(process.stdout, { end: false });
 102
 103     process.stdin.on("end", function() {
 104       process.stdout.write("Goodbye\n");
 105     });
 106
 107
 108 ## Writable Stream
 109
 110 <!--type=class-->
 111
 112 A `Writable Stream` has the following methods, members, and events.
 113
 114 ### Event: 'drain'
 115
 116 `function () { }`
 117
 118 After a `write()` method returned `false`, this event is emitted to
 119 indicate that it is safe to write again.
 120
 121 ### Event: 'error'
 122
 123 `function (exception) { }`
 124
 125 Emitted on error with the exception `exception`.
 126
 127 ### Event: 'close'
 128
 129 `function () { }`
 130
 131 Emitted when the underlying file descriptor has been closed.
 132
 133 ### Event: 'pipe'
 134
 135 `function (src) { }`
 136
 137 Emitted when the stream is passed to a readable stream's pipe method.
 138
 139 ### stream.writable
 140
 141 A boolean that is `true` by default, but turns `false` after an `'error'`
 142 occurred or `end()` / `destroy()` was called.
 143
 144 ### stream.write(string, [encoding], [fd])
 145
 146 Writes `string` with the given `encoding` to the stream.  Returns `true` if
 147 the string has been flushed to the kernel buffer.  Returns `false` to
 148 indicate that the kernel buffer is full, and the data will be sent out in
 149 the future. The `'drain'` event will indicate when the kernel buffer is
 150 empty again. The `encoding` defaults to `'utf8'`.
 151
 152 If the optional `fd` parameter is specified, it is interpreted as an integral
 153 file descriptor to be sent over the stream. This is only supported for UNIX
 154 streams, and is silently ignored otherwise. When writing a file descriptor in
 155 this manner, closing the descriptor before the stream drains risks sending an
 156 invalid (closed) FD.
 157
 158 ### stream.write(buffer)
 159
 160 Same as the above except with a raw buffer.
 161
 162 ### stream.end()
 163
 164 Terminates the stream with EOF or FIN.
 165 This call will allow queued write data to be sent before closing the stream.
 166
 167 ### stream.end(string, encoding)
 168
 169 Sends `string` with the given `encoding` and terminates the stream with EOF
 170 or FIN. This is useful to reduce the number of packets sent.
 171
 172 ### stream.end(buffer)
 173
 174 Same as above but with a `buffer`.
 175
 176 ### stream.destroy()
 177
 178 Closes the underlying file descriptor. Stream will not emit any more events.
 179 Any queued write data will not be sent.
 180
 181 ### stream.destroySoon()
 182
 183 After the write queue is drained, close the file descriptor. `destroySoon()`
 184 can still destroy straight away, as long as there is no data left in the queue
 185 for writes.