API Reference

Classes

Fs

The fs class is used for interacting with the file system.

All file paths must be POSIX file paths (/ instead of ), and will be normalized to the target platform if running on Windows.

Initializers

bring fs;

new fs.Util();

Name	Type	Description

---

Static Functions

Name	Description
absolute	The right-most parameter is considered {to}. Other parameters are considered an array of {from}.
appendFile	Appends new data to the end of an existing file.
basename	Retrieve the final segment of a given file path.
dirname	Retrieve the name of the directory from a given file path.
exists	Check if the path exists.
extension	Extracts the extension (without the leading dot) from the path, if possible.
glob	Match files using the patterns the shell uses.
isDir	Checks if the given path is a directory and exists.
join	Join all arguments together and normalize the resulting path.
md5	Calculate an MD5 content hash of all the files that match a glob pattern.
metadata	Gets the stats of the given path.
mkdir	Create a directory.
mkdtemp	Create a temporary directory.
readBytes	Read the contents of the file as bytes.
readdir	Read the contents of the directory.
readFile	Read the entire contents of a file.
readJson	Read the contents of the file and convert it to JSON.
readYaml	Convert all YAML objects from a single file into JSON objects.
relative	Solve the relative path from {from} to {to} based on the current working directory.
remove	Remove files and directories (modeled on the standard POSIX rmutility).
setPermissions	Set the permissions of the file, directory, etc.
symlink	Creates a symbolic link.
symlinkMetadata	Gets the stats of the given path without following symbolic links.
tryReadBytes	If the file exists, read the contents of the file as bytes;
tryReaddir	If the path exists, read the contents of the directory;
tryReadFile	If the file exists and can be read successfully, read the entire contents;
tryReadJson	Retrieve the contents of the file and convert it to JSON if the file exists and can be parsed successfully, otherwise, return undefined.
tryReadYaml	Convert all YAML objects from a single file into JSON objects if the file exists and can be parsed successfully, undefined otherwise.
writeBytes	Write bytes to a file, replacing the file if it already exists.
writeFile	Writes data to a file, replacing the file if it already exists.
writeJson	Writes JSON to a file, replacing the file if it already exists.
writeYaml	Writes multiple YAML objects to a file, replacing the file if it already exists.

---

absolute

bring fs;

fs.absolute(...paths: Array<str>);

The right-most parameter is considered {to}. Other parameters are considered an array of {from}.

Starting from leftmost {from} parameter, resolves {to} to an absolute path.

If {to} isn't already absolute, {from} arguments are prepended in right to left order, until an absolute path is found. If after using all {from} paths still no absolute path is found, the current working directory is used as well. The resulting path is normalized, and trailing slashes are removed unless the path gets resolved to the root directory.

paths^Required

• Type: str

A sequence of paths or path segments.

---

appendFile

bring fs;

fs.appendFile(filepath: str, data: str, options?: WriteFileOptions);

Appends new data to the end of an existing file.

filepath^Required

• Type: str

The file path that needs to be appended.

---

data^Required

• Type: str

The text to be appended to the file.

---

options^Optional

• Type: WriteFileOptions

The encoding can be set to specify the character encoding.

And the flag can be set to specify the attributes. If a flag is not provided, it defaults to "w".

---

basename

bring fs;

fs.basename(path: str);

Retrieve the final segment of a given file path.

path^Required

• Type: str

The path to evaluate.

---

dirname

bring fs;

fs.dirname(path: str);

Retrieve the name of the directory from a given file path.

path^Required

• Type: str

The path to evaluate.

---

exists

bring fs;

fs.exists(path: str);

Check if the path exists.

path^Required

• Type: str

The path to evaluate.

---

extension

bring fs;

fs.extension(path: str);

Extracts the extension (without the leading dot) from the path, if possible.

path^Required

• Type: str

The path to get extension for.

---

glob

bring fs;

fs.glob(pattern: str, options?: GlobOptions);

Match files using the patterns the shell uses.

Built with the great glob package, based on https://www.npmjs.com/package/glob

pattern^Required

• Type: str

The pattern to match.

---

options^Optional

• Type: GlobOptions

Glob options.

---

isDir

bring fs;

fs.isDir(path: str);

Checks if the given path is a directory and exists.

path^Required

• Type: str

The path to check.

---

join

bring fs;

fs.join(...paths: Array<str>);

Join all arguments together and normalize the resulting path.

paths^Required

• Type: str

The array of path need to join.

---

md5

bring fs;

fs.md5(dir: str, globPattern?: str);

Calculate an MD5 content hash of all the files that match a glob pattern.

dir^Required

• Type: str

The root directory.

---

globPattern^Optional

• Type: str

The glob pattern to match (defaults to all files and subdirectories).

---

metadata

bring fs;

fs.metadata(path: str);

Gets the stats of the given path.

path^Required

• Type: str

The path to get stats for.

---

mkdir

bring fs;

fs.mkdir(dirpath: str, opts?: MkdirOptions);

Create a directory.

dirpath^Required

• Type: str

The path to the directory you want to create.

---

opts^Optional

• Type: MkdirOptions

---

mkdtemp

bring fs;

fs.mkdtemp(prefix?: str);

Create a temporary directory.

Generates six random characters to be appended behind a required prefix to create a unique temporary directory.

prefix^Optional

• Type: str

The prefix for the directory to be created, default wingtemp.

---

readBytes

bring fs;

fs.readBytes(filepath: str);

Read the contents of the file as bytes.

filepath^Required

• Type: str

The file path.

---

readdir

bring fs;

fs.readdir(dirpath: str);

Read the contents of the directory.

dirpath^Required

• Type: str

The path to evaluate.

---

readFile

bring fs;

fs.readFile(filepath: str, options?: ReadFileOptions);

Read the entire contents of a file.

filepath^Required

• Type: str

The path of the file to be read.

---

options^Optional

• Type: ReadFileOptions

The encoding can be set to specify the character encoding.

And the flag can be set to specify the attributes. If a flag is not provided, it defaults to "r".

---

readJson

bring fs;

fs.readJson(filepath: str);

Read the contents of the file and convert it to JSON.

filepath^Required

• Type: str

The file path of the JSON file.

---

readYaml

bring fs;

fs.readYaml(filepath: str);

Convert all YAML objects from a single file into JSON objects.

filepath^Required

• Type: str

The file path of the YAML file.

---

relative

bring fs;

fs.relative(from: str, to: str);

Solve the relative path from {from} to {to} based on the current working directory.

At times we have two absolute paths, and we need to derive the relative path from one to the other.

from^Required

• Type: str

---

to^Required

• Type: str

---

remove

bring fs;

fs.remove(path: str, opts?: RemoveOptions);

Remove files and directories (modeled on the standard POSIX rmutility).

Returns undefined.

path^Required

• Type: str

The path to the file or directory you want to remove.

---

opts^Optional

• Type: RemoveOptions

---

setPermissions

bring fs;

fs.setPermissions(path: str, permissions: str);

Set the permissions of the file, directory, etc.

Expects a permission string like "755" or "644".

path^Required

• Type: str

The path of the file or directory.

---

permissions^Required

• Type: str

The mode to set as a string.

---

symlink

bring fs;

fs.symlink(target: str, path: str, type?: SymlinkType);

Creates a symbolic link.

target^Required

• Type: str

The path to the target file or directory.

---

path^Required

• Type: str

The path to the symbolic link to be created.

---

type^Optional

• Type: SymlinkType

The type of the target.

It can be FILE, DIRECTORY, or JUNCTION (Windows only). Defaults to FILE if not specified.

---

symlinkMetadata

bring fs;

fs.symlinkMetadata(path: str);

Gets the stats of the given path without following symbolic links.

path^Required

• Type: str

The path to get stats for.

---

tryReadBytes

bring fs;

fs.tryReadBytes(filepath: str);

If the file exists, read the contents of the file as bytes;

otherwise, return undefined.

filepath^Required

• Type: str

The file path.

---

tryReaddir

bring fs;

fs.tryReaddir(dirpath: str);

If the path exists, read the contents of the directory;

otherwise, return undefined.

dirpath^Required

• Type: str

The path to evaluate.

---

tryReadFile

bring fs;

fs.tryReadFile(filepath: str, options?: ReadFileOptions);

If the file exists and can be read successfully, read the entire contents;

otherwise, return undefined.

filepath^Required

• Type: str

The path of the file to be read.

---

options^Optional

• Type: ReadFileOptions

The encoding can be set to specify the character encoding, or the flag can be set to specify the attributes.

---

tryReadJson

bring fs;

fs.tryReadJson(filepath: str);

Retrieve the contents of the file and convert it to JSON if the file exists and can be parsed successfully, otherwise, return undefined.

filepath^Required

• Type: str

The file path of the JSON file.

---

tryReadYaml

bring fs;

fs.tryReadYaml(filepath: str);

Convert all YAML objects from a single file into JSON objects if the file exists and can be parsed successfully, undefined otherwise.

filepath^Required

• Type: str

The file path of the YAML file.

---

writeBytes

bring fs;

fs.writeBytes(filepath: str, data: Bytes, options?: WriteFileOptions);

Write bytes to a file, replacing the file if it already exists.

filepath^Required

• Type: str

The file path that needs to be written.

---

data^Required

• Type: Bytes

The bytes to write.

---

options^Optional

• Type: WriteFileOptions

The encoding can be set to specify the character encoding.

And the flag can be set to specify the attributes. If a flag is not provided, it defaults to "w".

---

writeFile

bring fs;

fs.writeFile(filepath: str, data: str, options?: WriteFileOptions);

Writes data to a file, replacing the file if it already exists.

filepath^Required

• Type: str

The file path that needs to be written.

---

data^Required

• Type: str

The data to write.

---

options^Optional

• Type: WriteFileOptions

The encoding can be set to specify the character encoding.

And the flag can be set to specify the attributes. If a flag is not provided, it defaults to "w".

---

writeJson

bring fs;

fs.writeJson(filepath: str, obj: Json);

Writes JSON to a file, replacing the file if it already exists.

filepath^Required

• Type: str

The file path that needs to be written.

---

obj^Required

• Type: Json

The JSON object to be dumped.

---

writeYaml

bring fs;

fs.writeYaml(filepath: str, ...objs: Array<Json>);

Writes multiple YAML objects to a file, replacing the file if it already exists.

filepath^Required

• Type: str

The file path that needs to be written.

---

objs^Required

• Type: Json

The YANL objects to be dumped.

---

Structs

GlobOptions

Options for glob, based on https://www.npmjs.com/package/glob.

Initializer

bring fs;

let GlobOptions = fs.GlobOptions{ ... };

Properties

Name	Type	Description
absolute	bool	Set to true to always receive absolute paths for matched files.
cwd	str	The current working directory in which to search.
dot	bool	Include .dot files in normal matches and globstar matches. Note that an explicit dot in a portion of the pattern will always match dot files.
follow	bool	Follow symlinked directories when expanding ** patterns.
ignore	MutArray<str>	An array of glob patterns to exclude from matches.
maxDepth	num	Specify a number to limit the depth of the directory traversal to this many levels below the cwd.
nodir	bool	Do not match directories, only files.

---

absolute^Optional

absolute: bool;

• Type: bool
• Default: false

Set to true to always receive absolute paths for matched files.

Set to false to always receive relative paths for matched files.

---

cwd^Optional

cwd: str;

• Type: str
• Default: process.cwd()

The current working directory in which to search.

---

dot^Optional

dot: bool;

• Type: bool
• Default: false

Include .dot files in normal matches and globstar matches. Note that an explicit dot in a portion of the pattern will always match dot files.

---

follow^Optional

follow: bool;

• Type: bool
• Default: false

Follow symlinked directories when expanding ** patterns.

This can result in a lot of duplicate references in the presence of cyclic links, and make performance quite bad.

---

ignore^Optional

ignore: MutArray<str>;

• Type: MutArray<str>
• Default: []

An array of glob patterns to exclude from matches.

To ignore all children within a directory, as well as the entry itself, append '/**' to the ignore pattern.

---

maxDepth^Optional

maxDepth: num;

• Type: num
• Default: no limit

Specify a number to limit the depth of the directory traversal to this many levels below the cwd.

---

nodir^Optional

nodir: bool;

• Type: bool
• Default: false

Do not match directories, only files.

(Note: to match only directories, put a / at the end of the pattern.)

---

Metadata

Metadata of a file system object.

Initializer

bring fs;

let Metadata = fs.Metadata{ ... };

Properties

Name	Type	Description
accessed	datetime	The date and time the file was last accessed.
created	datetime	The date and time the file was created.
fileType	FileType	The type of file.
modified	datetime	The date and time the file was last modified.
permissions	str	The permissions of the file.
size	num	The size of the file in bytes.

---

accessed^Required

accessed: datetime;

• Type: datetime

The date and time the file was last accessed.

---

created^Required

created: datetime;

• Type: datetime

The date and time the file was created.

---

fileType^Required

fileType: FileType;

• Type: FileType

The type of file.

---

modified^Required

modified: datetime;

• Type: datetime

The date and time the file was last modified.

---

permissions^Required

permissions: str;

• Type: str

The permissions of the file.

---

size^Required

size: num;

• Type: num

The size of the file in bytes.

---

MkdirOptions

Custom settings for creating directory.

Initializer

bring fs;

let MkdirOptions = fs.MkdirOptions{ ... };

Properties

Name	Type	Description
mode	str	A file mode.
recursive	bool	Indicates whether parent folders should be created.

---

mode^Optional

mode: str;

• Type: str
• Default: "0777"

A file mode.

The string will be parsed as an octal integer.

---

recursive^Optional

recursive: bool;

• Type: bool
• Default: true

Indicates whether parent folders should be created.

If a folder was created, the path to the first created folder will be returned.

---

ReadFileOptions

Custom settings for reading from a file.

Initializer

bring fs;

let ReadFileOptions = fs.ReadFileOptions{ ... };

Properties

Name	Type	Description
encoding	str	The character encoding utilized for file reading.
flag	str	The flag can be set to specify the attributes.

---

encoding^Optional

encoding: str;

• Type: str
• Default: "utf-8"

The character encoding utilized for file reading.

---

flag^Optional

flag: str;

• Type: str
• Default: "r".

The flag can be set to specify the attributes.

---

RemoveOptions

Custom settings for removing files and directories.

Initializer

bring fs;

let RemoveOptions = fs.RemoveOptions{ ... };

Properties

Name	Type	Description
force	bool	When true, exceptions will be ignored if path does not exist.
recursive	bool	If true, perform a recursive directory removal.

---

force^Optional

force: bool;

• Type: bool
• Default: true

When true, exceptions will be ignored if path does not exist.

---

recursive^Optional

recursive: bool;

• Type: bool
• Default: true

If true, perform a recursive directory removal.

In recursive mode, operations are retried on failure.

---

WriteFileOptions

Custom settings for writing to a file.

Initializer

bring fs;

let WriteFileOptions = fs.WriteFileOptions{ ... };

Properties

Name	Type	Description
encoding	str	The character encoding utilized for file writing.
flag	str	The flag can be set to specify the attributes.

---

encoding^Optional

encoding: str;

• Type: str
• Default: "utf-8"

The character encoding utilized for file writing.

---

flag^Optional

flag: str;

• Type: str
• Default: "w".

The flag can be set to specify the attributes.

---

Enums

FileType

Represents the type of a file system object.

Members

Name	Description
FILE	Represents a regular file.
DIRECTORY	Represents a directory.
SYMLINK	Represents a symbolic link.
OTHER	Represents any type of file system object that is not FILE, DIRECTORY or SYMLINK.

---

FILE

Represents a regular file.

---

DIRECTORY

Represents a directory.

---

SYMLINK

Represents a symbolic link.

---

OTHER

Represents any type of file system object that is not FILE, DIRECTORY or SYMLINK.

This includes sockets, FIFOs (named pipes), block devices, and character devices.

---

SymlinkType

Represents the type of the target for creating symbolic links.

Members

Name	Description
FILE	Symbolic link that points to a file.
DIRECTORY	Symbolic link that points to a directory.
JUNCTION	Windows-specific: Symbolic link that points to a directory junction.

---

FILE

Symbolic link that points to a file.

---

DIRECTORY

Symbolic link that points to a directory.

---

JUNCTION

Windows-specific: Symbolic link that points to a directory junction.

---