Readonlyclosed
Readonlyconnection
Alias of outgoingMessage.socket.
Is true after writable.destroy() has
been called.
Readonlyerrored
Returns error if the stream has been destroyed with an error.
Readonlyheaders
Read-only. true if the headers were sent,
otherwise false.
Readonlyreq
Readonlysocket
Reference to the underlying socket. Usually, users will not want to access this property.
After calling outgoingMessage.end(), this
property will be nulled.
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.
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.
If set to true, Node.js will check whether the
Content-Length header 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'.
Readonlywritable
Is true if it is safe to call
writable.write(), which means the stream has not
been destroyed, errored, or ended.
Readonlywritable
Number of times writable.uncork() needs to be
called in order to fully uncork the stream.
Readonlywritable
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.
Readonlywritable
Is set to true immediately before the
'finish' event is emitted.
Readonlywritable
Return the value of highWaterMark passed when
creating this Writable.
Readonlywritable
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.
Readonlywritable
Is true if the stream's buffer has been full and
stream will emit 'drain'.
Readonlywritable
Getter for the property objectMode of a given
Writable stream.
StaticcaptureValue: boolean
Change the default captureRejections option on
all new EventEmitter objects.
Static
ReadonlycaptureValue: Symbol.for('nodejs.rejection')
See how to write a custom rejection handler.
Staticdefault
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.defaultMaxListeners property can be
used. If this value is not a positive number, a
RangeError is thrown.
Take caution when setting the
events.defaultMaxListeners because the change
affects all EventEmitter 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 single
EventEmitter, 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'.
Static
Readonlyerror
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.
Optional_construct
Optional_writev
Optional[captureEvent emitter The defined events on documents including:
Event emitter The defined events on documents including:
Event emitter The defined events on documents including:
Event emitter The defined events on documents including:
Event emitter The defined events on documents including:
Event emitter The defined events on documents including:
Event emitter The defined events on documents including:
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.
Append a single header value to the header object.
If the value is an array, this is equivalent to calling this method multiple times.
If there were no previous values for the header, this is
equivalent to 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
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 implementing
writable._writev() may have an adverse effect
on throughput.
See also: writable.uncork(),
writable._writev().
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 to write() 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().
Optionalerror:
Error
Optional, an error to emit with
'error' event.
Synchronously calls each of the listeners registered for
the event named eventName, in the order they
were registered, passing the supplied arguments to each.
Returns true if the event had listeners,
false otherwise.
import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();
// First listener
myEmitter.on('event', function firstListener() {
console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
const parameters = args.join(', ');
console.log(`event with parameters ${parameters} in third listener`);
});
console.log(myEmitter.listeners('event'));
myEmitter.emit('event', 1, 2, 3, 4, 5);
// Prints:
// [
// [Function: firstListener],
// [Function: secondListener],
// [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
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!
Optionalcb:
()
=>
void
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 data to write. For streams not operating in
object mode, chunk must be a {string},
{Buffer}, {TypedArray} or {DataView}. For object
mode streams, chunk may be any
JavaScript value other than null.
Optionalcb:
()
=>
void
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 data to write. For streams not operating in
object mode, chunk must be a {string},
{Buffer}, {TypedArray} or {DataView}. For object
mode streams, chunk may be any
JavaScript value other than null.
The encoding if chunk is a string
Optionalcb:
()
=>
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) ]
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.
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'] }
Returns the current max listener value for the
EventEmitter which is either set by
emitter.setMaxListeners(n) or defaults to
defaultMaxListeners.
Send response as application/json
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
Optionallistener:
Function
The event handler function
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().
Adds the listener function to the end of the
listeners array for the event named
eventName. No checks are made to see if the
listener has already been added. Multiple
calls passing the same combination of
eventName and listener will
result in the listener being added, and
called, multiple times.
server.on('connection', (stream) => {
console.log('someone connected!');
});
Returns a reference to the EventEmitter, so
that calls can be chained.
By default, event listeners are invoked in the order they
are added. The
emitter.prependListener() method can be used
as an alternative to add the event listener to the
beginning of the listeners array.
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a
The callback function
Adds a one-time
listener function for the event named
eventName. The next time
eventName is triggered, this listener is
removed and then invoked.
server.once('connection', (stream) => {
console.log('Ah, we have our first user!');
});
Returns a reference to the EventEmitter, so
that calls can be chained.
By default, event listeners are invoked in the order they
are added. The
emitter.prependOnceListener() method can be
used as an alternative to add the event listener to the
beginning of the listeners array.
import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
// b
// a
The callback function
Adds the listener function to the
beginning of the listeners array for the event
named eventName. No checks are made to see if
the listener has already been added. Multiple
calls passing the same combination of
eventName and listener will
result in the listener being added, and
called, multiple times.
server.prependListener('connection', (stream) => {
console.log('someone connected!');
});
Returns a reference to the EventEmitter, so
that calls can be chained.
The callback function
Adds a one-timelistener function for the event named
eventName to the beginning of the
listeners array. The next time eventName is
triggered, this listener is removed, and then invoked.
server.prependOnceListener('connection', (stream) => {
console.log('Ah, we have our first user!');
});
Returns a reference to the EventEmitter, so
that calls can be chained.
The callback function
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');
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.
OptionaleventName:
string
|
symbol
Removes the specified listener from the
listener array for the event named eventName.
const callback = (stream) => {
console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);
removeListener() will remove, at most, one
instance of a listener from the listener array. If any
single listener has been added multiple times to the
listener array for the specified eventName,
then removeListener() must be called multiple
times to remove each instance.
Once an event is emitted, all listeners attached to it at
the time of emitting are called in order. This implies
that any removeListener() or
removeAllListeners() calls
after emitting and before the last
listener finishes execution will not remove them fromemit()
in progress. Subsequent events behave as expected.
import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();
const callbackA = () => {
console.log('A');
myEmitter.removeListener('event', callbackB);
};
const callbackB = () => {
console.log('B');
};
myEmitter.on('event', callbackA);
myEmitter.on('event', callbackB);
// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
// A
// B
// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
// A
Because listeners are managed using an internal array,
calling this will change the position indices of any
listener registered after the listener being
removed. This will not impact the order in which listeners
are called, but it means that any copies of the listener
array as returned by the
emitter.listeners() method will need to be
recreated.
When a single function has been added as a handler
multiple times for a single event (as in the example
below), removeListener() will remove the most
recently added instance. In the example the
once('ping') listener is removed:
import { EventEmitter } from 'node:events';
const ee = new EventEmitter();
function pong() {
console.log('pong');
}
ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);
ee.emit('ping');
ee.emit('ping');
Returns a reference to the EventEmitter, so
that calls can be chained.
Send a response
Optionaldata:
string
|
number
|
bigint
|
Readable
|
Buffer
Send a response
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
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
to Infinity (or 0) to indicate
an unlimited number of listeners.
Returns a reference to the EventEmitter, so
that calls can be chained.
Once a socket is associated with the message and is
connected, socket.setTimeout() will be called
with msecs as the first parameter.
Optionalcallback:
()
=>
void
Optional function to be called when a timeout
occurs. Same as binding to the
timeout event.
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() using
process.nextTick(). Doing so allows batching
of all writable.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().
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 the
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. 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}, {TypedArray} or {DataView}. For object
mode streams, chunk may be any
JavaScript value other than null.
Optionalcallback:
(error:
undefined
|
null
|
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.
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 the
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. 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}, {TypedArray} or {DataView}. For object
mode streams, chunk may be any
JavaScript value other than null.
The encoding, if chunk is a string.
Optionalcallback:
(error:
undefined
|
null
|
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.
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
Optionalcallback:
()
=>
void
Will be called when the response message has been written
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.
OptionalstatusMessage:
string
Optionalheaders:
OutgoingHttpHeaders
|
OutgoingHttpHeader[]
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.
Optionalheaders:
OutgoingHttpHeaders
|
OutgoingHttpHeader[]
StaticaddExperimental
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.
StaticfromExperimental
A utility method for creating a Writable from
a web WritableStream.
Optionaloptions:
Pick<Staticget
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] ]
}
StaticgetReturns 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
}
Staticlistener
A class method that returns the number of listeners for
the given eventName registered 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
Staticon
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());
Use the close option to specify an array of
event names that will end the iteration:
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);
ee.emit('close');
});
for await (const event of on(ee, 'foo', { close: ['close'] })) {
console.log(event); // prints ['bar'] [42]
}
// the loop will exit after 'close' is emitted
console.log('done'); // prints 'done'
Optionaloptions:
StaticEventEmitterIteratorOptions
An AsyncIterator that iterates
eventName events emitted by the
emitter
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());
Use the close option to specify an array of
event names that will end the iteration:
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);
ee.emit('close');
});
for await (const event of on(ee, 'foo', { close: ['close'] })) {
console.log(event); // prints ['bar'] [42]
}
// the loop will exit after 'close' is emitted
console.log('done'); // prints 'done'
Optionaloptions:
StaticEventEmitterIteratorOptions
An AsyncIterator that iterates
eventName events emitted by the
emitter
Staticonce
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!
Optionaloptions:
StaticEventEmitterOptions
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!
Optionaloptions:
StaticEventEmitterOptions
Staticsetimport { setMaxListeners, EventEmitter } from 'node:events';
const target = new EventTarget();
const emitter = new EventEmitter();
setMaxListeners(5, target, emitter);
Optionaln:
number
A non-negative number. The maximum number of
listeners per EventTarget event.
Staticto
Is
trueafter'close'has been emitted.