Private
Optional
#cookies
Readonly
closed
v18.0.0
Readonly
connection
Alias of outgoingMessage.socket.
v0.3.0
Since v15.12.0,v14.17.1 - Use socket instead.
Is true after writable.destroy() has
been called.
v8.0.0
Readonly
errored
Returns error if the stream has been destroyed with an error.
v18.0.0
Use writableEnded instead.
Readonly
headers
Read-only. true if the headers were sent, otherwise
false.
v0.9.3
Readonly
req
Readonly
socket
Reference to the underlying socket. Usually, users will not want to access this property.
After calling outgoingMessage.end(), this property
will be nulled.
v0.3.0
When using implicit headers (not calling
response.writeHead() explicitly), this property
controls the status code that will be sent to the client when
the headers get flushed.
response.statusCode = 404;
After response header was sent to the client, this property indicates the status code which was sent out.
v0.4.0
When using implicit headers (not calling
response.writeHead() explicitly), this property
controls the status message that will be sent to the client when
the headers get flushed. If this is left as
undefined then the standard message for the status
code will be used.
response.statusMessage = 'Not found';
After response header was sent to the client, this property indicates the status message which was sent out.
v0.11.8
If set to true, Node.js will check whether the
Content-Lengthheader value and the size of the
body, in bytes, are equal. Mismatching the
Content-Length header value will result in an
Error being thrown, identified by
code:``'ERR_HTTP_CONTENT_LENGTH_MISMATCH'.
v18.10.0, v16.18.0
Readonly
writable
Is true if it is safe to call
writable.write(), which means the stream has not
been destroyed, errored, or ended.
v11.4.0
Readonly
writable
Number of times writable.uncork() needs to be
called in order to fully uncork the stream.
v13.2.0, v12.16.0
Readonly
writable
Is true after writable.end() has been
called. This property does not indicate whether the data has
been flushed, for this use
writable.writableFinished instead.
v12.9.0
Readonly
writable
Is set to true immediately before the
'finish' event is emitted.
v12.6.0
Readonly
writable
Return the value of highWaterMark passed when
creating this Writable.
v9.3.0
Readonly
writable
This property contains the number of bytes (or objects) in the
queue ready to be written. The value provides introspection data
regarding the status of the highWaterMark.
v9.4.0
Readonly
writable
Is true if the stream's buffer has been full
and stream will emit 'drain'.
v15.2.0, v14.17.0
Readonly
writable
Getter for the property objectMode of a given
Writable stream.
v12.3.0
Static
Readonly
captureValue: Symbol.for('nodejs.rejection')
See how to write a custom rejection handler.
v13.4.0, v12.16.0
Static
captureValue: boolean
Change the default captureRejections option on all
new EventEmitter objects.
v13.4.0, v12.16.0
Static
default
By default, a maximum of 10 listeners can be
registered for any single event. This limit can be changed for
individual EventEmitter instances using the
emitter.setMaxListeners(n) method. To change the
default for allEventEmitter instances, the
events.defaultMaxListenersproperty can be used. If
this value is not a positive number, a RangeErroris
thrown.
Take caution when setting the
events.defaultMaxListeners because the change
affects allEventEmitter instances,
including those created before the change is made. However,
calling emitter.setMaxListeners(n) still has
precedence over events.defaultMaxListeners.
This is not a hard limit. The EventEmitter instance
will allow more listeners to be added but will output a trace
warning to stderr indicating that a "possible EventEmitter
memory leak" has been detected. For any
singleEventEmitter, the
emitter.getMaxListeners() and
emitter.setMaxListeners()methods can be used to
temporarily avoid this warning:
import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
// do stuff
emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});
The --trace-warnings command-line flag can be used
to display the stack trace for such warnings.
The emitted warning can be inspected with
process.on('warning') and will have the
additional emitter, type, and
count properties, referring to the event emitter
instance, the event's name and the number of attached
listeners, respectively. Its name property is set
to 'MaxListenersExceededWarning'.
v0.11.2
Static
Readonly
error
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.
v13.6.0, v12.17.0
Optional
[captureRest
...args:
AnyRest
Optional
_construct
Optional
_writev
Event emitter The defined events on documents including:
Rest
...args:
any[]
Adds HTTP trailers (headers but at the end of the message) to the message.
Trailers will only be emitted if the message is chunked encoded. If not, the trailers will be silently discarded.
HTTP requires the Trailer header to be sent to
emit trailers, with a list of header field names in its
value, e.g.
message.writeHead(200, { 'Content-Type': 'text/plain',
'Trailer': 'Content-MD5' });
message.write(fileData);
message.addTrailers({ 'Content-MD5': '7895bf4b8828b55ceaf47747b4bca667' });
message.end();
Attempting to set a header field name or value that contains
invalid characters will result in a
TypeError being thrown.
v0.3.0
Append a single header value for the header object.
If the value is an array, this is equivalent of calling this method multiple times.
If there were no previous value for the header, this is
equivalent of calling
outgoingMessage.setHeader(name, value).
Depending of the value of
options.uniqueHeaders when the client request
or the server were created, this will end up in the header
being sent multiple times or a single time with values
joined using ; .
Header name
Header value
v18.3.0, v16.17.0
The writable.cork() method forces all written
data to be buffered in memory. The buffered data will be
flushed when either the
uncork
or
end
methods are called.
The primary intent of writable.cork() is to
accommodate a situation in which several small chunks are
written to the stream in rapid succession. Instead of
immediately forwarding them to the underlying destination,
writable.cork()buffers all the chunks until
writable.uncork() is called, which will pass
them all to writable._writev(), if present.
This prevents a head-of-line blocking situation where data
is being buffered while waiting for the first small chunk to
be processed. However, use of
writable.cork() without implementingwritable._writev()
may have an adverse effect on throughput.
See also: writable.uncork(),
writable._writev().
v0.11.2
Destroy the stream. Optionally emit an
'error' event, and emit a
'close'event (unless
emitClose is set to false). After
this call, the writable stream has ended and subsequent
calls to write() or end() will
result in an ERR_STREAM_DESTROYED error. This
is a destructive and immediate way to destroy a stream.
Previous calls towrite() may not have drained,
and may trigger an ERR_STREAM_DESTROYED error.
Use end() instead of destroy if data should
flush before close, or wait for the
'drain' event before destroying the
stream.
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 writable._destroy().
Optional
error:
Error
Optional, an error to emit with
'error' event.
v8.0.0
Rest
...args:
any[]
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.
Calling the write method after calling end will raise an error.
// Write 'hello, ' and then end with 'world!'.
const fs = require('node:fs');
const file = fs.createWriteStream('example.txt');
file.write('hello, ');
file.end('world!');
// Writing more now is not allowed!
Optional
cb:
(() => void)
v0.9.4
Optional
cb:
(() => void)
Optional
cb:
(() => void)
Returns an array listing the events for which the emitter
has registered listeners. The values in the array are
strings or Symbols.
import { EventEmitter } from 'node: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) ]
v6.0.0
Flushes the message headers.
For efficiency reason, Node.js normally buffers the message
headers until outgoingMessage.end() is called
or the first chunk of message data is written. It then tries
to pack the headers and data into a single TCP packet.
It is usually desired (it saves a TCP round-trip), but not
when the first data is not sent until possibly much later.
outgoingMessage.flushHeaders()bypasses the
optimization and kickstarts the message.
v1.6.0
Returns a shallow copy of the current outgoing headers. Since a shallow copy is used, array values may be mutated without additional calls to various header-related HTTP module methods. The keys of the returned object are the header names and the values are the respective header values. All header names are lowercase.
The object returned by the
outgoingMessage.getHeaders() method does not
prototypically inherit from the JavaScript
Object. This means that typical
Object methods such as
obj.toString(),
obj.hasOwnProperty(), and others are not
defined and will not work.
outgoingMessage.setHeader('Foo', 'bar');
outgoingMessage.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']);
const headers = outgoingMessage.getHeaders();
// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }
v7.7.0
Returns the current max listener value for the
EventEmitter which is either set by
emitter.setMaxListeners(n) or defaults to
defaultMaxListeners.
v1.0.0
Returns the number of listeners listening for the event
named eventName. If listener is
provided, it will return how many times the listener is
found in the list of the listeners of the event.
The name of the event being listened for
Optional
listener:
Function
The event handler function
v3.2.0
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] ]
v0.1.26
Alias for emitter.removeListener().
Rest
...args:
any[]
v10.0.0
Rest
...args:
any[]
Rest
...args:
any[]
Rest
...args:
any[]
Rest
...args:
any[]
Returns a copy of the array of listeners for the event named
eventName, including any wrappers (such as
those created by .once()).
import { EventEmitter } from 'node:events';
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');
v9.4.0
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.
Optional
eventName:
string | symbol
v0.1.26
Rest
...args:
any[]
Set headers
Sets a single header value. If the header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings to send multiple headers with the same name.
Header name
Header value
v0.4.0
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.
v0.3.5
Once a socket is associated with the message and is
connected,socket.setTimeout() will be called
with msecs as the first parameter.
Optional
callback:
(() => void)
Optional function to be called when a timeout occurs.
Same as binding to the timeout event.
v0.9.12
The writable.uncork() method flushes all data
buffered since
cork
was called.
When using writable.cork() and
writable.uncork() to manage the buffering of
writes to a stream, defer calls to
writable.uncork()
usingprocess.nextTick(). Doing so allows
batching of allwritable.write() calls that
occur within a given Node.js event loop phase.
stream.cork();
stream.write('some ');
stream.write('data ');
process.nextTick(() => stream.uncork());
If the writable.cork() method is called
multiple times on a stream, the same 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().
v0.11.2
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 will be called
with the error as its first argument. The
callback is called asynchronously and before
'error' is emitted.
The return value is true if the internal buffer
is less than thehighWaterMark 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. Once
write() returns false, do not write more chunks
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 a
'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
pipe. However, if calling write() is preferred, it
is possible to respect backpressure and avoid memory issues
using the 'drain' event:
function write(data, cb) {
if (!stream.write(data)) {
stream.once('drain', cb);
} else {
process.nextTick(cb);
}
}
// 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.
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.
Optional
callback:
((error) => void)
Callback for when this chunk of data is flushed.
false if the stream wishes for the calling code
to wait for the 'drain' event to be
emitted before continuing to write additional data; otherwise
true.
v0.9.4
Optional
callback:
((error) => void)
Sends an HTTP/1.1 103 Early Hints message to the client with
a Link header, indicating that the user agent can
preload/preconnect the linked resources. The
hints is an object containing the values of
headers to be sent with early hints message. The optional
callback argument will be called when the
response message has been written.
Example
const earlyHintsLink = '</styles.css>; rel=preload; as=style';
response.writeEarlyHints({
'link': earlyHintsLink,
});
const earlyHintsLinks = [
'</styles.css>; rel=preload; as=style',
'</scripts.js>; rel=preload; as=script',
];
response.writeEarlyHints({
'link': earlyHintsLinks,
'x-trace-id': 'id for diagnostics',
});
const earlyHintsCallback = () => console.log('early hints message sent');
response.writeEarlyHints({
'link': earlyHintsLinks,
}, earlyHintsCallback);
An object containing the values of headers
Optional
callback:
(() => void)
Will be called when the response message has been written
v18.11.0
Sends a response header to the request. The status code is a
3-digit HTTP status code, like 404. The last
argument, headers, are the response headers.
Optionally one can give a human-readable
statusMessage as the second argument.
headers may be an Array where the
keys and values are in the same list. It is not a
list of tuples. So, the even-numbered offsets are key
values, and the odd-numbered offsets are the associated
values. The array is in the same format as
request.rawHeaders.
Returns a reference to the ServerResponse, so
that calls can be chained.
const body = 'hello world';
response
.writeHead(200, {
'Content-Length': Buffer.byteLength(body),
'Content-Type': 'text/plain',
})
.end(body);
This method must only be called once on a message and it
must be called before response.end() is called.
If response.write() or
response.end() are called before calling this,
the implicit/mutable headers will be calculated and call
this function.
When headers have been set with
response.setHeader(), they will be merged with
any headers passed to response.writeHead(),
with the headers passed to
response.writeHead() given precedence.
If this method is called and
response.setHeader() has not been called, it
will directly write the supplied header values onto the
network channel without caching internally, and the
response.getHeader() on the header will not
yield the expected result. If progressive population of
headers is desired with potential future retrieval and
modification, use response.setHeader() instead.
// Returns content-type = text/plain
const server = http.createServer((req, res) => {
res.setHeader('Content-Type', 'text/html');
res.setHeader('X-Foo', 'bar');
res.writeHead(200, { 'Content-Type': 'text/plain' });
res.end('ok');
});
Content-Length is read in bytes, not
characters. Use Buffer.byteLength() to
determine the length of the body in bytes. Node.js will
check whether Content-Length and the length of
the body which has been transmitted are equal or not.
Attempting to set a header field name or value that contains
invalid characters will result in a [Error][]
being thrown.
Optional
statusMessage:
string
Optional
headers:
OutgoingHttpHeaders | OutgoingHttpHeader[]
v0.1.30
Optional
headers:
OutgoingHttpHeaders | OutgoingHttpHeader[]
Static
addExperimental
Listens once to the abort event on the provided
signal.
Listening to the abort event on abort signals
is unsafe and may lead to resource leaks since another third
party with the signal can call
e.stopImmediatePropagation(). Unfortunately
Node.js cannot change this since it would violate the web
standard. Additionally, the original API makes it easy to
forget to remove listeners.
This API allows safely using AbortSignals in
Node.js APIs by solving these two issues by listening to the
event such that stopImmediatePropagation does
not prevent the listener from running.
Returns a disposable so that it may be unsubscribed from more easily.
import { addAbortListener } from 'node:events';
function example(signal) {
let disposable;
try {
signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
disposable = addAbortListener(signal, (e) => {
// Do something when signal is aborted.
});
} finally {
disposable?.[Symbol.dispose]();
}
}
Disposable that removes the abort listener.
v20.5.0
Static
fromExperimental
A utility method for creating a Writable from a
web WritableStream.
Optional
options:
Pick<WritableOptions, "signal" | "highWaterMark" | "objectMode" | "decodeStrings">
v17.0.0
Static
get
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.
import { getEventListeners, EventEmitter } from 'node:events';
{
const ee = new EventEmitter();
const listener = () => console.log('Events are fun');
ee.on('foo', listener);
console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
}
{
const et = new EventTarget();
const listener = () => console.log('Events are fun');
et.addEventListener('foo', listener);
console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
}
v15.2.0, v14.17.0
Static
getReturns the currently set max amount of listeners.
For EventEmitters this behaves exactly the same
as calling .getMaxListeners on the emitter.
For EventTargets this is the only way to get
the max event listeners for the event target. If the number
of event handlers on a single EventTarget exceeds the max
set, the EventTarget will print a warning.
import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';
{
const ee = new EventEmitter();
console.log(getMaxListeners(ee)); // 10
setMaxListeners(11, ee);
console.log(getMaxListeners(ee)); // 11
}
{
const et = new EventTarget();
console.log(getMaxListeners(et)); // 10
setMaxListeners(11, et);
console.log(getMaxListeners(et)); // 11
}
v19.9.0
Static
listener
A class method that returns the number of listeners for the
given eventNameregistered on the given
emitter.
import { EventEmitter, listenerCount } from 'node: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
v0.9.12
Since v3.2.0 - Use listenerCount instead.
Static on
import { on, EventEmitter } from 'node:events';
import process from 'node:process';
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:
import { on, EventEmitter } from 'node:events';
import process from 'node:process';
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
Optional
options:
StaticEventEmitterOptions
that iterates eventName events emitted by the
emitter
v13.6.0, v12.16.0
Static once
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.
import { once, EventEmitter } from 'node:events';
import process from 'node:process';
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.error('error happened', err);
}
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:
import { EventEmitter, once } from 'node:events';
const ee = new EventEmitter();
once(ee, 'error')
.then(([err]) => console.log('ok', err.message))
.catch((err) => console.error('error', err.message));
ee.emit('error', new Error('boom'));
// Prints: ok boom
An AbortSignal can be used to cancel waiting
for the event:
import { EventEmitter, once } from 'node: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!
Optional
options:
StaticEventEmitterOptions
v11.13.0, v10.16.0
Optional
options:
StaticEventEmitterOptions
Static
setimport { setMaxListeners, EventEmitter } from 'node:events';
const target = new EventTarget();
const emitter = new EventEmitter();
setMaxListeners(5, target, emitter);
Optional
n:
number
A non-negative number. The maximum number of listeners
per EventTarget event.
Rest
...eventTargets:
(EventEmitter<DefaultEventMap> | _DOMEventTarget)[]
v15.4.0
Static
to
Is
trueafter'close'has been emitted.