function

fs.promises.readdir

function readdir(
path: PathLike,
options?: null | BufferEncoding | ObjectEncodingOptions & { recursive: boolean; withFileTypes: false }
): Promise<string[]>;

Reads the contents of a directory.

The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the filenames. If the encoding is set to 'buffer', the filenames returned will be passed as Buffer objects.

If options.withFileTypes is set to true, the returned array will contain fs.Dirent objects.

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

try {
  const files = await readdir(path);
  for (const file of files)
    console.log(file);
} catch (err) {
  console.error(err);
}
@returns

Fulfills with an array of the names of the files in the directory excluding '.' and '..'.

function readdir(
path: PathLike,
options: 'buffer' | { encoding: 'buffer'; recursive: boolean; withFileTypes: false }
): Promise<NonSharedBuffer[]>;

Asynchronous readdir(3) - read a directory.

@param path

A path to a file. If a URL is provided, it must use the file: protocol.

@param options

The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, 'utf8' is used.

function readdir(
path: PathLike,
options?: null | BufferEncoding | ObjectEncodingOptions & { recursive: boolean; withFileTypes: false }
): Promise<string[] | NonSharedBuffer[]>;

Asynchronous readdir(3) - read a directory.

@param path

A path to a file. If a URL is provided, it must use the file: protocol.

@param options

The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, 'utf8' is used.

function readdir(
path: PathLike,
options: ObjectEncodingOptions & { recursive: boolean; withFileTypes: true }
): Promise<Dirent<string>[]>;

Asynchronous readdir(3) - read a directory.

@param path

A path to a file. If a URL is provided, it must use the file: protocol.

@param options

If called with withFileTypes: true the result data will be an array of Dirent.

function readdir(
path: PathLike,
options: { encoding: 'buffer'; recursive: boolean; withFileTypes: true }
): Promise<Dirent<NonSharedBuffer>[]>;

Asynchronous readdir(3) - read a directory.

@param path

A path to a directory. If a URL is provided, it must use the file: protocol.

@param options

Must include withFileTypes: true and encoding: 'buffer'.

Referenced types

type PathLike = string | Buffer | URL

Valid types for path values in "fs".

interface ObjectEncodingOptions

class Dirent<Name extends string | Buffer = string>

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 readdir or readdirSync is called with the withFileTypes option set to true, the resulting array is filled with fs.Dirent objects, rather than strings or Buffer s.

  • name: Name

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

  • parentPath: string

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

  • isBlockDevice(): boolean;

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

  • isCharacterDevice(): boolean;

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

  • isDirectory(): boolean;

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

  • isFIFO(): boolean;

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

  • isFile(): boolean;

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

  • isSocket(): boolean;

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