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.

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 ::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.
Return values

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

::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.
Return values

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

::onDidDelete(callback)

Invoke the given callback when the file is deleted.

Argument Description
callback

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

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

::onWillThrowWatchError(callback)

Invoke the given callback when there is an error with the watch. When your callback has been invoked, the file will have unsubscribed from the file watches.

Argument Description
callback

Function callback
errorObject

Object
error

Object the error object
handle

Function call this to indicate you have handled the error. The error will not be thrown if this function is called.

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

  • Returns a promise that resolves to a String.

::getDigestSync()

Get the SHA-1 digest of this file

Return values

::setEncoding(encoding)

Sets the file's character set encoding name.

Argument Description
encoding

The String encoding to use (default: 'utf8')

::getEncoding()

Return values

  • Returns the String encoding name for this file (default: 'utf8').

Managing Paths

::getPath()

Return values

  • Returns the String path for the file.

::getRealPathSync()

Return values

  • Returns this file's completely resolved String path.

::getRealPath()

Return values

  • Returns a promise that resolves to the file's completely resolved String path.

::getBaseName()

Return the String filename without any directory information.

Traversing

::getParent()

Return 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 either a String, or null if the file does not exist.

::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.

::createWriteStream()

Return values

  • Returns a stream to write content to the file.

  • Returns a WriteStream object.

::writeSync(text)

Overwrites the file with the given text.

Argument Description
text

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

  • Returns undefined.