Is true after
readable.destroy() has been called.
Is true if it is safe to call
readable.read(), which means the stream has not
been destroyed or emitted 'error' or
'end'.
Returns whether the stream was destroyed or errored before
emitting 'end'.
Returns whether 'data' has been
emitted.
Getter for the property encoding of a given
Readable stream. The
encodingproperty can be set using the
readable.setEncoding() method.
Becomes true when
'end' event is emitted.
This property reflects the current state of a
Readable stream as described in the
Three states section.
Returns the value of highWaterMark passed when
creating this Readable.
This property contains the number of bytes (or objects) in
the queue ready to be read. The value provides introspection
data regarding the status of the highWaterMark.
Getter for the property objectMode of a given
Readable stream.
Sets or gets the default captureRejection value for all emitters.
This symbol shall be used to install a listener for only
monitoring 'error'
events. Listeners installed using this symbol are called
before the regular
'error' listeners are called.
Installing a listener using this symbol does not change the
behavior once an 'error' event is
emitted, therefore the process will still crash if no
regular 'error' listener is installed.
Event emitter The defined events on documents including:
Destroy the stream. Optionally emit an
'error' event, and emit a
'close'event (unless
emitClose is set to false).
After this call, the readable stream will release any
internal resources and subsequent calls to
push()will be ignored.
Once destroy() has been called any further
calls will be a no-op and no further errors except from
_destroy() may be emitted as
'error'.
Implementors should not override this method, but
instead implement readable._destroy().
Error which will be passed as payload in
'error' event
Returns an array listing the events for which the
emitter has registered listeners. The values in the
array are strings or Symbols.
const EventEmitter = require('events');
const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});
const sym = Symbol('symbol');
myEE.on(sym, () => {});
console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
Returns the current max listener value for the
EventEmitter which is either set by
emitter.setMaxListeners(n) or defaults to
defaultMaxListeners.
The readable.isPaused() method returns the
current operating state of theReadable.
This is used primarily by the mechanism that underlies
thereadable.pipe() method. In most typical
cases, there will be no reason to use this method
directly.
const readable = new stream.Readable();
readable.isPaused(); // === false
readable.pause();
readable.isPaused(); // === true
readable.resume();
readable.isPaused(); // === false
Returns the number of listeners listening to the event
named eventName.
The name of the event being listened for
Returns a copy of the array of listeners for the event
named eventName.
server.on('connection', (stream) => {
console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]
Alias for emitter.removeListener().
The readable.pause() method will cause a
stream in flowing mode to stop emitting
'data' events, switching out of
flowing mode. Any data that becomes available will
remain in the internal buffer.
const readable = getReadableStreamSomehow();
readable.on('data', (chunk) => {
console.log(`Received ${chunk.length} bytes of data.`);
readable.pause();
console.log('There will be no additional data for 1 second.');
setTimeout(() => {
console.log('Now data will start flowing again.');
readable.resume();
}, 1000);
});
The readable.pause() method has no effect
if there is a 'readable'event
listener.
Returns a copy of the array of listeners for the event
named eventName, including any wrappers
(such as those created by .once()).
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));
// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];
// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();
// Logs "log once" to the console and removes the listener
logFnWrapper();
emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');
// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');
The readable.read() method pulls some data
out of the internal buffer and returns it. If no data
available to be read, null is returned. By
default, the data will be returned as a
Buffer object unless an encoding has been
specified using the
readable.setEncoding() method or the stream
is operating in object mode.
The optional size argument specifies a
specific number of bytes to read. Ifsize
bytes are not available to be read,
null will be returned _unless_the stream
has ended, in which case all of the data remaining in
the internal buffer will be returned.
If the size argument is not specified, all
of the data contained in the internal buffer will be
returned.
The size argument must be less than or
equal to 1 GiB.
The readable.read() method should only be
called on Readable streams operating in
paused mode. In flowing mode,
readable.read() is called automatically
until the internal buffer is fully drained.
const readable = getReadableStreamSomehow();
// 'readable' may be triggered multiple times as data is buffered in
readable.on('readable', () => {
let chunk;
console.log('Stream is readable (new data received in buffer)');
// Use a loop to make sure we read all currently available data
while (null !== (chunk = readable.read())) {
console.log(`Read ${chunk.length} bytes of data...`);
}
});
// 'end' will be triggered once when there is no more data available
readable.on('end', () => {
console.log('Reached end of stream.');
});
Each call to readable.read() returns a
chunk of data, or null. The chunks are not
concatenated. A while loop is necessary to
consume all data currently in the buffer. When reading a
large file .read() may return
null, having consumed all buffered content
so far, but there is still more data to come not yet
buffered. In this case a new
'readable' event will be emitted
when there is more data in the buffer. Finally the
'end' event will be emitted when
there is no more data to come.
Therefore to read a file's whole contents from a
readable, it is necessary to collect chunks
across multiple 'readable' events:
const chunks = [];
readable.on('readable', () => {
let chunk;
while (null !== (chunk = readable.read())) {
chunks.push(chunk);
}
});
readable.on('end', () => {
const content = chunks.join('');
});
A Readable stream in object mode will
always return a single item from a call to
readable.read(size), regardless of the
value of thesize argument.
If the readable.read() method returns a
chunk of data, a 'data' event will
also be emitted.
Calling read after
the 'end' event has been emitted
will return null. No runtime error will be
raised.
Optional argument to specify how much data to read.
Removes all listeners, or those of the specified
eventName.
It is bad practice to remove listeners added elsewhere
in the code, particularly when the
EventEmitter instance was created by some
other component or module (e.g. sockets or file
streams).
Returns a reference to the EventEmitter, so
that calls can be chained.
The readable.resume() method causes an
explicitly paused Readable stream to resume
emitting 'data' events, switching
the stream into flowing mode.
The readable.resume() method can be used to
fully consume the data from a stream without actually
processing any of that data:
getReadableStreamSomehow()
.resume()
.on('end', () => {
console.log('Reached the end, but did not read anything.');
});
The readable.resume() method has no effect
if there is a 'readable'event
listener.
The readable.setEncoding() method sets the
character encoding for data read from the
Readable stream.
By default, no encoding is assigned and stream data will
be returned asBuffer objects. Setting an
encoding causes the stream data to be returned as
strings of the specified encoding rather than as
Bufferobjects. For instance, calling
readable.setEncoding('utf8') will
cause the output data to be interpreted as UTF-8 data,
and passed as strings. Callingreadable.setEncoding('hex')
will cause the data to be encoded in hexadecimal string
format.
The Readable stream will properly handle
multi-byte characters delivered through the stream that
would otherwise become improperly decoded if simply
pulled from the stream as Buffer objects.
const readable = getReadableStreamSomehow();
readable.setEncoding('utf8');
readable.on('data', (chunk) => {
assert.equal(typeof chunk, 'string');
console.log('Got %d characters of string data:', chunk.length);
});
The encoding to use.
By default EventEmitters will print a
warning if more than 10 listeners are added
for a particular event. This is a useful default that
helps finding memory leaks. The
emitter.setMaxListeners() method allows the
limit to be modified for this specific
EventEmitter instance. The value can be set
toInfinity (or 0) to indicate
an unlimited number of listeners.
Returns a reference to the EventEmitter, so
that calls can be chained.
The readable.unpipe() method detaches a
Writable stream previously attached using
the pipe method.
If the destination is not specified, then
all pipes are detached.
If the destination is specified, but no
pipe is set up for it, then the method does nothing.
const fs = require('fs');
const readable = getReadableStreamSomehow();
const writable = fs.createWriteStream('file.txt');
// All the data from readable goes into 'file.txt',
// but only for the first second.
readable.pipe(writable);
setTimeout(() => {
console.log('Stop writing to file.txt.');
readable.unpipe(writable);
console.log('Manually close the file stream.');
writable.end();
}, 1000);
Optional specific stream to unpipe
Passing chunk as null signals
the end of the stream (EOF) and behaves the same as
readable.push(null), after which no more
data can be written. The EOF signal is put at the end of
the buffer and any buffered data will still be flushed.
The readable.unshift() method pushes a
chunk of data back into the internal buffer. This is
useful in certain situations where a stream is being
consumed by code that needs to "un-consume"
some amount of data that it has optimistically pulled
out of the source, so that the data can be passed on to
some other party.
The stream.unshift(chunk) method cannot be
called after the 'end' event has
been emitted or a runtime error will be thrown.
Developers using stream.unshift() often
should consider switching to use of a
Transform stream instead. See the
API for stream implementers section for
more information.
// Pull off a header delimited by \n\n.
// Use unshift() if we get too much.
// Call the callback with (error, header, stream).
const { StringDecoder } = require('string_decoder');
function parseHeader(stream, callback) {
stream.on('error', callback);
stream.on('readable', onReadable);
const decoder = new StringDecoder('utf8');
let header = '';
function onReadable() {
let chunk;
while (null !== (chunk = stream.read())) {
const str = decoder.write(chunk);
if (str.match(/\n\n/)) {
// Found the header boundary.
const split = str.split(/\n\n/);
header += split.shift();
const remaining = split.join('\n\n');
const buf = Buffer.from(remaining, 'utf8');
stream.removeListener('error', callback);
// Remove the 'readable' listener before unshifting.
stream.removeListener('readable', onReadable);
if (buf.length)
stream.unshift(buf);
// Now the body of the message can be read from the stream.
callback(null, header, stream);
} else {
// Still reading the header.
header += str;
}
}
}
}
Unlike push,
stream.unshift(chunk) will not end the
reading process by resetting the internal reading state
of the stream. This can cause unexpected results if
readable.unshift() is called during a read
(i.e. from within a
_read implementation
on a custom stream). Following the call to
readable.unshift() with an immediate
push will reset the
reading state appropriately, however it is best to
simply avoid calling
readable.unshift() while in the process of
performing a read.
Chunk of data to unshift onto the read queue. For
streams not operating in object mode,
chunk must be a string,
Buffer, Uint8Array or
null. For object mode streams,
chunk may be any JavaScript value.
Encoding of string chunks. Must be a valid
Buffer encoding, such as
'utf8' or
'ascii'.
Prior to Node.js 0.10, streams did not implement the
entire stream module API as it is currently
defined. (See Compatibility for more
information.)
When using an older Node.js library that emits
'data' events and has a
pause method that is
advisory only, thereadable.wrap() method
can be used to create a Readable stream
that uses the old stream as its data source.
It will rarely be necessary to use
readable.wrap() but the method has been
provided as a convenience for interacting with older
Node.js applications and libraries.
const { OldReader } = require('./old-api-module.js');
const { Readable } = require('stream');
const oreader = new OldReader();
const myReader = new Readable().wrap(oreader);
myReader.on('readable', () => {
myReader.read(); // etc.
});
An "old style" readable stream
A utility method for creating duplex streams.
Stream converts writable stream into
writable Duplex and readable stream to
Duplex.
Blob converts into readable
Duplex.
string converts into readable
Duplex.
ArrayBuffer converts into readable
Duplex.
AsyncIterable converts into a readable
Duplex. Cannot yield null.
AsyncGeneratorFunction converts into a
readable/writable transform Duplex. Must
take a source AsyncIterable as first
parameter. Cannot yield null.
AsyncFunction converts into a writable
Duplex. Must return either
null or undefined
Object ({ writable, readable }) converts
readable and writable into
Stream and then combines them into
Duplex where the Duplex will
write to the writable and read from the
readable.
Promise converts into readable
Duplex. Value null is
ignored.
Returns a copy of the array of listeners for the event
named eventName.
For EventEmitters this behaves exactly the
same as calling .listeners on the emitter.
For EventTargets this is the only way to
get the event listeners for the event target. This is
useful for debugging and diagnostic purposes.
const { getEventListeners, EventEmitter } = require('events');
{
const ee = new EventEmitter();
const listener = () => console.log('Events are fun');
ee.on('foo', listener);
getEventListeners(ee, 'foo'); // [listener]
}
{
const et = new EventTarget();
const listener = () => console.log('Events are fun');
et.addEventListener('foo', listener);
getEventListeners(et, 'foo'); // [listener]
}
Returns whether the stream has been read from or cancelled.
A class method that returns the number of listeners for
the given eventNameregistered on the given
emitter.
const { EventEmitter, listenerCount } = require('events');
const myEmitter = new EventEmitter();
myEmitter.on('event', () => {});
myEmitter.on('event', () => {});
console.log(listenerCount(myEmitter, 'event'));
// Prints: 2
The emitter to query
The event name
```js const { on, EventEmitter } = require('events');
(async () => { const ee = new EventEmitter();
// Emit later on process.nextTick(() => { ee.emit('foo', 'bar'); ee.emit('foo', 42); });
for await (const event of on(ee, 'foo')) { // The execution of this inner block is synchronous and it // processes one event at a time (even with await). Do not use // if concurrent execution is required. console.log(event); // prints ['bar'] [42] } // Unreachable here })();
Returns an `AsyncIterator` that iterates `eventName` events. It will throw
if the `EventEmitter` emits `'error'`. It removes all listeners when
exiting the loop. The `value` returned by each iteration is an array
composed of the emitted event arguments.
An `AbortSignal` can be used to cancel waiting on events:
```js
const { on, EventEmitter } = require('events');
const ac = new AbortController();
(async () => {
const ee = new EventEmitter();
// Emit later on
process.nextTick(() => {
ee.emit('foo', 'bar');
ee.emit('foo', 42);
});
for await (const event of on(ee, 'foo', { signal: ac.signal })) {
// The execution of this inner block is synchronous and it
// processes one event at a time (even with await). Do not use
// if concurrent execution is required.
console.log(event); // prints ['bar'] [42]
}
// Unreachable here
})();
process.nextTick(() => ac.abort());
The name of the event being listened for
that iterates eventName events emitted by the
emitter
Creates a Promise that is fulfilled when
the EventEmitter emits the given event or
that is rejected if the EventEmitter emits
'error' while waiting. The
Promise will resolve with an array of all
the arguments emitted to the given event.
This method is intentionally generic and works with the
web platform
EventTarget
interface, which has no special'error'
event semantics and does not listen to the
'error' event.
const { once, EventEmitter } = require('events');
async function run() {
const ee = new EventEmitter();
process.nextTick(() => {
ee.emit('myevent', 42);
});
const [value] = await once(ee, 'myevent');
console.log(value);
const err = new Error('kaboom');
process.nextTick(() => {
ee.emit('error', err);
});
try {
await once(ee, 'myevent');
} catch (err) {
console.log('error happened', err);
}
}
run();
The special handling of the
'error' event is only used when
events.once()is used to wait for another
event. If events.once() is used to wait for
the 'error' event itself, then it
is treated as any other kind of event without special
handling:
const { EventEmitter, once } = require('events');
const ee = new EventEmitter();
once(ee, 'error')
.then(([err]) => console.log('ok', err.message))
.catch((err) => console.log('error', err.message));
ee.emit('error', new Error('boom'));
// Prints: ok boom
An AbortSignal can be used to cancel
waiting for the event:
const { EventEmitter, once } = require('events');
const ee = new EventEmitter();
const ac = new AbortController();
async function foo(emitter, event, signal) {
try {
await once(emitter, event, { signal });
console.log('event emitted!');
} catch (error) {
if (error.name === 'AbortError') {
console.error('Waiting for the event was canceled!');
} else {
console.error('There was an error', error.message);
}
}
}
foo(ee, 'foo', ac.signal);
ac.abort(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!
If
falsethen the stream will automatically end the writable side when the readable side ends. Set initially by theallowHalfOpenconstructor option, which defaults tofalse.This can be changed manually to change the half-open behavior of an existing
Duplexstream instance, but must be changed before the'end'event is emitted.v0.9.4