Directory

Description

Represents a directory on disk that can be traversed or watched for changes.

API documentation

Construction

::constructor(directoryPath, symlink)

Configures a new Directory instance.

No files are accessed. The directory does not yet need to exist.

Argument Description
directoryPath

A String containing the absolute path to the directory.
symlink optional

A Boolean indicating if the path is a symlink (default: false).

::create(mode)

Creates the directory on disk that corresponds to Directory::getPath if no such directory already exists.

Argument Description
mode optional

Number that defaults to 0777 and represents the default permissions of the directory on supported platforms.
Return values

  • Returns a Promise that resolves to a Boolean: true if the directory was created and false if it already existed.

Event Subscription

::onDidChange(callback)

Invoke the given callback when the directory’s contents change.

A directory’s contents are considered to have changed when one of its children is added, deleted, or renamed. This callback will not fire when one of its children has its contents changed.

Argument Description
callback

Function to be called when the directory’s contents change. Takes no arguments.
Return values

::isFile()

Return values

::isDirectory()

Return values

::isSymbolicLink()

Return values

  • Returns a Boolean indicating whetehr or not this is a symbolic link.

::exists()

Return values

  • Returns a Promise that resolves to a Boolean: true if the directory exists, false otherwise.

::existsSync()

Return values

  • Returns a Boolean: true if the directory exists, false otherwise.

::isRoot()

Return values

  • Returns a Boolean: true if this Directory is the root directory of the filesystem, or false if it isn’t.

Managing Paths

::getPath()

This may include unfollowed symlinks or relative directory entries; or it may be fully resolved. It depends on what you give it. Anything that Node’s builtin fs and path libraries can resolve will also be understood by Directory.

Return values

  • Returns the directory’s String path.

::getRealPathSync()

This will always be an absolute path; all relative paths are resolved and all symlinks are followed.

Return values

  • Returns the directory’s resolved String path, resolving symlinks if necessary.

::getBaseName()

Return values

  • Returns the String basename of the directory.

::relativize(fullPath)

Argument Description
fullPath

A path to compare against the real, absolute path of this Directory.
Return values

  • Returns the relative String path to the given path from this directory. If the given path is not a descendant of this directory, will return its full absolute path.

::resolve(uri)

Resolves the given relative path to an absolute path relative to this directory. If the path is already absolute or prefixed with a URI scheme, it is returned unchanged.

Argument Description
uri

A String containing the path to resolve.
Return values

  • Returns a String containing an absolute path, or undefined if the given URI is falsy (like an empty string).

Traversing

::getParent()

Traverse to the parent directory.

Return values

::getFile(filename)

Traverse within this Directory to a child File. This method doesn't actually check to see if the File exists; it just creates the File object.

You can also access descendant files by passing multiple arguments. In this usage, the final segment should be the name of a file; the others should be directories.

Argument Description
filename

The String name of a File within this Directory.
Return values

::getSubdirectory(dirname)

Traverse within this Directory to a child Directory. This method doesn't actually check to see if the directory exists; it just creates the Directory object.

You can also access descendant directories by passing multiple arguments. In this usage, all segments should be directory names.

Argument Description
dirname

The String name of the child Directory.
Return values

::getEntries(callback)

Reads file entries in this directory from disk asynchronously and applies a function to each.

Argument Description
callback

A Function to call with the following arguments:
error

An Error, may be null.
entries

An Array of File and Directory objects.

::getEntriesSync()

Reads file entries in this directory from disk synchronously.

Return values

::contains(pathToCheck)

Determines if the given path (real or symbolic) is inside this directory. This method does not actually check if the path exists; it just checks if the path is under this directory.

Argument Description
pathToCheck

The String path to check.
Return values

  • Returns a Boolean whether the given path is inside this directory.