Skip to main content

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();
NameTypeDescription

Static Functions

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

pathsRequired
  • 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.

filepathRequired
  • Type: str

The file path that needs to be appended.


dataRequired
  • Type: str

The text to be appended to the file.


optionsOptional

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.

pathRequired
  • Type: str

The path to evaluate.


dirname
bring fs;

fs.dirname(path: str);

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

pathRequired
  • Type: str

The path to evaluate.


exists
bring fs;

fs.exists(path: str);

Check if the path exists.

pathRequired
  • 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.

pathRequired
  • 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

patternRequired
  • Type: str

The pattern to match.


optionsOptional

Glob options.


isDir
bring fs;

fs.isDir(path: str);

Checks if the given path is a directory and exists.

pathRequired
  • Type: str

The path to check.


join
bring fs;

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

Join all arguments together and normalize the resulting path.

pathsRequired
  • 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.

dirRequired
  • Type: str

The root directory.


globPatternOptional
  • 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.

pathRequired
  • Type: str

The path to get stats for.


mkdir
bring fs;

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

Create a directory.

dirpathRequired
  • Type: str

The path to the directory you want to create.


optsOptional

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.

prefixOptional
  • Type: str

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


readdir
bring fs;

fs.readdir(dirpath: str);

Read the contents of the directory.

dirpathRequired
  • Type: str

The path to evaluate.


readFile
bring fs;

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

Read the entire contents of a file.

filepathRequired
  • Type: str

The path of the file to be read.


optionsOptional

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.

filepathRequired
  • 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.

filepathRequired
  • 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.

fromRequired
  • Type: str

toRequired
  • Type: str

remove
bring fs;

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

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

Returns undefined.

pathRequired
  • Type: str

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


optsOptional

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

pathRequired
  • Type: str

The path of the file or directory.


permissionsRequired
  • Type: str

The mode to set as a string.


bring fs;

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

Creates a symbolic link.

targetRequired
  • Type: str

The path to the target file or directory.


pathRequired
  • Type: str

The path to the symbolic link to be created.


typeOptional

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.

pathRequired
  • Type: str

The path to get stats for.


tryReaddir
bring fs;

fs.tryReaddir(dirpath: str);

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

otherwise, return undefined.

dirpathRequired
  • 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.

filepathRequired
  • Type: str

The path of the file to be read.


optionsOptional

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.

filepathRequired
  • 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.

filepathRequired
  • Type: str

The file path of the YAML file.


writeFile
bring fs;

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

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

filepathRequired
  • Type: str

The file path that needs to be written.


dataRequired
  • Type: str

The data to write.


optionsOptional

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.

filepathRequired
  • Type: str

The file path that needs to be written.


objRequired

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.

filepathRequired
  • Type: str

The file path that needs to be written.


objsRequired

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

NameTypeDescription
absolute
boolSet to true to always receive absolute paths for matched files.
cwd
strThe current working directory in which to search.
dot
boolInclude .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
boolFollow symlinked directories when expanding ** patterns.
ignore
MutArray<str>An array of glob patterns to exclude from matches.
maxDepth
numSpecify a number to limit the depth of the directory traversal to this many levels below the cwd.
nodir
boolDo not match directories, only files.

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


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

The current working directory in which to search.


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


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


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


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


nodirOptional
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

NameTypeDescription
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
strThe permissions of the file.
size
numThe size of the file in bytes.

accessedRequired
accessed: datetime;

The date and time the file was last accessed.


createdRequired
created: datetime;

The date and time the file was created.


fileTypeRequired
fileType: FileType;

The type of file.


modifiedRequired
modified: datetime;

The date and time the file was last modified.


permissionsRequired
permissions: str;
  • Type: str

The permissions of the file.


sizeRequired
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

NameTypeDescription
mode
strA file mode.
recursive
boolIndicates whether parent folders should be created.

modeOptional
mode: str;
  • Type: str
  • Default: "0777"

A file mode.

The string will be parsed as an octal integer.


recursiveOptional
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

NameTypeDescription
encoding
strThe character encoding utilized for file reading.
flag
strThe flag can be set to specify the attributes.

encodingOptional
encoding: str;
  • Type: str
  • Default: "utf-8"

The character encoding utilized for file reading.


flagOptional
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

NameTypeDescription
force
boolWhen true, exceptions will be ignored if path does not exist.
recursive
boolIf true, perform a recursive directory removal.

forceOptional
force: bool;
  • Type: bool
  • Default: true

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


recursiveOptional
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

NameTypeDescription
encoding
strThe character encoding utilized for file writing.
flag
strThe flag can be set to specify the attributes.

encodingOptional
encoding: str;
  • Type: str
  • Default: "utf-8"

The character encoding utilized for file writing.


flagOptional
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

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


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

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