Object “fs”

Object > NativeObject > FileSystem

The fs object provides methods to read and write files. All methods are asynchronous and return a promise.

Type: FileSystem extends NativeObject
Constructor: private
Singleton: fs
Namespace: tabris
Direct subclasses: None
JSX Support: No

Examples

JavaScript

import {fs} from 'tabris';

fs.writeFile(fs.cacheDir + '/file.txt', 'Hello World!')
  .then(() => console.log('File written successfully'))
  .catch(error => console.error(error));

See also:

JSX Using the file system to read and write files
JSX Opening files and showing their properties

Methods

appendToFile(path, data)

Writes the given binary content to the given file. If the file exists, it is appended, otherwise it is created. Returns a promise that resolves with true if a new file was created, or with false if the file already existed. It rejects with an Error if the path points to a directory.

Parameter Type Description
path string The path of the file to append.
data ArrayBuffer | Blob The content to append to the file.

Returns: Promise<boolean>

appendToFile(path, text, encoding?)

Writes the given text to the given file using the given encoding or utf-8 if no encoding is specified. If the file exists, it is appended, otherwise it is created. Returns a promise that resolves with true if a new file was created, or with false if the file already existed. It rejects with an Error if the path points to a directory.

Parameter Type Description
path string The path of the file to append.
text string The text to write to the file.
encoding string The encoding to use to write a text file. When omitted, utf-8 will be used. Optional.

Returns: Promise<boolean>

createDir(path)

Creates a directory on the given path, including intermediate directories. Returns a promise that resolves with true if the directory was created, or with false if it already existed. If the path points to a file the promise rejects.

Parameter Type Description
path string The path of the directory to create.

Returns: Promise<boolean>

isDir(path)

Returns true if there is a directory at the given path. Otherwise (no directory, or is a file) it returns false.

Parameter Type Description
path string The path of the directory.

Returns: boolean

isFile(path)

Returns true if there is a file at the given path. Otherwise (no file, or is a directory) it returns false.

Parameter Type Description
path string The path of the file.

Returns: boolean

openFile(options?)

Allows to select a file via a native file picker ui. The supplied options object provides additional configuration parameters to adjust the picker behavior.

Once the picker ui is closed the returned promise resolves with an array of File objects or an empty array if no file has been selected.

Parameter Type Description
options {
  type: string, // A mime type to only select a certain category of files. Eg. `'image/png'` or `image/*`. defaults to */*
  quantity: // The number of files to select. defaults to single
'single' | 'multiple'
}		 An optional set of configuration parameters. Optional.

Returns: Promise<File[]>

readDir(path)

Reads the contents of a given directory. Returns a promise that resolves on success to an array of the names of the files in the directory excluding ‘.’ and ‘..’. If no directory exists at that path the Promise rejects with an error object.

Parameter Type Description
path string The path of the directory to read.

Returns: Promise<string[]>

readFile(path)

Reads the given file and returns a promise that resolves to the contents of the file on success and rejects with an error object if no file exists at that path. The file contents are returned as an ArrayBuffer.

Parameter Type Description
path string The path of the file to read.

Returns: Promise<ArrayBuffer>

readFile(path, encoding)

Reads the given text file and returns a promise that resolves to the contents of the file on success and rejects with an Error if no file exists at that path. The file contents are returned as a string.

Parameter Type Description
path string The path of the file to read.
encoding string The encoding to use to read text files.

Returns: Promise<string>

remove(path)

Removes the given file or directory. If the directory is not empty all its contents will also be deleted. If there is no file or directory at the given path nothing will happen. Returns a promise that resolves with true if something was deleted, otherwise false. Rejects with an error object only in case of an access error.

Parameter Type Description
path string The path to the file or directory to remove.

Returns: Promise<boolean>

removeDir(path)

Removes the given directory if it exists. If the directory is not empty all its contents will also be deleted. Returns a promise that resolves if the directory was deleted or none existed at that path. If the path points to a file the promise rejects.

Parameter Type Description
path string The path of the directory to remove. Must be empty.

Returns: Promise<undefined>

removeFile(path)

Removes the given file if it exists. Returns a promise that resolves with true on success or with false if no directory exists at that path. If the path points to a directory the promise rejects.

Parameter Type Description
path string The path of the file to remove.

Returns: Promise<undefined>

writeFile(path, data)

Writes the given binary contents to the given file. If the file exists, it is overwritten, otherwise it is created. Returns a promise that resolves on success and rejects with an Error in case of a failure.

Parameter Type Description
path string The path of the file to write.
data ArrayBuffer | Blob The contents to write to the file.

Returns: Promise<undefined>

writeFile(path, text, encoding?)

Writes the given text to the given file using the given encoding or utf-8 if no encoding is specified. If the file exists, it is overwritten, otherwise it is created. Returns a promise that resolves on success and rejects with an Error in case of a failure.

Parameter Type Description
path string The path of the file to write.
text string The text to write to the file.
encoding string The encoding to use to write a text file. When omitted, utf-8 will be used. Optional.

Returns: Promise<undefined>

Properties

cacheDir

An external path of a directory that the app may use to store cached files. External storage may be any type like permanent internal disc storage, sd-card or a usb stick. The OS may delete files in this directory when the device runs low on storage. Only use this location for data that can easily be re-created.

Type: string
Settable: No
Change Event: Not supported

externalCacheDirs

iOSAndroid

An list of external paths that the app may use to store cached files. External storage may be any type storage type like permanent internal disc storage, sd-card or a usb stick. In case no type of external storage is available the list will be empty.

The OS may delete files in this directory when the device runs low on storage. Only use this location for data that can easily be re-created.

Type: string[]
Settable: No
Change Event: Not supported

externalFileDirs

iOSAndroid

A list of external paths that the app may use to store persistent files. External storage may be any storage type like permanent internal disc storage, sd-card or a usb stick. In case no type of external storage is available the list will be empty.

This is not the directory that contains the files bundled with the project, e.g. images, js files, package.json. You can access these files using the fetch or XMLHttpRequest APIs.

Type: string[]
Settable: No
Change Event: Not supported

filesDir

The path of a directory that the app may use to store persistent files. This is not the directory that contains the files bundled with the project, e.g. images, js files, package.json. You can access these files using the fetch or XMLHttpRequest APIs.

Type: string
Settable: No
Change Event: Not supported

See Also

Get involved

Help us improve Tabris.js!

Install the app

Use the Tabris.js app to try examples and run your own snippets.