stream.Writable
Instances of fs.WriteStream
are created and returned using the {@link createWriteStream } function.
* Extends `stream.Writable` Instances of `fs.WriteStream` are created and returned using the {@link createWriteStream } function.
(add-listener write-stream event listener)
events.EventEmitter
Parameters:
event
: string | symbol
listener
: (...args: any[]) => void
Returns: WriteStream
events.EventEmitter 1. open 2. close 3. ready **Parameters:** - `event`: `string | symbol` - `listener`: `(...args: any[]) => void` **Returns:** `WriteStream`
(bytes-written write-stream)
The number of bytes written so far. Does not include data that is still queued for writing.
The number of bytes written so far. Does not include data that is still queued for writing.
(close write-stream)
(close write-stream callback)
Closes writeStream
. Optionally accepts a
callback that will be executed once the writeStream
is closed.
Parameters:
callback
: ((err?: ErrnoException | null | undefined) => void) | undefined
Returns: void
Closes `writeStream`. Optionally accepts a callback that will be executed once the `writeStream`is closed. **Parameters:** - `callback`: `((err?: ErrnoException | null | undefined) => void) | undefined` **Returns:** `void`
(closed? write-stream)
Is true
after 'close'
has been emitted.
Is `true` after `'close'` has been emitted.
(compose write-stream stream)
(compose write-stream stream options)
Parameters:
stream
: ComposeFnParam | T | Iterable<T> | AsyncIterable<T>
options
: { signal: AbortSignal; } | undefined
Returns: T
**Parameters:** - `stream`: `ComposeFnParam | T | Iterable<T> | AsyncIterable<T>` - `options`: `{ signal: AbortSignal; } | undefined` **Returns:** `T`
(cork write-stream)
The writable.cork()
method forces all written data to be buffered in memory.
The buffered data will be flushed when either the {@link uncork } or {@link 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()
.
Returns: void
The `writable.cork()` method forces all written data to be buffered in memory. The buffered data will be flushed when either the {@link uncork } or {@link 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()`. **Returns:** `void`
(destroy write-stream)
(destroy write-stream error)
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()
.
Parameters:
error
: Error | undefined
- Optional, an error to emit with 'error'
event.Returns: WriteStream
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()`. **Parameters:** - `error`: `Error | undefined` - Optional, an error to emit with `'error'` event. **Returns:** `WriteStream`
(destroyed? write-stream)
Is true
after writable.destroy()
has been called.
Is `true` after `writable.destroy()` has been called.
(emit? write-stream & event)
(emit? write-stream event err)
(emit? write-stream event src)
(emit? write-stream event & args)
Parameters:
event
: string | symbol
args
: any[]
err
: Error
src
: Readable
Returns: boolean
**Parameters:** - `event`: `string | symbol` - `args`: `any[]` - `err`: `Error` - `src`: `Readable` **Returns:** `boolean`
(end write-stream)
(end write-stream cb)
(end write-stream chunk)
(end write-stream chunk cb)
(end write-stream chunk encoding)
(end write-stream chunk encoding cb)
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 {@link write } method after calling {@link 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!
Parameters:
chunk
: any
encoding
: BufferEncoding
cb
: (() => void) | undefined
Returns: WriteStream
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 {@link write } method after calling {@link end } will raise an error. ```js // 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! ``` **Parameters:** - `chunk`: `any` - `encoding`: `BufferEncoding` - `cb`: `(() => void) | undefined` **Returns:** `WriteStream`
(errored write-stream)
Returns error if the stream has been destroyed with an error.
Returns error if the stream has been destroyed with an error.
(event-names write-stream)
Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or Symbol
s.
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) ]
Returns: (string | symbol)[]
Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or `Symbol`s. ```js 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) ] ``` **Returns:** `(string | symbol)[]`
(listener-count write-stream event-name)
(listener-count write-stream event-name listener)
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.
Parameters:
event-name
: string | symbol
- The name of the event being listened forlistener
: Function | undefined
- The event handler functionReturns: number
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. **Parameters:** - `event-name`: `string | symbol` - The name of the event being listened for - `listener`: `Function | undefined` - The event handler function **Returns:** `number`
(listeners write-stream event-name)
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] ]
Parameters:
event-name
: string | symbol
Returns: Function[]
Returns a copy of the array of listeners for the event named `eventName`. ```js server.on('connection', (stream) => { console.log('someone connected!'); }); console.log(util.inspect(server.listeners('connection'))); // Prints: [ [Function] ] ``` **Parameters:** - `event-name`: `string | symbol` **Returns:** `Function[]`
(max-listeners write-stream)
Returns the current max listener value for the EventEmitter
which is either
set by emitter.setMaxListeners(n)
or defaults to {@link defaultMaxListeners }.
Returns: number
Returns the current max listener value for the `EventEmitter` which is either set by `emitter.setMaxListeners(n)` or defaults to {@link defaultMaxListeners }. **Returns:** `number`
(off write-stream event-name listener)
Alias for emitter.removeListener()
.
Parameters:
event-name
: string | symbol
listener
: (...args: any[]) => void
Returns: WriteStream
Alias for `emitter.removeListener()`. **Parameters:** - `event-name`: `string | symbol` - `listener`: `(...args: any[]) => void` **Returns:** `WriteStream`
(on write-stream event listener)
Parameters:
event
: string | symbol
listener
: (...args: any[]) => void
Returns: WriteStream
**Parameters:** - `event`: `string | symbol` - `listener`: `(...args: any[]) => void` **Returns:** `WriteStream`
(once write-stream event listener)
Parameters:
event
: string | symbol
listener
: (...args: any[]) => void
Returns: WriteStream
**Parameters:** - `event`: `string | symbol` - `listener`: `(...args: any[]) => void` **Returns:** `WriteStream`
(path write-stream)
The path to the file the stream is writing to as specified in the first
argument to {@link createWriteStream }. If path
is passed as a string, thenwriteStream.path
will be a string. If path
is passed as a Buffer
, thenwriteStream.path
will be a
Buffer
.
The path to the file the stream is writing to as specified in the first argument to {@link createWriteStream }. If `path` is passed as a string, then`writeStream.path` will be a string. If `path` is passed as a `Buffer`, then`writeStream.path` will be a `Buffer`.
(pending? write-stream)
This property is true
if the underlying file has not been opened yet,
i.e. before the 'ready'
event is emitted.
This property is `true` if the underlying file has not been opened yet, i.e. before the `'ready'` event is emitted.
(pipe write-stream destination)
(pipe write-stream destination options)
Parameters:
destination
: T
options
: { end?: boolean | undefined; } | undefined
Returns: T
**Parameters:** - `destination`: `T` - `options`: `{ end?: boolean | undefined; } | undefined` **Returns:** `T`
(prepend-listener write-stream event listener)
Parameters:
event
: string | symbol
listener
: (...args: any[]) => void
Returns: WriteStream
**Parameters:** - `event`: `string | symbol` - `listener`: `(...args: any[]) => void` **Returns:** `WriteStream`
(prepend-once-listener write-stream event listener)
Parameters:
event
: string | symbol
listener
: (...args: any[]) => void
Returns: WriteStream
**Parameters:** - `event`: `string | symbol` - `listener`: `(...args: any[]) => void` **Returns:** `WriteStream`
(raw-listeners write-stream event-name)
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');
Parameters:
event-name
: string | symbol
Returns: Function[]
Returns a copy of the array of listeners for the event named `eventName`, including any wrappers (such as those created by `.once()`). ```js 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'); ``` **Parameters:** - `event-name`: `string | symbol` **Returns:** `Function[]`
(remove-all-listeners write-stream)
(remove-all-listeners write-stream event-name)
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.
Parameters:
event-name
: string | symbol | undefined
Returns: WriteStream
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. **Parameters:** - `event-name`: `string | symbol | undefined` **Returns:** `WriteStream`
(remove-listener write-stream event listener)
Parameters:
event
: string | symbol
listener
: (...args: any[]) => void
Returns: WriteStream
**Parameters:** - `event`: `string | symbol` - `listener`: `(...args: any[]) => void` **Returns:** `WriteStream`
(set-bytes-written! write-stream value)
The number of bytes written so far. Does not include data that is still queued for writing.
The number of bytes written so far. Does not include data that is still queued for writing.
(set-default-encoding write-stream encoding)
The writable.setDefaultEncoding()
method sets the default encoding
for a Writable
stream.
Parameters:
encoding
: BufferEncoding
- The new default encodingReturns: WriteStream
The `writable.setDefaultEncoding()` method sets the default `encoding` for a `Writable` stream. **Parameters:** - `encoding`: `BufferEncoding` - The new default encoding **Returns:** `WriteStream`
(set-destroyed! write-stream value)
Is true
after writable.destroy()
has been called.
Is `true` after `writable.destroy()` has been called.
(set-max-listeners write-stream n)
By default EventEmitter
s 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.
Parameters:
n
: number
Returns: WriteStream
By default `EventEmitter`s 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. **Parameters:** - `n`: `number` **Returns:** `WriteStream`
(set-path! write-stream value)
The path to the file the stream is writing to as specified in the first
argument to {@link createWriteStream }. If path
is passed as a string, thenwriteStream.path
will be a string. If path
is passed as a Buffer
, thenwriteStream.path
will be a
Buffer
.
The path to the file the stream is writing to as specified in the first argument to {@link createWriteStream }. If `path` is passed as a string, then`writeStream.path` will be a string. If `path` is passed as a `Buffer`, then`writeStream.path` will be a `Buffer`.
(set-pending! write-stream value)
This property is true
if the underlying file has not been opened yet,
i.e. before the 'ready'
event is emitted.
This property is `true` if the underlying file has not been opened yet, i.e. before the `'ready'` event is emitted.
(uncork write-stream)
The writable.uncork()
method flushes all data buffered since {@link 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()
.
Returns: void
The `writable.uncork()` method flushes all data buffered since {@link 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. ```js 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. ```js 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()`. **Returns:** `void`
(writable-corked write-stream)
Number of times writable.uncork()
needs to be
called in order to fully uncork the stream.
Number of times `writable.uncork()` needs to be called in order to fully uncork the stream.
(writable-ended? write-stream)
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.
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.
(writable-finished? write-stream)
Is set to true
immediately before the 'finish'
event is emitted.
Is set to `true` immediately before the `'finish'` event is emitted.
(writable-high-water-mark write-stream)
Return the value of highWaterMark
passed when creating this Writable
.
Return the value of `highWaterMark` passed when creating this `Writable`.
(writable-length write-stream)
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
.
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`.
(writable-need-drain? write-stream)
Is true
if the stream's buffer has been full and stream will emit 'drain'
.
Is `true` if the stream's buffer has been full and stream will emit `'drain'`.
(writable-object-mode? write-stream)
Getter for the property objectMode
of a given Writable
stream.
Getter for the property `objectMode` of a given `Writable` stream.
(writable? write-stream)
Is true
if it is safe to call writable.write()
, which means
the stream has not been destroyed, errored, or ended.
Is `true` if it is safe to call `writable.write()`, which means the stream has not been destroyed, errored, or ended.
(write? write-stream chunk)
(write? write-stream chunk callback)
(write? write-stream chunk encoding)
(write? write-stream chunk encoding callback)
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 {@link 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.
Parameters:
chunk
: any
encoding
: BufferEncoding
callback
: ((error: Error | null | undefined) => void) | undefined
Returns: boolean
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 {@link pipe }. However, if calling `write()` is preferred, it is possible to respect backpressure and avoid memory issues using the `'drain'` event: ```js 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. **Parameters:** - `chunk`: `any` - `encoding`: `BufferEncoding` - `callback`: `((error: Error | null | undefined) => void) | undefined` **Returns:** `boolean`
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close