The numeric file descriptor managed by the {FileHandle} object.
interface
fs.promises.FileHandle
interface FileHandle
An alias for ().
- ): Promise<void>;
Alias of
filehandle.writeFile()
.When operating on file handles, the mode cannot be changed from what it was set to with
fsPromises.open()
. Therefore, this is equivalent tofilehandle.writeFile()
.@returnsFulfills with
undefined
upon success. Closes the file handle after waiting for any pending operation on the handle to complete.
import { open } from 'node:fs/promises'; let filehandle; try { filehandle = await open('thefile.txt', 'r'); } finally { await filehandle?.close(); }
@returnsFulfills with
undefined
upon success.Unlike the 16 KiB default
highWaterMark
for astream.Readable
, the stream returned by this method has a defaulthighWaterMark
of 64 KiB.options
can includestart
andend
values to read a range of bytes from the file instead of the entire file. Bothstart
andend
are inclusive and start counting at 0, allowed values are in the [0,Number.MAX_SAFE_INTEGER
] range. Ifstart
is omitted orundefined
,filehandle.createReadStream()
reads sequentially from the current file position. Theencoding
can be any one of those accepted byBuffer
.If the
FileHandle
points to a character device that only supports blocking reads (such as keyboard or sound card), read operations do not finish until data is available. This can prevent the process from exiting and the stream from closing naturally.By default, the stream will emit a
'close'
event after it has been destroyed. Set theemitClose
option tofalse
to change this behavior.import { open } from 'node:fs/promises'; const fd = await open('/dev/input/event0'); // Create a stream from some character device. const stream = fd.createReadStream(); setTimeout(() => { stream.close(); // This may not close the stream. // Artificially marking end-of-stream, as if the underlying resource had // indicated end-of-file by itself, allows the stream to close. // This does not cancel pending read operations, and if there is such an // operation, the process may still not be able to exit successfully // until it finishes. stream.push(null); stream.read(0); }, 100);
If
autoClose
is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak. IfautoClose
is set to true (default behavior), on'error'
or'end'
the file descriptor will be closed automatically.An example to read the last 10 bytes of a file which is 100 bytes long:
import { open } from 'node:fs/promises'; const fd = await open('sample.txt'); fd.createReadStream({ start: 90, end: 99 });
options
may also include astart
option to allow writing data at some position past the beginning of the file, allowed values are in the [0,Number.MAX_SAFE_INTEGER
] range. Modifying a file rather than replacing it may require theflags
open
option to be set tor+
rather than the defaultr
. Theencoding
can be any one of those accepted byBuffer
.If
autoClose
is set to true (default behavior) on'error'
or'finish'
the file descriptor will be closed automatically. IfautoClose
is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak.By default, the stream will emit a
'close'
event after it has been destroyed. Set theemitClose
option tofalse
to change this behavior.Forces all currently queued I/O operations associated with the file to the operating system's synchronized I/O completion state. Refer to the POSIX
fdatasync(2)
documentation for details.Unlike
filehandle.sync
this method does not flush modified metadata.@returnsFulfills with
undefined
upon success.- buffer: T,offset?: null | number,length?: null | number,position?: null | number
Reads data from the file and stores that in the given buffer.
If the file is not modified concurrently, the end-of-file is reached when the number of bytes read is zero.
@param bufferA buffer that will be filled with the file data read.
@param offsetThe location in the buffer at which to start filling.
@param lengthThe number of bytes to read.
@param positionThe location where to begin reading data from the file. If
null
, data will be read from the current file position, and the position will be updated. Ifposition
is an integer, the current file position will remain unchanged.@returnsFulfills upon success with an object with two properties:
buffer: T, Returns a byte-oriented
ReadableStream
that may be used to read the file's contents.An error will be thrown if this method is called more than once or is called after the
FileHandle
is closed or closing.import { open, } from 'node:fs/promises'; const file = await open('./some/file/to/read'); for await (const chunk of file.readableWebStream()) console.log(chunk); await file.close();
While the
ReadableStream
will read the file to completion, it will not close theFileHandle
automatically. User code must still call thefileHandle.close()
method.Asynchronously reads the entire contents of a file.
If
options
is a string, then it specifies theencoding
.The
FileHandle
has to support reading.If one or more
filehandle.read()
calls are made on a file handle and then afilehandle.readFile()
call is made, the data will be read from the current position till the end of the file. It doesn't always read from the beginning of the file.@returnsFulfills upon a successful read with the contents of the file. If no encoding is specified (using
options.encoding
), the data is returned as a {Buffer} object. Otherwise, the data will be a string.Asynchronously reads the entire contents of a file. The underlying file will not be closed automatically. The
FileHandle
must have been opened for reading.Convenience method to create a
readline
interface and stream over the file. Seefilehandle.createReadStream()
for the options.import { open } from 'node:fs/promises'; const file = await open('./some/file/to/read'); for await (const line of file.readLines()) { console.log(line); }
- buffers: readonly ArrayBufferView<ArrayBufferLike>[],position?: number
Read from a file and write to an array of ArrayBufferView s
@param positionThe offset from the beginning of the file where the data should be read from. If
position
is not anumber
, the data will be read from the current position.@returnsFulfills upon success an object containing two properties:
- @returns
Fulfills with an {fs.Stats} for the file.
- len?: number): Promise<void>;
Truncates the file.
If the file was larger than
len
bytes, only the firstlen
bytes will be retained in the file.The following example retains only the first four bytes of the file:
import { open } from 'node:fs/promises'; let filehandle = null; try { filehandle = await open('temp.txt', 'r+'); await filehandle.truncate(4); } finally { await filehandle?.close(); }
If the file previously was shorter than
len
bytes, it is extended, and the extended part is filled with null bytes ('\0'
):If
len
is negative then0
will be used.@returnsFulfills with
undefined
upon success. - buffer: TBuffer,offset?: null | number,length?: null | number,position?: null | number): Promise<{ buffer: TBuffer; bytesWritten: number }>;
Write
buffer
to the file.The promise is fulfilled with an object containing two properties:
It is unsafe to use
filehandle.write()
multiple times on the same file without waiting for the promise to be fulfilled (or rejected). For this scenario, usefilehandle.createWriteStream()
.On Linux, positional writes do not work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file.
@param offsetThe start position from within
buffer
where the data to write begins.@param lengthThe number of bytes from
buffer
to write.@param positionThe offset from the beginning of the file where the data from
buffer
should be written. Ifposition
is not anumber
, the data will be written at the current position. See the POSIX pwrite(2) documentation for more detail.buffer: TBuffer,options?: { length: number; offset: number; position: number }): Promise<{ buffer: TBuffer; bytesWritten: number }>;data: string,position?: null | number,encoding?: null | BufferEncoding): Promise<{ buffer: string; bytesWritten: number }>; - ): Promise<void>;
Asynchronously writes data to a file, replacing the file if it already exists.
data
can be a string, a buffer, an AsyncIterable, or an Iterable object. The promise is fulfilled with no arguments upon success.If
options
is a string, then it specifies theencoding
.The
FileHandle
has to support writing.It is unsafe to use
filehandle.writeFile()
multiple times on the same file without waiting for the promise to be fulfilled (or rejected).If one or more
filehandle.write()
calls are made on a file handle and then afilehandle.writeFile()
call is made, the data will be written from the current position till the end of the file. It doesn't always write from the beginning of the file. - buffers: readonly ArrayBufferView<ArrayBufferLike>[],position?: number
Write an array of ArrayBufferView s to the file.
The promise is fulfilled with an object containing a two properties:
It is unsafe to call
writev()
multiple times on the same file without waiting for the promise to be fulfilled (or rejected).On Linux, positional writes don't work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file.
@param positionThe offset from the beginning of the file where the data from
buffers
should be written. Ifposition
is not anumber
, the data will be written at the current position.