Filesystem

Filesystem provides cross-platform access to various posix filesystem methods. It replicates NodeJS interfaces for the most part to enable compatibility with NodeJS code, however it is not fully compatible, for example when dealing with encodings. Also, unlike NodeJS, only asynchronous methods are available.

This module also provides various offers to provide the user with options for sharing files with other applications and storing them in the cloud / protected areas of the user’s filesystem.

Filesystem is accessible via requiring the fs module.

Methods

fs.readFile(path[, encoding], callback)

Reads the contents of a file from the filesystem into memory.

If an encoding is specified (only ‘utf8’ is currently supported), a string containing the contents of the file will be returned. Otherwise, a Buffer object will be returned.

On success, the callback will be invoked, with the first argument containing undefined, and the second argument containing the contents of the file.

On error, the callback will be invoked with a single argument containing a human-unfriendly error.

fs.exists(path, callback)

Determines if the specified path points to a file or folder.

On success, the callback will be invoked, with the first argument containing undefined, and the second argument containing true if the file exists, otherwise false.

On error, the callback will be invoked with a single argument containing a human-unfriendly error.

Creates a symlink from existingPath to newPath.

The type flag would normally be used to indicate whether a soft or hard link should be created, however it is not currently supported. Only soft links can be created by this method at present.

On error, the callback will be invoked with a single argument containing a human-unfriendly error, otherwise the callback will be invoked with no arguments.

Resolves a symlink to its real location on the filesystem.

On success, the callback will be invoked, with the first argument containing undefined, and the second argument containing the path to the underlying file.

On error, the callback will be invoked with a single argument containing a human-unfriendly error.

fs.realpath(relativePath, callback)

Resolves a relative path to its absolute path. This method assumes any relative path is relative to the working directory of the application, which is in most cases the application’s own installation directory.

On success, the callback will be invoked, with the first argument containing undefined, and the second argument containing an absolute path.

On error, the callback will be invoked with a single argument containing a human-unfriendly error.

fs.rename(oldPath, newPath, callback)

Renames a file. Just like in POSIX, this also achieves the same result as ‘moving’ a file.

On error, the callback will be invoked with a single argument containing a human-unfriendly error, otherwise the callback will be invoked with no arguments.

fs.rmdir(path, callback)

Removes a directory. Just like in POSIX, if the directory is not empty this call will fail.

On error, the callback will be invoked with a single argument containing a human-unfriendly error, otherwise the callback will be invoked with no arguments.

fs.truncate(path, callback)

Removes all of the content from the specified file.

On error, the callback will be invoked with a single argument containing a human-unfriendly error, otherwise the callback will be invoked with no arguments.

Deletes the specified file.

On error, the callback will be invoked with a single argument containing a human-unfriendly error, otherwise the callback will be invoked with no arguments.

fs.writeFile(path, data, callback)

Writes the specified data to the specified path. The data parameter can either be a string or a Buffer object. Unlike NodeJS, specifying an encoding is not supported and ‘utf8’ is assumed to be the requested encoding.

On error, the callback will be invoked with a single argument containing a human-unfriendly error, otherwise the callback will be invoked with no arguments.

fs.mkdir(path, callback)

Creates a directory. Just like in POSIX, if the directory already exists this call will fail.

On error, the callback will be invoked with a single argument containing a human-unfriendly error, otherwise the callback will be invoked with no arguments.

fs.mkdtemp(prefix, callback)

Creates a unique temporary directory.

On success, the callback will be invoked, with the first argument containing undefined, and the second argument containing an absolute path to the new temporary directory.

On error, the callback will be invoked with a single argument containing a human-unfriendly error.

fs.readdir(path, callback)

Reads the list of files and folders within the specified path.

On success, the callback will be invoked, with the first argument containing undefined, and the second argument containing an Array of relative paths to files and folders within that directory.

On error, the callback will be invoked with a single argument containing a human-unfriendly error.

fs.offerCopyToLocation(location, localPath, callback)

Creates an Offer for the user to copy the specified file to a common user location.

The directory parameter can be any of the following properties from the fs.Location enum:

  • Any - usually results in a file browser appearing with the option of choosing a destination for the new file
  • Documents - results in either a file browser appearing as with Any, or directly saving to documents depending on platform
  • CameraRoll - results in either a file browser appearing as with Any, or a native OS photo save dialog appearing
  • Cloud - usually results in the file immediately uploading to cloud storage, may present a specific file browser

The localPath parameter should point to the path of a file in an internal application directory such as os.homeDirectory or os.tmpdir.

The callback will be invoked with an Offer object indicating the result of the operation. No extra fields are present in the offer details.

fs.offerCopyFromLocation(directory, localPath, callback)

Creates an Offer for the user to copy a file from a common user location.

The location parameter can be any of the following properties from the fs.Location enum:

  • Any - usually results in a file browser appearing with the option of choosing a file
  • Documents - results in a file browser appearing as with Any
  • CameraRoll - results in either a file browser appearing as with Any, or a native OS photo picker dialog appearing
  • Cloud - results in a file browser appearing as with Any

The localPath parameter should point to the path where the file should be copied in an internal application directory such as os.homeDirectory or os.tmpdir.

The callback will be invoked with an Offer object indicating the result of the operation. No extra fields are present in the offer details.

Properties

fs.constants

These constants mirror the ones provided by NodeJS. They’re not currently made use of but they may be in the future.