<!--introduced_in=v0.10.0-->

A stream is an abstract interface for working with streaming data in Node.js.

The `stream` module provides a base API that makes it easy to build objects

that implement the stream interface.

There are many stream objects provided by Node.js. For instance, a

[request to an HTTP server][http-incoming-message] and [`process.stdout`][]

are both stream instances.

Streams can be readable, writable, or both. All streams are instances of

[`EventEmitter`][].

```js

const stream = require('stream');

```

objects will rarely (if ever) have need to use the `stream` module directly.

additional notes. The first section explains the elements of the stream API that

are required to *use* streams within an application. The second section explains

the elements of the API that are required to *implement* new types of streams.

## Types of Streams

There are four fundamental stream types within Node.js:

* [Readable][] - streams from which data can be read (for example

[`fs.createReadStream()`][]).

* [Writable][] - streams to which data can be written (for example

* [Duplex][] - streams that are both Readable and Writable (for example

[`net.Socket`][]).

* [Transform][] - Duplex streams that can modify or transform the data as it

is written and read (for example [`zlib.createDeflate()`][]).

### Object Mode

All streams created by Node.js APIs operate exclusively on strings and `Buffer`

(or `Uint8Array`) objects. It is possible, however, for stream implementations

to work with other types of JavaScript values (with the exception of `null`,

which serves a special purpose within streams). Such streams are considered to

operate in "object mode".

Stream instances are switched into object mode using the `objectMode` option

when the stream is created. Attempting to switch an existing stream into

object mode is not safe.

### Buffering

Both [Writable][] and [Readable][] streams will store data in an internal

buffer that can be retrieved using `writable._writableState.getBuffer()` or

`readable._readableState.buffer`, respectively.

The amount of data potentially buffered depends on the `highWaterMark` option

passed into the streams constructor. For normal streams, the `highWaterMark`

option specifies a [total number of bytes][hwm-gotcha]. For streams operating

in object mode, the `highWaterMark` specifies a total number of objects.

Data is buffered in Readable streams when the implementation calls

[`stream.push(chunk)`][stream-push]. If the consumer of the Stream does not

call [`stream.read()`][stream-read], the data will sit in the internal

queue until it is consumed.

Once the total size of the internal read buffer reaches the threshold specified

by `highWaterMark`, the stream will temporarily stop reading data from the

underlying resource until the data currently buffered can be consumed (that is,

used to fill the read buffer).

Data is buffered in Writable streams when the

[`writable.write(chunk)`][stream-write] method is called repeatedly. While the

total size of the internal write buffer is below the threshold set by

the size of the internal buffer reaches or exceeds the `highWaterMark`, `false`

will be returned.

is to limit the buffering of data to acceptable levels such that sources and

destinations of differing speeds will not overwhelm the available memory.

Because [Duplex][] and [Transform][] streams are both Readable and Writable,

each maintain *two* separate internal buffers used for reading and writing,

allowing each side to operate independently of the other while maintaining an

appropriate and efficient flow of data. For example, [`net.Socket`][] instances

are [Duplex][] streams whose Readable side allows consumption of data received

*from* the socket and whose Writable side allows writing data *to* the socket.

Because data may be written to the socket at a faster or slower rate than data

is received, it is important for each side to operate (and buffer) independently

of the other.

Almost all Node.js applications, no matter how simple, use streams in some

manner. The following is an example of using streams in a Node.js application

that implements an HTTP server:

// req is an http.IncomingMessage, which is a Readable Stream

// res is an http.ServerResponse, which is a Writable Stream

// Get the data as utf8 strings.

// If an encoding is not set, Buffer objects will be received.

req.setEncoding('utf8');

// Readable streams emit 'data' events once a listener is added

// write back something interesting to the user:

res.write(typeof data);

res.end();

});

});

server.listen(1337);

// $ curl localhost:1337 -d "not json"

// error: Unexpected token o in JSON at position 1

```

[Writable][] streams (such as `res` in the example) expose methods such as

`write()` and `end()` that are used to write data onto the stream.

[Readable][] streams use the [`EventEmitter`][] API for notifying application

code when data is available to be read off the stream. That available data can

be read from the stream in multiple ways.

Both [Writable][] and [Readable][] streams use the [`EventEmitter`][] API in

various ways to communicate the current state of the stream.

[Duplex][] and [Transform][] streams are both [Writable][] and [Readable][].

Applications that are either writing data to or consuming data from a stream

are not required to implement the stream interfaces directly and will generally

have no reason to call `require('stream')`.

Developers wishing to implement new types of streams should refer to the

### Writable Streams

Writable streams are an abstraction for a *destination* to which data is

written.

Examples of [Writable][] streams include:

* [HTTP requests, on the client][]

* [HTTP responses, on the server][]

* [fs write streams][]

* [zlib streams][zlib]

* [crypto streams][crypto]

* [TCP sockets][]

* [child process stdin][]

* [`process.stdout`][], [`process.stderr`][]

*Note*: Some of these examples are actually [Duplex][] streams that implement

the [Writable][] interface.

All [Writable][] streams implement the interface defined by the

`stream.Writable` class.

While specific instances of [Writable][] streams may differ in various ways,

all Writable streams follow the same fundamental usage pattern as illustrated

in the example below:

```js

const myStream = getWritableStreamSomehow();

myStream.write('some data');

myStream.write('some more data');

myStream.end('done writing data');

```

<!-- YAML

added: v0.9.4

-->

<!--type=class-->

<!-- YAML

added: v0.9.4

-->

The `'close'` event is emitted when the stream and any of its underlying

resources (a file descriptor, for example) have been closed. The event indicates

that no more events will be emitted, and no further computation will occur.

<!-- YAML

added: v0.9.4

-->

If a call to [`stream.write(chunk)`][stream-write] returns `false`, the

`'drain'` event will be emitted when it is appropriate to resume writing data

to the stream.

```js

// Write the data to the supplied writable stream one million times.

// Be attentive to back-pressure.

function writeOneMillionTimes(writer, data, encoding, callback) {

write();

function write() {

do {

i--;

if (i === 0) {

// last time!

writer.write(data, encoding, callback);

} else {

// see if we should continue, or wait

// don't pass the callback, because we're not done yet.

ok = writer.write(data, encoding);

}

} while (i > 0 && ok);

if (i > 0) {

// had to stop early!

// write some more once it drains

writer.once('drain', write);

}

}

}

```

<!-- YAML

added: v0.9.4

-->

* {Error}

The `'error'` event is emitted if an error occurred while writing or piping

data. The listener callback is passed a single `Error` argument when called.

*Note*: The stream is not closed when the `'error'` event is emitted.

##### Event: 'finish'

<!-- YAML

added: v0.9.4

-->

The `'finish'` event is emitted after the [`stream.end()`][stream-end] method

has been called, and all data has been flushed to the underlying system.

```js

const writer = getWritableStreamSomehow();

}

writer.end('This is the end\n');

writer.on('finish', () => {

console.error('All writes are now complete.');

});

```

##### Event: 'pipe'

<!-- YAML

added: v0.9.4

-->

* `src` {stream.Readable} source stream that is piping to this writable

The `'pipe'` event is emitted when the [`stream.pipe()`][] method is called on

a readable stream, adding this writable to its set of destinations.

```js

const writer = getWritableStreamSomehow();

const reader = getReadableStreamSomehow();

writer.on('pipe', (src) => {

console.error('something is piping into the writer');

assert.equal(src, reader);

});

reader.pipe(writer);

```

##### Event: 'unpipe'

<!-- YAML

added: v0.9.4

-->

* `src` {[Readable][] Stream} The source stream that

[unpiped][`stream.unpipe()`] this writable

The `'unpipe'` event is emitted when the [`stream.unpipe()`][] method is called

on a [Readable][] stream, removing this [Writable][] from its set of

destinations.

```js

const writer = getWritableStreamSomehow();

const reader = getReadableStreamSomehow();

writer.on('unpipe', (src) => {

console.error('Something has stopped piping into the writer.');

assert.equal(src, reader);

});

reader.pipe(writer);

reader.unpipe(writer);

```

##### writable.cork()

<!-- YAML

added: v0.11.2

-->

The `writable.cork()` method forces all written data to be buffered in memory.

The buffered data will be flushed when either the [`stream.uncork()`][] or

[`stream.end()`][stream-end] methods are called.

The primary intent of `writable.cork()` is to avoid a situation where writing

buffered writes in a more optimized manner.

See also: [`writable.uncork()`][].

<!-- YAML

added: v0.9.4

pr-url: https://github.com/nodejs/node/pull/11608

description: The `chunk` argument can now be a `Uint8Array` instance.

* `chunk` {string|Buffer|Uint8Array|any} Optional data to write. For streams

not operating in object mode, `chunk` must be a string, `Buffer` or

`Uint8Array`. For object mode streams, `chunk` may be any JavaScript value

other than `null`.

* `encoding` {string} The encoding, if `chunk` is a string

* `callback` {Function} Optional callback for when the stream is finished

Calling the `writable.end()` method signals that no more data will be written

to the [Writable][]. The optional `chunk` and `encoding` arguments allow one

final additional chunk of data to be written immediately before closing the

stream. If provided, the optional `callback` function is attached as a listener

for the [`'finish'`][] event.

Calling the [`stream.write()`][stream-write] method after calling

[`stream.end()`][stream-end] will raise an error.

```js

// write 'hello, ' and then end with 'world!'

const file = fs.createWriteStream('example.txt');

file.write('hello, ');

file.end('world!');

// writing more now is not allowed!

```

##### writable.setDefaultEncoding(encoding)

<!-- YAML

added: v0.11.15

changes:

- version: v6.1.0

pr-url: https://github.com/nodejs/node/pull/5040

description: This method now returns a reference to `writable`.

The `writable.setDefaultEncoding()` method sets the default `encoding` for a

[Writable][] stream.

##### writable.uncork()

<!-- YAML

added: v0.11.2

-->

The `writable.uncork()` method flushes all data buffered since

[`stream.cork()`][] was called.

of writes to a stream, it is recommended that calls to `writable.uncork()` be

deferred using `process.nextTick()`. Doing so allows batching of all

`writable.write()` calls that occur within a given Node.js event loop phase.

```js

stream.cork();

stream.write('some ');

stream.write('data ');

process.nextTick(() => stream.uncork());

```

number of calls to `writable.uncork()` must be called to flush the buffered

data.

stream.cork();

stream.write('some ');

stream.cork();

stream.write('data ');

process.nextTick(() => {

stream.uncork();

// The data will not be flushed until uncork() is called a second time.

stream.uncork();

});

```

See also: [`writable.cork()`][].

<!-- YAML

added: v0.9.4

pr-url: https://github.com/nodejs/node/pull/11608

description: The `chunk` argument can now be a `Uint8Array` instance.

- version: v6.0.0

pr-url: https://github.com/nodejs/node/pull/6170

description: Passing `null` as the `chunk` parameter will always be

considered invalid now, even in object mode.

* `chunk` {string|Buffer|Uint8Array|any} Optional data to write. For streams

not operating in object mode, `chunk` must be a string, `Buffer` or

`Uint8Array`. For object mode streams, `chunk` may be any JavaScript value

other than `null`.

* `encoding` {string} The encoding, if `chunk` is a string

wait for the `'drain'` event to be emitted before continuing to write

additional data; otherwise `true`.

The `writable.write()` method writes some data to the stream, and calls the

supplied `callback` once the data has been fully handled. If an error

occurs, the `callback` *may or may not* be called with the error as its

first argument. To reliably detect write errors, add a listener for the

`'error'` event.

`highWaterMark` configured when the stream was created after admitting `chunk`.

If `false` is returned, further attempts to write data to the stream should

stop until the [`'drain'`][] event is emitted.

While a stream is not draining, calls to `write()` will buffer `chunk`, and

return false. Once all currently buffered chunks are drained (accepted for

delivery by the operating system), the `'drain'` event will be emitted.

It is recommended that once write() returns false, no more chunks be written

until the `'drain'` event is emitted. While calling `write()` on a stream that

is not draining is allowed, Node.js will buffer all written chunks until

maximum memory usage occurs, at which point it will abort unconditionally.

Even before it aborts, high memory usage will cause poor garbage collector

performance and high RSS (which is not typically released back to the system,

even after the memory is no longer required). Since TCP sockets may never

drain if the remote peer does not read the data, writing a socket that is

not draining may lead to a remotely exploitable vulnerability.

Writing data while the stream is not draining is particularly

problematic for a [Transform][], because the `Transform` streams are paused

by default until they are piped or an `'data'` or `'readable'` event handler

is added.

If the data to be written can be generated or fetched on demand, it is

recommended to encapsulate the logic into a [Readable][] and use

[`stream.pipe()`][]. However, if calling `write()` is preferred, it is

possible to respect backpressure and avoid memory issues using the

```js

}

}

// Wait for cb to be called before doing any other write.

write('hello', () => {

console.log('write completed, do more writes now');

});

A Writable stream in object mode will always ignore the `encoding` argument.