If false, the stream will automatically close the writable end when the
readable end is closed. Set initially by the allowHalfOpen constructor option,
which defaults to true.
This can be changed manually to modify the half-open behavior of an existing
Duplex stream instance, but must be changed before the 'end' event is emitted.
ReadonlyreadableReturns whether the stream was destroyed or encountered an error before emitting 'end'.
Is true if it is safe to call `read`, which means
the stream has not been destroyed or emitted 'error' or 'end'.
ReadonlyreadableReturns whether 'data' has been emitted.
ReadonlyreadableGetter for the encoding property of a given Readable stream. The encoding property can be set using the setEncoding method.
ReadonlyreadableBecomes true when 'end' event is emitted.
This property reflects the current state of a Readable stream, as described
in the " Three States " section.
ReadonlyreadableReturns the value of ` highWaterMark ` passed when this ` Readable` was created.
ReadonlyreadableThis property contains the number of bytes (or objects) in the queue
that are ready to be read. The value provides introspection data regarding
the status of the highWaterMark.
ReadonlyreadableGetter for the ` objectMode ` property of a given ` Readable ` stream.
This is true after ` readable.destroy()` has been called.
ReadonlyclosedIs true after the 'close' event has been triggered.
ReadonlyerroredReturns an error if the stream was destroyed due to an error.
Is true if it is safe to call ` writable.write()`, which means
the stream has not been destroyed, encountered an error, or reached the end.
ReadonlywritableReturns whether the stream was destroyed or encountered an error before emitting 'finish'.
ReadonlywritableThis is true after `writable.end()` has been called. This property
does not indicate whether the data has been flushed; to check that, use `writable.writableFinished ` instead.
ReadonlywritableIt is set to true immediately before the 'finish' event is triggered.
ReadonlywritableReturn the value of ` highWaterMark ` passed when this ` Writable` was created.
ReadonlywritableThis property contains the number of bytes (or objects) in the queue
that are ready to be written. The value provides introspection data regarding
the status of the highWaterMark.
ReadonlywritableGetter for the ` objectMode ` property of a given ` Writable ` stream.
ReadonlywritableThe number of times ` writable.uncork() ` must be
called in order to fully uncork the stream.
ReadonlywritableIs true if the stream's buffer is full and the stream will emit a 'drain' event.
StaticfromA utility method for creating duplex streams.
Stream converts a writable stream into a writable Duplex and a readable stream
into a Duplex.Blob is converted into readable Duplex.The string is converted into a readable Duplex.ArrayBuffer converts to a readable Duplex.AsyncIterable converts to a readable Duplex. Cannot yield null.AsyncGeneratorFunction converts to a readable/writable
Duplex. Must take a source AsyncIterable as the first parameter. Cannot yield
null.AsyncFunction converts to a writable Duplex. Must return
either null or undefinedThe `Object( { writable, readable } ) ` method converts `readable ` and
`writable ` into `Stream ` objects and then combines them into a `Duplex`, where the
`Duplex ` writes to the ` writable ` and reads from the ` readable`.The Promise is converted to a readable Duplex. A null value is ignored.StatictoStaticfromSynchronously 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; otherwise, it returns false.
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
Returns the number of listeners listening for the event named eventName.
If a listener is provided, it returns the number of times that listener appears
in the list of listeners for the event.
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] ]
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
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
Adds the listener function to the beginning of the listeners array for the
event named eventName. No checks are made to determine whether the listener has
already been added. Multiple calls that pass 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.
Adds a one-time listener 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.
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 for the specified eventName.
It is bad practice to remove listeners added elsewhere in the code,
especially 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.
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 a 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 emission are called in order. This means that any
removeListener() or removeAllListeners() calls made after emission and
before the last listener finishes executing will not remove them from
the currentemit() operation. 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 indexes of any listener registered after the listener
being removed. This will not affect the order in which listeners are called,
but it means that any copies of the listener array 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.
Returns an array listing the events for which the emitter has registered listeners.
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) ]
By default, EventEmitterswill display a warning if more than 10 listeners are
added for a particular event. This is a useful default that helps identify
memory leaks. The `emitter.setMaxListeners()` method allows the limit to be
adjusted for this specific EventEmitter instance. The value can be set to
`Infinity ` (or `0`) to allow an unlimited number of listeners.
Returns a reference to the EventEmitter, so that calls can be chained.
Optional[captureThe ` Symbol.for('nodejs.rejection') ` method is called if a
promise rejection occurs when emitting an event and
`captureRejections ` is enabled on the emitter.
You can use `events.captureRejectionSymbol` instead of
`Symbol.for('nodejs.rejection')`.
import { EventEmitter, captureRejectionSymbol } from 'node:events';
class MyClass extends EventEmitter {
constructor() {
super({ captureRejections: true });
}
[captureRejectionSymbol](err, event, ...args) {
console.log('rejection happened for', event, 'with', err, ...args);
this.destroy(err);
}
destroy(err) {
// Tear the resource down here.
}
}
Optional_The ` readable.read() ` method reads data from the internal buffer and
returns it. If no data is available to be read, `null` is returned. By default,
the data is 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. If
there are notenough bytes to 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 completely emptied.
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 that has not yet been 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 entire 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 the `size` 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.
The ` readable.setEncoding() ` method sets the character encoding for
data read from the Readable stream.
By default, no encoding is assigned, and stream data is returned as Buffer objects. Setting an encoding causes the stream data
to be returned as strings in the specified encoding rather than as Buffer objects. For instance, calling ` readable.setEncoding('utf8') ` will cause the
output data to be interpreted as UTF-8 data and passed as strings. Calling `readable.setEncoding('hex') ` will cause the data to be encoded in hexadecimal
string format.
The Readable stream will properly handle multibyte characters delivered
through the stream that would otherwise be decoded incorrectly 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.
The ` readable.pause()` method causes 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.
The ` readable.resume() ` method causes an explicitly paused Readable stream to
resume emitting 'data' events, switching the stream to 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.isPaused() method returns the current state of the Readable.
This is used primarily by the mechanism that underlies the readable.pipe() method.
In most cases, there is no need to use this method directly.
const readable = new stream.Readable();
readable.isPaused(); // === false
readable.pause();
readable.isPaused(); // === true
readable.resume();
readable.isPaused(); // === false
The ` readable.unpipe() ` method detaches a ` Writable ` stream that was previously attached
using the ` pipe ` method.
If the destination is not specified, all pipes are detached.
If the destination is specified but no pipe has been set up for it, then
the method does nothing.
import fs from 'node: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 placed 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 from the source, so that the data can be passed on to another party.
The ` stream.unshift(chunk) ` method cannot be called after the 'end' event
has been emitted; otherwise, a runtime error will be thrown.
Developers who frequently use `stream.unshift()` should consider switching to
the 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).
import { StringDecoder } from 'node: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.includes('\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);
return;
}
// Still reading the header.
header += str;
}
}
}
Unlike `push`, `stream.unshift(chunk) ` will not
terminate the reading process by resetting the stream’s internal reading state.
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.
A chunk of data to add to the read queue. For streams not operating in object mode, the chunk must
be a {string}, {Buffer}, {TypedArray}, {DataView}, or null. For streams in object mode, the 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 `node: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 for informational purposes only, the `readable.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.
import { OldReader } from './old-api-module.js';
import { Readable } from 'node:stream';
const oreader = new OldReader();
const myReader = new Readable().wrap(oreader);
myReader.on('readable', () => {
myReader.read(); // etc.
});
An "old-style" readable stream
import { Readable } from 'node:stream';
async function* splitToWords(source) {
for await (const chunk of source) {
const words = String(chunk).split(' ');
for (const word of words) {
yield word;
}
}
}
const wordsStream = Readable.from(['text passed through', 'composed stream']).compose(splitToWords);
const words = await wordsStream.toArray();
console.log(words); // prints ['text', 'passed', 'through', 'composed', 'stream']
readable.compose(s) is equivalent to stream.compose(readable, s).
This method also allows an AbortSignal to be provided, which will destroy
the composed stream when aborted.
See stream.compose(...streams) for more information.
a stream composed of the stream stream.
The iterator created by this method allows users to choose whether to cancel the destruction
of the stream if the `for await...of ` loop is exited by a `return`, `break`, or `throw`,
or whether the iterator should destroy the stream if an error occurs during iteration.
This method allows you to map over the stream. The `fn` function will be called for every chunk in the stream.
If the `fn` function returns a promise, that promise will be resolvedbefore being passed to the result stream.
a function to iterate over every chunk in the stream. Asynchronous or not.
a stream mapped using the function fn.
This method allows you to filter the stream. For each chunk in the stream, the `fn` function will be called,
and if it returns a truthy value, the chunk will be passed to the result stream.
If the `fn` function returns a promise, that promise will be awaited.
a function to filter chunks from the stream. Asynchronous or not.
a stream filtered using the predicate fn.
This method allows you to iterate over a stream. For each chunk in the stream, the `fn` function will be called.
If the `fn` function returns a promise, that promise will be awaited.
This method differs from `for await...of ` loops in that it can optionally process chunks concurrently.
In addition, a `forEach` iteration can only be stopped by passing a signal option
and aborting the associated `AbortController`, whereas `for await...of ` can be stopped using `break` or `return`.
In either case, the stream will be destroyed.
This method differs from listening for the 'data' event in that it uses the readable event
in the underlying system and can limit the number of concurrent function calls.
a function to call for each chunk of the stream. Asynchronous or not.
Optionaloptions: Pick<ReadableOperatorOptions, "signal" | "concurrency">a promise for when the stream has finished.
This method makes it easy to retrieve the contents of a stream.
Since this method reads the entire stream into memory, it negates the benefits of streams. It is intended for interoperability and convenience, not as the primary way to consume streams.
a promise containing an array with the contents of the stream.
This method is similar to `Array.prototype.some` and calls `fn` on each chunk in the stream
until the awaited return value is `true ` (or any truthy value). Oncethe awaitedreturn value of a `fn` call on a chunk
is truthy, the stream is destroyed and the promise is fulfilled with `true`.
If none of the `fn` calls on the chunks return a truthy value, the promise is fulfilled with `false`.
a function to call for each chunk of the stream. Asynchronous or not.
Optionaloptions: Pick<ReadableOperatorOptions, "signal" | "concurrency">a promise that evaluates to true if fn returned a truthy value for at least one of the chunks.
This method is similar to `Array.prototype.find ` and calls `fn` on each chunk in the stream
to find a chunk for which `fn` returns a truthy value. Once the awaited return value of an `fn` call is truthy,
the stream is destroyed and the promise is fulfilled with the value for which `fn` returned a truthy value.
If all `fn` calls on the chunks return a falsy value, the promise is fulfilled with `undefined`.
a function to call for each chunk of the stream. Asynchronous or not.
Optionaloptions: Pick<ReadableOperatorOptions, "signal" | "concurrency">a promise that resolves to the first chunk for which fn evaluates to a truthy value,
or undefined if no element was found.
This method is similar to `Array.prototype.find ` and calls `fn` on each chunk in the stream
to find a chunk for which `fn` returns a truthy value. Once the awaited return value of an `fn` call is truthy,
the stream is destroyed and the promise is fulfilled with the value for which `fn` returned a truthy value.
If all `fn` calls on the chunks return a falsy value, the promise is fulfilled with `undefined`.
a function to call for each chunk of the stream. Asynchronous or not.
Optionaloptions: Pick<ReadableOperatorOptions, "signal" | "concurrency">a promise that resolves to the first chunk for which fn evaluates to a truthy value,
or undefined if no element was found.
This method is similar to `Array.prototype.every` and calls `fn` on each chunk in the stream
to check whether all awaited return values are truthy for `fn`. Once an `fn` call on a chunk
returns afalsyvalue, the stream is destroyed and the promise is fulfilled with `false`.
If all `fn` calls on the chunks return a truthy value, the promise is fulfilled with `true`.
a function to call for each chunk of the stream. Asynchronous or not.
Optionaloptions: Pick<ReadableOperatorOptions, "signal" | "concurrency">a promise that evaluates to true if fn returned a truthy value for each of the chunks.
This method returns a new stream by applying the given callback to each chunk of the stream and then flattening the result.
It is possible to return a stream, another iterable, or an async iterable from `fn`, and the resulting streams will be merged (flattened) into the returned stream.
a function that iterates over every chunk in the stream. It may be asynchronous. It may be a stream or a generator.
Optionaloptions: Pick<ReadableOperatorOptions, "signal" | "concurrency">a stream flat-mapped using the function fn.
This method calls fn on each chunk of the stream in order, passing it the result of the calculation performed on the previous element. It returns a promise for the final value of the reduction.
If no initial value is provided, the first chunk of the stream is used as the initial value.
If the stream is empty, the promise is rejected with a TypeError that has the ` ERR_INVALID_ARGS ` code property.
The reducer function processes the stream element by element, which means there is no concurrency parameter
or parallelism. To perform a reduce operation concurrently, you can move the async function to the ` readable.map ` method.
a reducer function to be called on every chunk in the stream. Asynchronous or not.
a guarantee of the final value of the reduction.
This method calls fn on each chunk of the stream in order, passing it the result of the calculation performed on the previous element. It returns a promise for the final value of the reduction.
If no initial value is provided, the first chunk of the stream is used as the initial value.
If the stream is empty, the promise is rejected with a TypeError that has the ` ERR_INVALID_ARGS ` code property.
The reducer function processes the stream element by element, which means there is no concurrency parameter
or parallelism. To perform a reduce operation concurrently, you can move the async function to the ` readable.map ` method.
a guarantee of the final value of the reduction.
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 subsequent calls will have no effect, and no
further errors—other than those from `_destroy()` —may be reported as 'error'.
Implementors should not override this method, but instead implement readable._destroy().
Error that will be passed as the payload in the 'error' event
OptionalThe ` writable.write()` method writes some data to the stream and calls the
supplied callback once the data has been fully processed. If an error
occurs, the callback will be called with the error as its
first argument. The callback is called asynchronously and before an 'error' is
emitted.
The return value is true if the internal buffer is smaller than the highWaterMark configured when the stream was created after accepting the 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 chunks 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 to 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 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 retrieved on demand, it is
recommended to encapsulate the logic in a Readable and use a pipe. However, if you prefer to call `write()`, it is
possible to handle backpressure and avoid memory issues by 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 streams in object mode, chunk may be any JavaScript value other than null.
Callback to be called when this chunk of data is flushed.
false if the stream wants the calling code to wait for the 'drain' event to be emitted before continuing to write additional data; otherwise true.
Writes data to the stream, using explicit encoding for string data.
Optional data to write. For streams not operating in object mode, chunk must be a {string}, {Buffer},
{TypedArray}, or {DataView}. For streams in object mode, chunk may be any JavaScript value other than null.
The encoding, if ` chunk ` is a string.
Callback to be called when this chunk of data is flushed.
false if the stream wants the calling code to wait for the 'drain' event to be emitted before continuing to write additional data; otherwise true.
See Writable.write for full details.
Calling the ` writable.end()` method indicates 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!'.
import fs from 'node:fs';
const file = fs.createWriteStream('example.txt');
file.write('hello, ');
file.end('world!');
// Writing more now is not allowed!
Callback to be called when the stream has finished.
Indicates that no more data will be written, followed by a final chunk of data.
Optional data to write. For streams not operating in object mode, chunk must be a {string}, {Buffer},
{TypedArray}, or {DataView}. For streams in object mode, chunk may be any JavaScript value other than null.
Callback to be called when the stream has finished.
See Writable.end for full details.
Indicates that no more data will be written, followed by a final chunk of data.
Optional data to write. For streams not operating in object mode, chunk must be a {string}, {Buffer},
{TypedArray}, or {DataView}. For streams in object mode, chunk may be any JavaScript value other than null.
The encoding of the chunk is a string
Callback to be called when the stream has finished.
See Writable.end for full details.
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 ` method is called.
The primary purpose of `writable.cork()` is to handle 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, using writable.cork() without implementing writable._writev() may have a negative impact on throughput.
See also: writable.uncork(), writable._writev().
The ` writable.uncork() ` method flushes all data that has been 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 made 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().
HsmCipherStream Implements symmetric streaming orchestration (encryption/decryption) for the HSM using AAP streams 5 and 6.