Skip to content

Sys.Fs

Sys.Fs reads and writes files on the server’s file system, inside the app’s working folder (the working folder within Lowgile’s data folder). Sys.Fs.Path offers helpers from Node’s path module for building and splitting paths.

Availability: Server

Most functions take a base and path components:

  • base (FsBasePath) names a folder that relative paths start from. For Sys.Fs, use 'working'. The other values are 'data', 'project', 'permanent', 'tmp', 'sharedCache', 'buildCache', 'clientBuild', 'clientDist', 'repo', 'extensions' and 'absolute', which takes the path components as an absolute path.
  • pathComponents (string | string[]) is one path or a list of path segments, joined with the platform’s separator, for example 'invoices/2026/0042.pdf' or ['invoices', '2026', '0042.pdf']. If the first component is an absolute path, base is ignored.

Every access is checked: a path that does not lie inside the working folder, including one that leaves it through .., throws Tried to break out of a constrained directory.

await Sys.Fs.writeFile('working', ['exports', 'orders.json'], orders, { format: 'json', jsonIndentation: 2 })
const file = await Sys.Fs.readFile('working', 'exports/orders.json', { format: 'json' })
// file.filePath: absolute path; file.content: the parsed JSON
readFile<T = string | number | boolean | object | any[]>(base: FsBasePath, pathComponents: string | string[], options?: ReadFileOptions & { format: 'json' }): Promise<FileAndContent<T>>
readFile<T = Buffer>(base: FsBasePath, pathComponents: string | string[], options?: ReadFileOptions & { format: 'binary' }): Promise<FileAndContent<T>>
readFile<T = ReadStream>(base: FsBasePath, pathComponents: string | string[], options?: ReadFileOptions & { format: 'binaryStream' }): Promise<FileAndContent<ReadStream>>
readFile<T extends string = string>(base: FsBasePath, pathComponents: string | string[], options?: ReadFileOptions & { format: TextFileFormat }): Promise<FileAndContent<T>>
readFile<T = any>(base: FsBasePath, pathComponents: string | string[], options?: ReadFileOptions): Promise<FileAndContent<T>>

Reads a file and returns its absolute path and its content in the requested format.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from; see Paths.
pathComponentsstring | string[]Path of the file.
optionsReadFileOptionsOptional. Format and error handling.

ReadFileOptions fields

FieldTypeRequiredDescription
formatReadFileFormatNo'json' parses the content as JSON. 'binary' returns a Buffer. 'binaryStream' returns a Node ReadStream. A text encoding ('utf8', 'utf-8', 'ascii', 'latin1', 'utf16le', 'ucs2', 'ucs-2') returns a string. Defaults to 'utf8'.
ignoreErrorbooleanNoIf true, a file that cannot be read gives content: null instead of an error. A path outside the working folder still throws.

Returns: Promise<FileAndContent<T>>, an object with filePath: string (the absolute path) and content: T · Availability: Server

readAllFilesMatchingWildcard<T = string | number | boolean | object | any[]>(base: FsBasePath, pathComponents: string | string[], options?: ReadFileOptions & { format: 'json' }): Promise<FileAndContent<T>[]>
readAllFilesMatchingWildcard<T = Buffer>(base: FsBasePath, pathComponents: string | string[], options?: ReadFileOptions & { format: 'binary' }): Promise<FileAndContent<T>[]>
readAllFilesMatchingWildcard<T = ReadStream>(base: FsBasePath, pathComponents: string | string[], options?: ReadFileOptions & { format: 'binaryStream' }): Promise<FileAndContent<ReadStream>[]>
readAllFilesMatchingWildcard<T extends string = string>(base: FsBasePath, pathComponents: string | string[], options?: ReadFileOptions & { format: TextFileFormat }): Promise<FileAndContent<T>[]>
readAllFilesMatchingWildcard<T = any>(base: FsBasePath, pathComponents: string | string[], options?: ReadFileOptions): Promise<FileAndContent<T>[]>

Reads every file that matches a wildcard pattern, as findAllMatchingWildcard() finds them, and returns one result per file.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path with a glob pattern, for example 'imports/*.csv' or 'imports/**/*.json'.
optionsReadFileOptionsOptional. Format and error handling, as for readFile().

Returns: Promise<FileAndContent<T>[]> · Availability: Server

findAllMatchingWildcard(base: FsBasePath, pathComponents: string | string[]): Promise<string[]>

Returns the absolute paths of all files and folders that match a glob pattern (*, **, ?, […], {a,b}), using the glob package (version ^13.0.6).

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path with a glob pattern.

Returns: Promise<string[]> · Availability: Server

writeFile(base: FsBasePath, pathComponents: string | string[], data: any, options?: WriteFileOptions): Promise<any>

Writes data to a file, replacing it or appending to it. Missing folders on the path are created.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path of the file.
dataanyContent to write: a string or a Buffer, or any JSON-serializable value with format: 'json'.
optionsWriteFileOptionsOptional. Format and write mode.

WriteFileOptions fields

FieldTypeRequiredDescription
formatWriteFileFormatNo'json' serializes data as JSON. 'binary' or a text encoding ('utf8', 'ascii', 'latin1', …) sets the encoding for string data. Defaults to 'utf8'.
jsonIndentationstring | numberNoIndentation for format: 'json'. Without it, the JSON is written on one line.
beautifyFormat'html' | 'scss' | 'ts' | 'json'NoFormats string data with Prettier as this language before writing. If formatting fails, the text is written unchanged.
modeModeNoFile permissions for a newly created file, for example 0o600.
appendbooleanNoIf true, appends to the file instead of replacing it.
ignoreErrorbooleanNoIf true, a write error returns undefined instead of throwing.

Returns: Promise<any>, resolving to undefined · Availability: Server

writeFileStream(base: FsBasePath, pathComponents: string | string[], options?: Omit<WriteFileOptions, 'format'>): Promise<WriteStream>

Creates missing folders and opens a Node WriteStream to the file, replacing its content. Use it for content that is produced piece by piece; end the stream when done.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path of the file.
optionsOmit<WriteFileOptions, 'format'>Optional. Only ignoreError has an effect: if true, a failure returns undefined instead of throwing.

Returns: Promise<WriteStream> · Availability: Server

Note

mode, append, beautifyFormat and jsonIndentation are accepted but ignored.

writeTemporaryFile(prefix: string, data: any, options?: WriteFileOptions): Promise<string>

Writes data to a new file with a unique name, <prefix>_<8 random characters>.dat, in the working folder and returns its absolute path. Lowgile does not delete the file later.

ParameterTypeDescription
prefixstringStart of the file name.
dataanyContent to write, as for writeFile().
optionsWriteFileOptionsOptional. Format and write mode, as for writeFile().

Returns: Promise<string> · Availability: Server

deleteFile(base: FsBasePath, pathComponents: string | string[], ignoreErrors?: boolean): Promise<void>

Deletes a file. It fails for a folder or a missing file; use deleteFileOrFolder() for folders.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path of the file.
ignoreErrorsbooleanOptional. If true, errors such as a missing file are ignored. Defaults to false.

Returns: Promise<void> · Availability: Server

deleteFileOrFolder(base: FsBasePath, pathComponents: string | string[], ignoreErrors?: boolean): Promise<void>

Deletes a file, or a folder with everything in it. A missing path is not an error.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path of the file or folder.
ignoreErrorsbooleanOptional. If true, other errors are ignored too. Defaults to false.

Returns: Promise<void> · Availability: Server

deleteMultiple(base: FsBasePath, paths: (string | string[])[], ignoreErrors?: boolean): Promise<void>

Deletes several files or folders, each as deleteFileOrFolder() does.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
paths(string | string[])[]One path, or list of path segments, per file or folder.
ignoreErrorsbooleanOptional. If true, errors are ignored. Defaults to false.

Returns: Promise<void> · Availability: Server

ensureFolderExists(base: FsBasePath, pathComponents: string | string[]): Promise<void>

Creates a folder, including missing parent folders, unless it already exists.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path of the folder.

Returns: Promise<void> · Availability: Server

createFolder(base: FsBasePath, pathComponents: string | string[]): Promise<{ path: string; folderName: string; }>

Creates a folder, including missing parent folders, unless it already exists, and returns its absolute path.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path of the folder.

Returns: Promise<{ path: string; folderName: string }> · Availability: Server

Note

folderName is the path of the parent folder, as returned by folderName(), not the name of the new folder.

move(sourceBase: FsBasePath, sourcePathComponents: string | string[], targetBase: FsBasePath, targetPathComponents: string | string[], overwrite?: boolean): Promise<void>

Moves or renames a file or folder. Missing parent folders of the target are created.

ParameterTypeDescription
sourceBaseFsBasePathFolder that the relative source path starts from.
sourcePathComponentsstring | string[]Path of the file or folder to move.
targetBaseFsBasePathFolder that the relative target path starts from.
targetPathComponentsstring | string[]New path.
overwritebooleanOptional. If true (the default), an existing target is replaced; otherwise the move fails.

Returns: Promise<void> · Availability: Server

copy(sourceBase: FsBasePath, sourcePathComponents: string | string[], targetBase: FsBasePath, targetPathComponents: string | string[]): Promise<void>

Copies a file, or a folder with everything in it. Existing files at the target are overwritten.

ParameterTypeDescription
sourceBaseFsBasePathFolder that the relative source path starts from.
sourcePathComponentsstring | string[]Path of the file or folder to copy.
targetBaseFsBasePathFolder that the relative target path starts from.
targetPathComponentsstring | string[]Path of the copy.

Returns: Promise<void> · Availability: Server

copyFolderUpdate(sourceBase: FsBasePath, sourcePathComponents: string | string[], targetBase: FsBasePath, targetPathComponents: string | string[]): Promise<void>

Updates a target folder from a source folder: copies files and subfolders that are missing in the target, and files whose source was changed after the target file. Files that exist only in the target are kept.

ParameterTypeDescription
sourceBaseFsBasePathFolder that the relative source path starts from.
sourcePathComponentsstring | string[]Path of the source folder.
targetBaseFsBasePathFolder that the relative target path starts from.
targetPathComponentsstring | string[]Path of the target folder.

Returns: Promise<void> · Availability: Server

createSymlink(sourceBase: FsBasePath, sourcePathComponents: string | string[], targetBase: FsBasePath, targetPathComponents: string | string[], type: SymlinkType): Promise<void>

Creates a symbolic link at the source path that points to the target path. An existing link at the source path is replaced; an existing file or folder there makes the call fail.

ParameterTypeDescription
sourceBaseFsBasePathFolder that the relative link path starts from.
sourcePathComponentsstring | string[]Path of the link to create.
targetBaseFsBasePathFolder that the relative target path starts from.
targetPathComponentsstring | string[]Path the link points to.
type'dir' | 'file' | 'junction'Kind of link. It matters on Windows only, where 'junction' creates a junction for a folder.

Returns: Promise<void> · Availability: Server

stats(base: FsBasePath, pathComponents: string | string[]): Promise<Stats>

Returns Node’s file information (size, timestamps, isFile(), isDirectory(), …) for a file or folder. It fails if the path does not exist.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path of the file or folder.

Returns: Promise<Stats>, see Node’s fs.Stats · Availability: Server

exists(base: FsBasePath, pathComponents: string | string[]): Promise<boolean>

Checks whether a file or folder exists. A path outside the working folder gives false instead of an error.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path of the file or folder.

Returns: Promise<boolean> · Availability: Server

getFilePath(base: FsBasePath, pathComponents: string | string[]): string

Returns the absolute path for a base and path components, without checking access or whether the path exists.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path relative to base, or an absolute path.

Returns: string · Availability: Server

isFilePathAccessible(base: FsBasePath, pathComponents: string | string[]): boolean

Checks whether Sys.Fs may access a path, that is, whether it lies inside the working folder. It does not check whether the path exists.

ParameterTypeDescription
baseFsBasePathFolder that relative paths start from.
pathComponentsstring | string[]Path to check.

Returns: boolean · Availability: Server

checkAccessToPath(path: string): void

Throws Tried to break out of a constrained directory if an absolute path lies outside the working folder, and does nothing otherwise.

ParameterTypeDescription
pathstringAbsolute path to check.

Returns: void · Availability: Server

fileName(path: string, removeExtension?: string): string

Returns the last segment of a path, as Node’s path.basename() does.

ParameterTypeDescription
pathstringPath to take the file name from.
removeExtensionstringOptional. Ending to remove from the result if the name ends with it, for example '.pdf'.

Returns: string · Availability: Server

folderName(path: string): string

Returns the path of the folder that contains path, as Node’s path.dirname() does. For '/data/working/invoices/0042.pdf' it returns '/data/working/invoices'.

ParameterTypeDescription
pathstringPath of a file or folder.

Returns: string · Availability: Server

Path: {
basename: (path: string, suffix?: string) => string;
dirname: (path: string) => string;
extname: (path: string) => string;
join: (...paths: string[]) => string;
normalize: (path: string) => string;
parse: (path: string) => path.ParsedPath;
resolve: (...paths: string[]) => string;
sep: "\\" | "/";
relative: (from: string, to: string) => string;
isAbsolute: (path: string) => boolean;
}

A subset of Node’s path module for the server’s platform: basename, dirname, extname, join, normalize, parse, resolve, sep, relative and isAbsolute. They only compute paths and do not touch the file system. The full module is available as Sys.Path; see the Node path documentation.

const pdfName = Sys.Fs.Path.basename(filePath, '.pdf')

Type: object · Availability: Server