File Extended

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

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

Returns a Boolean, always true.

::isDirectory()

Return values

Returns a Boolean, always false.

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

Returns a String.

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