File

Description

Represents an individual file that can be watched, read from, and written to.

API documentation

Construction

::constructor(filePath, symlink)

Configures a new File instance.

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

Argument Description
filePath

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

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

::create()

Creates the file on disk that corresponds to File::getPath if no such file already exists.

Return values

  • Returns a Promise that resolves once the file is created on disk. It resolves to a boolean value that is true if the file was created or false if it already existed.

Event Subscription

::onDidChange(callback)

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

Argument Description
callback

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

::onDidRename(callback)

Invoke the given callback when the file’s path changes.

Argument Description
callback

Function to be called when the file’s path changes. Takes no arguments.
Return values

::onDidDelete(callback)

Invoke the given callback when the file is deleted.

Argument Description
callback

Function to be called when the file is deleted. Takes no arguments.
Return values

File Metadata

::isFile()

Return values

::isDirectory()

Return values

::isSymbolicLink()

Return values

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

::exists()

Return values

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

::existsSync()

Return values

  • Returns a Boolean: true if the file exists; false otherwise.

::getDigest()

Get the SHA-1 digest of this file.

Return values

::getDigestSync()

Get the SHA-1 digest of this file.

Return values

::setEncoding()

Sets the file's character set encoding name.

Supports utf8 natively and whichever other encodings are supported by the iconv-lite package.

::getEncoding()

Return values

  • Returns the String encoding name for this file; default is utf8.

Managing Paths

::getPath()

Return values

  • Returns the String path for this file.

::setPath(path)

Sets the path for the file.

This should not normally need to be called; use it only when you know a file’s path has changed and you don’t want to rely on the internal renaming detection.

Argument Description
path

String The new path to set; should be absolute.

::getRealPath()

Return values

  • Returns a Promise that resolves to this file’s completely resolved String path, following symlinks if necessary.

::getRealPathSync()

Return values

  • Returns this file’s completely resolved String path, following symlinks if necessary.

::getBaseName()

Return values

  • Returns the String filename of this file without its directory context.

Traversing

::getParent()

Return values

  • Returns the Directory that contains this file.

Reading and Writing

::read(flushCache)

Reads the contents of the file.

Argument Description
flushCache

A Boolean indicating whether to require a direct read or if a cached copy is acceptable.
Return values

  • Returns a Promise that resolves to a String (if the file exists) or null (if it does not).

::readSync(flushCache)

Reads the contents of the file synchronously.

Argument Description
flushCache

A Boolean indicating whether to require a direct read or if a cached copy is acceptable.
Return values

  • Returns a String (if the file exists) or null (if it does not).

::createReadStream()

Return values

  • Returns a stream to read the content of the file.

  • Returns a ReadStream object.

::write(text)

Overwrites the file with the given text.

Argument Description
text

The String text to write to the underlying file.
Return values

  • Returns a Promise that resolves when the file has been written.

::writeSync(text)

Overwrites the file with the given text.

Argument Description
text

The String text to write to the underlying file.

::createWriteStream()

Return values

  • Returns a stream to write content to the file.

  • Returns a WriteStream object.