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. ForSys.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,baseis 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 JSONFunctions
Section titled “Functions”readFile()
Section titled “readFile()”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.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from; see Paths. |
pathComponents | string | string[] | Path of the file. |
options | ReadFileOptions | Optional. Format and error handling. |
ReadFileOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
format | ReadFileFormat | No | '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'. |
ignoreError | boolean | No | If 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()
Section titled “readAllFilesMatchingWildcard()”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.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path with a glob pattern, for example 'imports/*.csv' or 'imports/**/*.json'. |
options | ReadFileOptions | Optional. Format and error handling, as for readFile(). |
Returns: Promise<FileAndContent<T>[]> · Availability: Server
findAllMatchingWildcard()
Section titled “findAllMatchingWildcard()”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).
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path with a glob pattern. |
Returns: Promise<string[]> · Availability: Server
writeFile()
Section titled “writeFile()”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.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path of the file. |
data | any | Content to write: a string or a Buffer, or any JSON-serializable value with format: 'json'. |
options | WriteFileOptions | Optional. Format and write mode. |
WriteFileOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
format | WriteFileFormat | No | 'json' serializes data as JSON. 'binary' or a text encoding ('utf8', 'ascii', 'latin1', …) sets the encoding for string data. Defaults to 'utf8'. |
jsonIndentation | string | number | No | Indentation for format: 'json'. Without it, the JSON is written on one line. |
beautifyFormat | 'html' | 'scss' | 'ts' | 'json' | No | Formats string data with Prettier as this language before writing. If formatting fails, the text is written unchanged. |
mode | Mode | No | File permissions for a newly created file, for example 0o600. |
append | boolean | No | If true, appends to the file instead of replacing it. |
ignoreError | boolean | No | If true, a write error returns undefined instead of throwing. |
Returns: Promise<any>, resolving to undefined · Availability: Server
writeFileStream()
Section titled “writeFileStream()”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.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path of the file. |
options | Omit<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()
Section titled “writeTemporaryFile()”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.
| Parameter | Type | Description |
|---|---|---|
prefix | string | Start of the file name. |
data | any | Content to write, as for writeFile(). |
options | WriteFileOptions | Optional. Format and write mode, as for writeFile(). |
Returns: Promise<string> · Availability: Server
deleteFile()
Section titled “deleteFile()”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.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path of the file. |
ignoreErrors | boolean | Optional. If true, errors such as a missing file are ignored. Defaults to false. |
Returns: Promise<void> · Availability: Server
deleteFileOrFolder()
Section titled “deleteFileOrFolder()”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.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path of the file or folder. |
ignoreErrors | boolean | Optional. If true, other errors are ignored too. Defaults to false. |
Returns: Promise<void> · Availability: Server
deleteMultiple()
Section titled “deleteMultiple()”deleteMultiple(base: FsBasePath, paths: (string | string[])[], ignoreErrors?: boolean): Promise<void>Deletes several files or folders, each as deleteFileOrFolder() does.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
paths | (string | string[])[] | One path, or list of path segments, per file or folder. |
ignoreErrors | boolean | Optional. If true, errors are ignored. Defaults to false. |
Returns: Promise<void> · Availability: Server
ensureFolderExists()
Section titled “ensureFolderExists()”ensureFolderExists(base: FsBasePath, pathComponents: string | string[]): Promise<void>Creates a folder, including missing parent folders, unless it already exists.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path of the folder. |
Returns: Promise<void> · Availability: Server
createFolder()
Section titled “createFolder()”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.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | 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()
Section titled “move()”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.
| Parameter | Type | Description |
|---|---|---|
sourceBase | FsBasePath | Folder that the relative source path starts from. |
sourcePathComponents | string | string[] | Path of the file or folder to move. |
targetBase | FsBasePath | Folder that the relative target path starts from. |
targetPathComponents | string | string[] | New path. |
overwrite | boolean | Optional. If true (the default), an existing target is replaced; otherwise the move fails. |
Returns: Promise<void> · Availability: Server
copy()
Section titled “copy()”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.
| Parameter | Type | Description |
|---|---|---|
sourceBase | FsBasePath | Folder that the relative source path starts from. |
sourcePathComponents | string | string[] | Path of the file or folder to copy. |
targetBase | FsBasePath | Folder that the relative target path starts from. |
targetPathComponents | string | string[] | Path of the copy. |
Returns: Promise<void> · Availability: Server
copyFolderUpdate()
Section titled “copyFolderUpdate()”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.
| Parameter | Type | Description |
|---|---|---|
sourceBase | FsBasePath | Folder that the relative source path starts from. |
sourcePathComponents | string | string[] | Path of the source folder. |
targetBase | FsBasePath | Folder that the relative target path starts from. |
targetPathComponents | string | string[] | Path of the target folder. |
Returns: Promise<void> · Availability: Server
createSymlink()
Section titled “createSymlink()”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.
| Parameter | Type | Description |
|---|---|---|
sourceBase | FsBasePath | Folder that the relative link path starts from. |
sourcePathComponents | string | string[] | Path of the link to create. |
targetBase | FsBasePath | Folder that the relative target path starts from. |
targetPathComponents | string | 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()
Section titled “stats()”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.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path of the file or folder. |
Returns: Promise<Stats>, see Node’s fs.Stats · Availability: Server
exists()
Section titled “exists()”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.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path of the file or folder. |
Returns: Promise<boolean> · Availability: Server
getFilePath()
Section titled “getFilePath()”getFilePath(base: FsBasePath, pathComponents: string | string[]): stringReturns the absolute path for a base and path components, without checking access or whether the path exists.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path relative to base, or an absolute path. |
Returns: string · Availability: Server
isFilePathAccessible()
Section titled “isFilePathAccessible()”isFilePathAccessible(base: FsBasePath, pathComponents: string | string[]): booleanChecks whether Sys.Fs may access a path, that is, whether it lies inside the working folder. It does not check whether the path exists.
| Parameter | Type | Description |
|---|---|---|
base | FsBasePath | Folder that relative paths start from. |
pathComponents | string | string[] | Path to check. |
Returns: boolean · Availability: Server
checkAccessToPath()
Section titled “checkAccessToPath()”checkAccessToPath(path: string): voidThrows Tried to break out of a constrained directory if an absolute path lies outside the working folder, and does nothing otherwise.
| Parameter | Type | Description |
|---|---|---|
path | string | Absolute path to check. |
Returns: void · Availability: Server
fileName()
Section titled “fileName()”fileName(path: string, removeExtension?: string): stringReturns the last segment of a path, as Node’s path.basename() does.
| Parameter | Type | Description |
|---|---|---|
path | string | Path to take the file name from. |
removeExtension | string | Optional. Ending to remove from the result if the name ends with it, for example '.pdf'. |
Returns: string · Availability: Server
folderName()
Section titled “folderName()”folderName(path: string): stringReturns 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'.
| Parameter | Type | Description |
|---|---|---|
path | string | Path of a file or folder. |
Returns: string · Availability: Server
Properties
Section titled “Properties”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