function

fs.promises.opendir

function opendir(

path: PathLike,

options?: OpenDirOptions

): Promise<Dir>;

Asynchronously open a directory for iterative scanning. See the POSIX opendir(3) documentation for more detail.

Creates an fs.Dir, which contains all further functions for reading from and cleaning up the directory.

The encoding option sets the encoding for the path while opening the directory and subsequent read operations.

Example using async iteration:

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.

@returns

Fulfills with an {fs.Dir}.

Referenced types

type PathLike = string | Buffer | URL

Valid types for path values in "fs".

interface OpenDirOptions

bufferSize?: number
Number of directory entries that are buffered internally when reading from the directory. Higher values lead to better performance but higher memory usage.
encoding?: BufferEncoding
recursive?: boolean

class Dir

A class representing a directory stream.

Created by opendir, 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.

readonly path: string
The read-only path of this directory as was provided to opendir,opendirSync, or fsPromises.opendir().
[Symbol.asyncDispose](): Promise<void>;
Calls dir.close() if the directory handle is open, and returns a promise that fulfills when disposal is complete.
[Symbol.asyncIterator](): AsyncIterator<Dirent<string>>;
Asynchronously iterates over the directory via readdir(3) until all entries have been read.
[Symbol.dispose](): void;
Calls dir.closeSync() if the directory handle is open, and returns undefined.
close(): Promise<void>;
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.
close(
cb: NoParamCallback
): void;
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.
closeSync(): void;
Synchronously close the directory's underlying resource handle. Subsequent reads will result in errors.
read(): Promise<null | Dirent<string>>;
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.
@returns
containing {fs.Dirent|null}
read(
cb: (err: null | ErrnoException, dirEnt: null | Dirent<string>) => void
): void;
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.
@returns
containing {fs.Dirent|null}
readSync(): null | Dirent<string>;
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.