Common Objects

The common objects are shared by all of the file system API variants (promise, callback, and synchronous).

A class representing a directory stream.

Created by fs.opendir(), fs.opendirSync(), or fsPromises.opendir().

import { opendir } from 'node:fs/promises';

try {
  const dir = await opendir('./');
  for await (const dirent of dir)
    console.log(dirent.name);
} catch (err) {
  console.error(err);
}

When using the async iterator, the fs.Dir object will be automatically closed after the iterator exits.

dir.close(): Promise

Asynchronously close the directory's underlying resource handle. Subsequent reads will result in errors.

A promise is returned that will be fulfilled after the resource has been closed.

dir.close(callback): void

Asynchronously close the directory's underlying resource handle. Subsequent reads will result in errors.

The callback will be called after the resource handle has been closed.

dir.closeSync(): void

Synchronously close the directory's underlying resource handle. Subsequent reads will result in errors.

The read-only path of this directory as was provided to fs.opendir(), fs.opendirSync(), or fsPromises.opendir().

dir.read(): Promise

Asynchronously read the next directory entry via readdir(3) as an fs.Dirent.

A promise is returned that will be fulfilled with an fs.Dirent, or null if there are no more directory entries to read.

Directory entries returned by this function are in no particular order as provided by the operating system's underlying directory mechanisms. Entries added or removed while iterating over the directory might not be included in the iteration results.

dir.read(callback): void

Asynchronously read the next directory entry via readdir(3) as an fs.Dirent.

After the read is completed, the callback will be called with an fs.Dirent, or null if there are no more directory entries to read.

Directory entries returned by this function are in no particular order as provided by the operating system's underlying directory mechanisms. Entries added or removed while iterating over the directory might not be included in the iteration results.

dir.readSync(): fs.Dirent | null

Synchronously read the next directory entry as an fs.Dirent. See the POSIX readdir(3) documentation for more detail.

If there are no more directory entries to read, null will be returned.

Directory entries returned by this function are in no particular order as provided by the operating system's underlying directory mechanisms. Entries added or removed while iterating over the directory might not be included in the iteration results.

dir[Symbol.asyncIterator](): AsyncIterator

Asynchronously iterates over the directory until all entries have been read. Refer to the POSIX readdir(3) documentation for more detail.

Entries returned by the async iterator are always an fs.Dirent. The null case from dir.read() is handled internally.

See fs.Dir for an example.

Directory entries returned by this iterator are in no particular order as provided by the operating system's underlying directory mechanisms. Entries added or removed while iterating over the directory might not be included in the iteration results.

dir[Symbol.asyncDispose](): Promise

Calls dir.close() if the directory handle is open, and returns a promise that fulfills when disposal is complete.

This method enables the directory to be used with await using, which will automatically close the directory when the scope exits. For more information, see the MDN documentation on using statements.

dir[Symbol.dispose](): void

Calls dir.closeSync() if the directory handle is open, and returns undefined.

This method enables the directory to be used with using, which will automatically close the directory when the scope exits. For more information, see the MDN documentation on using statements.

A representation of a directory entry, which can be a file or a subdirectory within the directory, as returned by reading from an fs.Dir. The directory entry is a combination of the file name and file type pairs.

Additionally, when fs.readdir() or fs.readdirSync() is called with the withFileTypes option set to true, the resulting array is filled with fs.Dirent objects, rather than strings or Buffers.

When a directory is read, such as with fs.readdir() or fs.opendir(), the file type of each entry is the type reported by the operating system and may depend on the file system; for example, some file systems may report a type that differs from what fs.lstat() returns. Node.js calls fs.lstat() on such an entry only when the reported type is unknown. Use fs.lstat() when an accurate file type is required.

dirent.isBlockDevice(): boolean

Returns true if the fs.Dirent object describes a block device.

dirent.isCharacterDevice(): boolean

Returns true if the fs.Dirent object describes a character device.

dirent.isDirectory(): boolean

Returns true if the fs.Dirent object describes a file system directory.

dirent.isFIFO(): boolean

Returns true if the fs.Dirent object describes a first-in-first-out (FIFO) pipe.

dirent.isFile(): boolean

Returns true if the fs.Dirent object describes a regular file.

dirent.isSocket(): boolean

Returns true if the fs.Dirent object describes a socket.

dirent.isSymbolicLink(): boolean

Returns true if the fs.Dirent object describes a symbolic link.

The file name that this fs.Dirent object refers to. The type of this value is determined by the options.encoding passed to fs.readdir() or fs.readdirSync().

The path to the parent directory of the file this fs.Dirent object refers to.

class fs.FSWatcher extends EventEmitter

A successful call to fs.watch() method will return a new fs.FSWatcher object.

All fs.FSWatcher objects emit a 'change' event whenever a specific watched file is modified.

Emitted when something changes in a watched directory or file. See more details in fs.watch().

The filename argument may not be provided depending on operating system support. If filename is provided, it will be provided as a Buffer if fs.watch() is called with its encoding option set to 'buffer', otherwise filename will be a UTF-8 string.

import { watch } from 'node:fs';
// Example when handled through fs.watch() listener
watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename);
    // Prints: <Buffer ...>
  }
});

Emitted when the watcher stops watching for changes. The closed fs.FSWatcher object is no longer usable in the event handler.

Emitted when an error occurs while watching the file. The errored fs.FSWatcher object is no longer usable in the event handler.

watcher.close(): void

Stop watching for changes on the given fs.FSWatcher. Once stopped, the fs.FSWatcher object is no longer usable.

watcher.ref(): fs.FSWatcher

When called, requests that the Node.js event loop not exit so long as the fs.FSWatcher is active. Calling watcher.ref() multiple times will have no effect.

By default, all fs.FSWatcher objects are "ref'ed", making it normally unnecessary to call watcher.ref() unless watcher.unref() had been called previously.

watcher.unref(): fs.FSWatcher

When called, the active fs.FSWatcher object will not require the Node.js event loop to remain active. If there is no other activity keeping the event loop running, the process may exit before the fs.FSWatcher object's callback is invoked. Calling watcher.unref() multiple times will have no effect.

class fs.StatWatcher extends EventEmitter

A successful call to fs.watchFile() method will return a new fs.StatWatcher object.

watcher.ref(): fs.StatWatcher

When called, requests that the Node.js event loop not exit so long as the fs.StatWatcher is active. Calling watcher.ref() multiple times will have no effect.

By default, all fs.StatWatcher objects are "ref'ed", making it normally unnecessary to call watcher.ref() unless watcher.unref() had been called previously.

watcher.unref(): fs.StatWatcher

When called, the active fs.StatWatcher object will not require the Node.js event loop to remain active. If there is no other activity keeping the event loop running, the process may exit before the fs.StatWatcher object's callback is invoked. Calling watcher.unref() multiple times will have no effect.

class fs.ReadStream extends stream.Readable

Instances of fs.ReadStream cannot be constructed directly. They are created and returned using the fs.createReadStream() function.

Emitted when the fs.ReadStream's underlying file descriptor has been closed.

Emitted when the fs.ReadStream's file descriptor has been opened.

Emitted when the fs.ReadStream is ready to be used.

Fires immediately after 'open'.

The number of bytes that have been read so far.

The path to the file the stream is reading from as specified in the first argument to fs.createReadStream(). If path is passed as a string, then readStream.path will be a string. If path is passed as a Buffer, then readStream.path will be a Buffer. If fd is specified, then readStream.path will be undefined.

This property is true if the underlying file has not been opened yet, i.e. before the 'ready' event is emitted.

A fs.Stats object provides information about a file.

Objects returned from fs.stat(), fs.lstat(), fs.fstat(), and their synchronous counterparts are of this type. If bigint in the options passed to those methods is true, the numeric values will be bigint instead of number, and the object will contain additional nanosecond-precision properties suffixed with Ns. Stat objects are not to be created directly using the new keyword.

Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,

  // Instances of Date
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT,

  // Instances of Temporal.Instant
  atimeInstant: 2011-10-10T23:24:11.0001Z,
  mtimeInstant: 2011-10-10T23:24:11.0001Z,
  ctimeInstant: 2011-10-10T23:24:11.0001Z,
  birthtimeInstant: 2011-10-10T23:24:11.0001Z
}

bigint version:

BigIntStats {
  dev: 2114n,
  ino: 48064969n,
  mode: 33188n,
  nlink: 1n,
  uid: 85n,
  gid: 100n,
  rdev: 0n,
  size: 527n,
  blksize: 4096n,
  blocks: 8n,
  atimeMs: 1318289051000n,
  mtimeMs: 1318289051000n,
  ctimeMs: 1318289051000n,
  birthtimeMs: 1318289051000n,
  atimeNs: 1318289051000000000n,
  mtimeNs: 1318289051000000000n,
  ctimeNs: 1318289051000000000n,
  birthtimeNs: 1318289051000000000n,

  // Instances of Date
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT,

  // Instances of Temporal.Instant
  atimeInstant: 2011-10-10T23:24:11Z,
  mtimeInstant: 2011-10-10T23:24:11Z,
  ctimeInstant: 2011-10-10T23:24:11Z,
  birthtimeInstant: 2011-10-10T23:24:11Z
}

stats.isBlockDevice(): boolean

Returns true if the fs.Stats object describes a block device.

stats.isCharacterDevice(): boolean

Returns true if the fs.Stats object describes a character device.

stats.isDirectory(): boolean

Returns true if the fs.Stats object describes a file system directory.

If the fs.Stats object was obtained from calling fs.lstat() on a symbolic link which resolves to a directory, this method will return false. This is because fs.lstat() returns information about a symbolic link itself and not the path it resolves to.

stats.isFIFO(): boolean

Returns true if the fs.Stats object describes a first-in-first-out (FIFO) pipe.

stats.isFile(): boolean

Returns true if the fs.Stats object describes a regular file.

stats.isSocket(): boolean

Returns true if the fs.Stats object describes a socket.

stats.isSymbolicLink(): boolean

Returns true if the fs.Stats object describes a symbolic link.

This method is only valid when using fs.lstat().

The numeric identifier of the device containing the file.

The file system specific "Inode" number for the file.

A bit-field describing the file type and mode.

The number of hard-links that exist for the file.

The numeric user identifier of the user that owns the file (POSIX).

The numeric group identifier of the group that owns the file (POSIX).

A numeric device identifier if the file represents a device.

The size of the file in bytes.

If the underlying file system does not support getting the size of the file, this will be 0.

The file system block size for i/o operations.

The number of blocks allocated for this file.

The timestamp indicating the last time this file was accessed expressed in milliseconds since the POSIX Epoch.

The timestamp indicating the last time this file was modified expressed in milliseconds since the POSIX Epoch.

The timestamp indicating the last time the file status was changed expressed in milliseconds since the POSIX Epoch.

The timestamp indicating the creation time of this file expressed in milliseconds since the POSIX Epoch.

Only present when bigint: true is passed into the method that generates the object. The timestamp indicating the last time this file was accessed expressed in nanoseconds since the POSIX Epoch.

Only present when bigint: true is passed into the method that generates the object. The timestamp indicating the last time this file was modified expressed in nanoseconds since the POSIX Epoch.

Only present when bigint: true is passed into the method that generates the object. The timestamp indicating the last time the file status was changed expressed in nanoseconds since the POSIX Epoch.

Only present when bigint: true is passed into the method that generates the object. The timestamp indicating the creation time of this file expressed in nanoseconds since the POSIX Epoch.

The timestamp indicating the last time this file was accessed.

The timestamp indicating the last time this file was modified.

The timestamp indicating the last time the file status was changed.

The timestamp indicating the creation time of this file.

The atimeMs, mtimeMs, ctimeMs, birthtimeMs properties are numeric values that hold the corresponding times in milliseconds. Their precision is platform specific. When bigint: true is passed into the method that generates the object, the properties will be bigints, otherwise they will be numbers.

The atimeNs, mtimeNs, ctimeNs, birthtimeNs properties are bigints that hold the corresponding times in nanoseconds. They are only present when bigint: true is passed into the method that generates the object. Their precision is platform specific.

atime, mtime, ctime, and birthtime are Date object alternate representations of the various times. The Date and number values are not connected. Assigning a new number value, or mutating the Date value, will not be reflected in the corresponding alternate representation.

The times in the stat object have the following semantics:

• atime "Access Time": Time when file data last accessed. Changed by the mknod(2), utimes(2), and read(2) system calls.
• mtime "Modified Time": Time when file data last modified. Changed by the mknod(2), utimes(2), and write(2) system calls.
• ctime "Change Time": Time when file status was last changed (inode data modification). Changed by the chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2), and write(2) system calls.
• birthtime "Birth Time": Time of file creation. Set once when the file is created. On file systems where birthtime is not available, this field may instead hold either the ctime or 1970-01-01T00:00Z (ie, Unix epoch timestamp 0). This value may be greater than atime or mtime in this case. On Darwin and other FreeBSD variants, also set if the atime is explicitly set to an earlier value than the current birthtime using the utimes(2) system call.

Prior to Node.js 0.12, the ctime held the birthtime on Windows systems. As of 0.12, ctime is not "creation time", and on Unix systems, it never was.

Provides information about a mounted file system.

Objects returned from fs.statfs() and its synchronous counterpart are of this type. If bigint in the options passed to those methods is true, the numeric values will be bigint instead of number.

StatFs {
  type: 1397114950,
  bsize: 4096,
  frsize: 4096,
  blocks: 121938943,
  bfree: 61058895,
  bavail: 61058895,
  files: 999,
  ffree: 1000000
}

bigint version:

StatFs {
  type: 1397114950n,
  bsize: 4096n,
  frsize: 4096n,
  blocks: 121938943n,
  bfree: 61058895n,
  bavail: 61058895n,
  files: 999n,
  ffree: 1000000n
}

Free blocks available to unprivileged users. Multiply by statfs.bsize to get the number of available bytes.

import { statfs } from 'node:fs/promises';

const stats = await statfs('/');
const availableBytes = stats.bsize * stats.bavail;
console.log(`Available space: ${availableBytes} bytes`);

const { statfs } = require('node:fs/promises');

(async () => {
  const stats = await statfs('/');
  const availableBytes = stats.bsize * stats.bavail;
  console.log(`Available space: ${availableBytes} bytes`);
})();

Free blocks in file system. Multiply by statfs.bsize to get the number of free bytes.

import { statfs } from 'node:fs/promises';

const stats = await statfs('/');
const freeBytes = stats.bsize * stats.bfree;
console.log(`Free space: ${freeBytes} bytes`);

const { statfs } = require('node:fs/promises');

(async () => {
  const stats = await statfs('/');
  const freeBytes = stats.bsize * stats.bfree;
  console.log(`Free space: ${freeBytes} bytes`);
})();

Total data blocks in file system. Multiply by statfs.bsize to get the total size in bytes.

import { statfs } from 'node:fs/promises';

const stats = await statfs('/');
const totalBytes = stats.bsize * stats.blocks;
console.log(`Total space: ${totalBytes} bytes`);

const { statfs } = require('node:fs/promises');

(async () => {
  const stats = await statfs('/');
  const totalBytes = stats.bsize * stats.blocks;
  console.log(`Total space: ${totalBytes} bytes`);
})();

Optimal transfer block size in bytes.

Fundamental file system block size.

Free file nodes in file system.

Total file nodes in file system.

Type of file system. A platform-specific numeric identifier for the type of file system. This value corresponds to the f_type field returned by statfs(2) on POSIX systems (for example, 0xEF53 for ext4 on Linux). Its meaning is OS-dependent and is not guaranteed to be consistent across platforms.

An optimized UTF-8 stream writer that allows for flushing all the internal buffering on demand. It handles EAGAIN errors correctly, allowing for customization, for example, by dropping content if the disk is busy.

The 'close' event is emitted when the stream is fully closed.

The 'drain' event is emitted when the internal buffer has drained sufficiently to allow continued writing.

The 'drop' event is emitted when the maximal length is reached and that data will not be written. The data that was dropped is passed as the first argument to the event handler.

The 'error' event is emitted when an error occurs.

The 'finish' event is emitted when the stream has been ended and all data has been flushed to the underlying file.

The 'ready' event is emitted when the stream is ready to accept writes.

The 'write' event is emitted when a write operation has completed. The number of bytes written is passed as the first argument to the event handler.

new fs.Utf8Stream(options?): fs.Utf8Stream

utf8Stream.destroy(): void

Close the stream immediately, without flushing the internal buffer.

utf8Stream.end(): void

Close the stream gracefully, flushing the internal buffer before closing.

utf8Stream.flush(callback): void

Writes the current buffer to the file if a write was not in progress. Do nothing if minLength is zero or if it is already writing.

utf8Stream.flushSync(): void

Flushes the buffered data synchronously. This is a costly operation.

utf8Stream.reopen(file): void

• file: string | Buffer | URL A path to a file to be written to (mode controlled by the append option).

Reopen the file in place, useful for log rotation.

utf8Stream.write(data): boolean

When the options.contentMode is set to 'utf8' when the stream is created, the data argument must be a string. If the contentMode is set to 'buffer', the data argument must be a Buffer.

utf8Stream[Symbol.dispose](): void

Calls utf8Stream.destroy().

This method enables the stream to be used with using, which will automatically destroy the stream when the scope exits. For more information, see the MDN documentation on using statements.

class fs.WriteStream extends stream.Writable

Instances of fs.WriteStream cannot be constructed directly. They are created and returned using the fs.createWriteStream() function.

Emitted when the fs.WriteStream's underlying file descriptor has been closed.

Emitted when the fs.WriteStream's file is opened.

Emitted when the fs.WriteStream is ready to be used.

Fires immediately after 'open'.

The number of bytes written so far. Does not include data that is still queued for writing.

writeStream.close(callback?): void

Closes writeStream. Optionally accepts a callback that will be executed once the writeStream is closed.

The path to the file the stream is writing to as specified in the first argument to fs.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.

This property is true if the underlying file has not been opened yet, i.e. before the 'ready' event is emitted.

Returns an object containing commonly used constants for file system operations.

The following constants are exported by fs.constants and fsPromises.constants.

Not every constant will be available on every operating system; this is especially important for Windows, where many of the POSIX specific definitions are not available. For portable applications it is recommended to check for their presence before use.

To use more than one constant, use the bitwise OR | operator.

Example:

import { open, constants } from 'node:fs';

const {
  O_RDWR,
  O_CREAT,
  O_EXCL,
} = constants;

open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => {
  // ...
});

The following constants are meant for use as the mode parameter passed to fsPromises.access(), fs.access(), and fs.accessSync().

The definitions are also available on Windows.

The following constants are meant for use with fs.copyFile().

The definitions are also available on Windows.

The following constants are meant for use with fs.open().

On Windows, only O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY, UV_FS_O_FILEMAP, UV_FS_O_TEMPORARY, UV_FS_O_SHORT_LIVED, UV_FS_O_SEQUENTIAL, and UV_FS_O_RANDOM are available.

The following constants are meant for use with the fs.Stats object's mode property for determining a file's type.

On Windows, only S_IFCHR, S_IFDIR, S_IFLNK, S_IFMT, and S_IFREG, are available.

The following constants are meant for use with the fs.Stats object's mode property for determining the access permissions for a file.

On Windows, only S_IRUSR and S_IWUSR are available.