<!--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');

```

While it is important to understand how streams work, the `stream` module itself

is most useful for developers that are creating new types of stream instances.

Developers who are primarily *consuming* stream objects will rarely 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:

Additionally this module includes the utility functions [pipeline][] and

[finished][].

### 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

buffer that can be retrieved using `writable.writableBuffer` or

`readable.readableBuffer`, respectively.

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

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

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

[`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).

[`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

```

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

be read from the stream in multiple ways.

[`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.

* [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`][]

Some of these examples are actually [`Duplex`][] streams that implement the

[`Writable`][] interface.

`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.

##### 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

-->

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

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

destinations.

This is also emitted in case this [`Writable`][] stream emits an error when a

[`Readable`][] stream pipes into it.

```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()`][].

##### writable.destroy([error])

<!-- YAML

added: v8.0.0

-->

* Returns: {this}

<!-- YAML

added: v0.9.4

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

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

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

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

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.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());

```