host.fs

The filesystem interface reads and writes files, inspects metadata, and traverses directories on the selected client.

Here, host is a selected RemoteHost; see host discovery to obtain one. The module overview covers permissions and shared errors.

Paths use the client's native syntax; relative paths start at its startup directory. All methods require fs.enabled. Writing, creating, and deleting additionally require fs.allow_write; see permissions.

host.fs.readFile(path)

Function: reads the complete original bytes of a file.

Parameters: required path: string, the file path.

Return value: Promise<Uint8Array>. The complete file requires corresponding JavaScript memory.

host.fs.readTextFile(path)

Function: reads a complete file and decodes UTF-8, replacing malformed sequences.

Parameters: required path: string, the file path.

Return value: Promise<string>.

host.fs.readDir(path)

Function: reads directory entries on demand.

Parameters: required path: string, the directory path.

Return value: AsyncIterableIterator<DirEntry>, rather than a promise. Each entry has name: string and boolean fields isFile, isDirectory, and isSymlink. The first next() opens the directory; exhaustion, return(), or break releases its cursor.

host.fs.stat(path)

Function: reads file or directory information, following permitted symbolic links.

Parameters: required path: string.

Return value: Promise<FileInfo>, containing:

host.fs.writeFile(path, data, options?)

Function: writes bytes to a file. Chunks take effect immediately; a later failure does not roll back completed writes.

Parameters: required path: string and data: Uint8Array; optional options?: WriteOptions below. Parent directories are not created automatically.

Return value: Promise<void>.

host.fs.writeTextFile(path, data, options?)

Function: encodes a string as UTF-8 and writes it to a file.

Parameters: required path: string and data: string; options?: WriteOptions as for writeFile().

Return value: Promise<void>, with the same write and failure behavior as writeFile().

host.fs.mkdir(path, options?)

Function: creates a directory.

Parameters: required path: string; options?: { recursive?: boolean }, default recursive: false. True creates missing parent directories.

Return value: Promise<void>.

host.fs.remove(path, options?)

Function: deletes a file or directory.

Parameters: required path: string; options?: { recursive?: boolean }, default recursive: false. Deleting a nonempty directory requires recursion.

Return value: Promise<void>.

See remote.d.ts for type declarations.