Node.js v14.21.3 documentation

Promise example#

Promise-based operations return a promise that is fulfilled when the asynchronous operation is complete.

import { unlink } from 'fs/promises';

try {
  await unlink('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (error) {
  console.error('there was an error:', error.message);
}const { unlink } = require('fs/promises');

(async function(path) {
  try {
    await unlink(path);
    console.log(`successfully deleted ${path}`);
  } catch (error) {
    console.error('there was an error:', error.message);
  }
})('/tmp/hello');

Callback example#

The callback form takes a completion callback function as its last argument and invokes the operation asynchronously. The arguments passed to the completion callback depend on the method, but the first argument is always reserved for an exception. If the operation is completed successfully, then the first argument is null or undefined.

import { unlink } from 'fs';

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});const { unlink } = require('fs');

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});

The callback-based versions of the fs module APIs are preferable over the use of the promise APIs when maximal performance (both in terms of execution time and memory allocation are required).

Synchronous example#

The synchronous APIs block the Node.js event loop and further JavaScript execution until the operation is complete. Exceptions are thrown immediately and can be handled using try…catch, or can be allowed to bubble up.

import { unlinkSync } from 'fs';

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}const { unlinkSync } = require('fs');

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}

Promises API#

The fs/promises API provides asynchronous file system methods that return promises.

The promise APIs use the underlying Node.js threadpool to perform file system operations off the event loop thread. These operations are not synchronized or threadsafe. Care must be taken when performing multiple concurrent modifications on the same file or data corruption may occur.

Class: FileHandle#

A <FileHandle> object is an object wrapper for a numeric file descriptor.

Instances of the <FileHandle> object are created by the fsPromises.open() method.

All <FileHandle> objects are <EventEmitter>s.

If a <FileHandle> is not closed using the filehandle.close() method, it will try to automatically close the file descriptor and emit a process warning, helping to prevent memory leaks. Please do not rely on this behavior because it can be unreliable and the file may not be closed. Instead, always explicitly close <FileHandle>s. Node.js may change this behavior in the future.

filehandle.appendFile(data[, options])#

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> Default: 'utf8'
• Returns: <Promise> Fulfills with undefined upon success.

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 to filehandle.writeFile().

filehandle.chmod(mode)#

• mode <integer> the file mode bit mask.
• Returns: <Promise> Fulfills with undefined upon success.

Modifies the permissions on the file. See chmod(2).

filehandle.chown(uid, gid)#

• uid <integer> The file's new owner's user id.
• gid <integer> The file's new group's group id.
• Returns: <Promise> Fulfills with undefined upon success.

Changes the ownership of the file. A wrapper for chown(2).

filehandle.close()#

• Returns: <Promise> Fulfills with undefined upon success.

Closes the file handle after waiting for any pending operation on the handle to complete.

import { open } from 'fs/promises';

let filehandle;
try {
  filehandle = await open('thefile.txt', 'r');
} finally {
  await filehandle?.close();
}

filehandle.datasync()#

• Returns: <Promise> Fulfills with undefined upon success.

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.

filehandle.fd#

• <number> The numeric file descriptor managed by the <FileHandle> object.

filehandle.read(buffer, offset, length, position)#

• buffer <Buffer> | <TypedArray> | <DataView> A buffer that will be filled with the file data read.
• offset <integer> The location in the buffer at which to start filling. Default: 0
• length <integer> The number of bytes to read. Default: buffer.byteLength
• position <integer> The 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. If position is an integer, the current file position will remain unchanged.
• Returns: <Promise> Fulfills upon success with an object with two properties:
  • bytesRead <integer> The number of bytes read
  • buffer <Buffer> | <TypedArray> | <DataView> A reference to the passed in buffer argument.

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.

filehandle.read([options])#

• options <Object>
  • buffer <Buffer> | <TypedArray> | <DataView> A buffer that will be filled with the file data read. Default: Buffer.alloc(16384)
  • offset <integer> The location in the buffer at which to start filling. Default: 0
  • length <integer> The number of bytes to read. Default: buffer.byteLength
  • position <integer> The 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. If position is an integer, the current file position will remain unchanged. Default:: null
• Returns: <Promise> Fulfills upon success with an object with two properties:
  • bytesRead <integer> The number of bytes read
  • buffer <Buffer> | <TypedArray> | <DataView> A reference to the passed in buffer argument.

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.

filehandle.readFile(options)#

• options <Object> | <string>
  • encoding <string> | <null> Default: null
  • signal <AbortSignal> allows aborting an in-progress readFile
• Returns: <Promise> Fulfills 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.

If options is a string, then it specifies the encoding.

The <FileHandle> has to support reading.

If one or more filehandle.read() calls are made on a file handle and then a filehandle.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.

filehandle.readv(buffers[, position])#

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> The offset from the beginning of the file where the data should be read from. If position is not a number, the data will be read from the current position.
• Returns: <Promise> Fulfills upon success an object containing two properties:
  • bytesRead <integer> the number of bytes read
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> property containing a reference to the buffers input.

Read from a file and write to an array of <ArrayBufferView>s

filehandle.stat([options])#

• options <Object>
  • bigint <boolean> Whether the numeric values in the returned <fs.Stats> object should be bigint. Default: false.
• Returns: <Promise> Fulfills with an <fs.Stats> for the file.

filehandle.sync()#

• Returns: <Promise> Fufills with undefined upon success.

Request that all data for the open file descriptor is flushed to the storage device. The specific implementation is operating system and device specific. Refer to the POSIX fsync(2) documentation for more detail.

filehandle.truncate(len)#

• len <integer> Default: 0
• Returns: <Promise> Fulfills with undefined upon success.

Truncates the file.

If the file was larger than len bytes, only the first len bytes will be retained in the file.

The following example retains only the first four bytes of the file:

import { open } from '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 then 0 will be used.

filehandle.utimes(atime, mtime)#

• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Returns: <Promise>

Change the file system timestamps of the object referenced by the <FileHandle> then resolves the promise with no arguments upon success.

This function does not work on AIX versions before 7.1, it will reject the promise with an error using code UV_ENOSYS.

filehandle.write(buffer[, offset[, length[, position]]])#

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> The start position from within buffer where the data to write begins. Default: 0
• length <integer> The number of bytes from buffer to write. Default: buffer.byteLength - offset
• position <integer> The offset from the beginning of the file where the data from buffer should be written. If position is not a number, the data will be written at the current position. See the POSIX pwrite(2) documentation for more detail.
• Returns: <Promise>

Write buffer to the file.

The promise is resolved with an object containing two properties:

• bytesWritten <integer> the number of bytes written
• buffer <Buffer> | <TypedArray> | <DataView> a reference to the buffer written.

It is unsafe to use filehandle.write() multiple times on the same file without waiting for the promise to be resolved (or rejected). For this scenario, use fs.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.

filehandle.write(string[, position[, encoding]])#

• string <string>
• position <integer> The offset from the beginning of the file where the data from string should be written. If position is not a number the data will be written at the current position. See the POSIX pwrite(2) documentation for more detail.
• encoding <string> The expected string encoding. Default: 'utf8'
• Returns: <Promise>

Write string to the file. If string is not a string, the promise is rejected with an error.

The promise is resolved with an object containing two properties:

• bytesWritten <integer> the number of bytes written
• buffer <string> a reference to the string written.

It is unsafe to use filehandle.write() multiple times on the same file without waiting for the promise to be resolved (or rejected). For this scenario, use fs.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.

filehandle.writeFile(data, options)#

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <null> The expected character encoding when data is a string. Default: 'utf8'
• Returns: <Promise>

Asynchronously writes data to a file, replacing the file if it already exists. data can be a string, a buffer, an <AsyncIterable> or <Iterable> object. The promise is resolved with no arguments upon success.

If options is a string, then it specifies the encoding.

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 resolved (or rejected).

If one or more filehandle.write() calls are made on a file handle and then a filehandle.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.

filehandle.writev(buffers[, position])#

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> The offset from the beginning of the file where the data from buffers should be written. If position is not a number, the data will be written at the current position.
• Returns: <Promise>

Write an array of