fs

A secure file system module for Gingee that provides secure sandboxed synchronous and asynchronous file operations. NOTE: A path with a leading / is relative to the scope root (box/ or web/). A path without a leading slash is relative to the currently executing gbox script directory (aligned with require('./…')). Module-override fs wrappers keep the caller's base so transparent facades resolve paths as the request/entry script intended. IMPORTANT: Requires explicit permission to use the module. See docs/permissions-guide for more details.
Description:
  • A secure file system module for Gingee that provides secure sandboxed synchronous and asynchronous file operations. NOTE: A path with a leading / is relative to the scope root (box/ or web/). A path without a leading slash is relative to the currently executing gbox script directory (aligned with require('./…')). Module-override fs wrappers keep the caller's base so transparent facades resolve paths as the request/entry script intended. IMPORTANT: Requires explicit permission to use the module. See docs/permissions-guide for more details.

Members

(static, constant) BOX

Description:
  • Constant for the BOX scope. This constant can be used to specify the BOX scope when working with file system operations. It represents the application box directory, typically used for sandboxed data and server scripts that should not be accessible from the web.
Constant for the BOX scope. This constant can be used to specify the BOX scope when working with file system operations. It represents the application box directory, typically used for sandboxed data and server scripts that should not be accessible from the web.

(static, constant) WEB

Description:
  • Constant for the WEB scope. This constant can be used to specify the WEB scope when working with file system operations. It represents the web directory, typically used for web assets.
Constant for the WEB scope. This constant can be used to specify the WEB scope when working with file system operations. It represents the web directory, typically used for web assets.

Methods

(static) appendFile(scope, filePath, data, optionsopt) → {Promise.<void>}

Description:
  • Asynchronously appends data to a file, creating directories as needed.
Example
fs.appendFile(fs.BOX, 'data/file.txt', 'Hello, world!', 'utf8').then(() => {
  console.log('File appended successfully');
});
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
data string | Buffer The data to append.
options object | string <optional>
 The encoding or an options object.
Throws:
If the file path is outside the secure scope or if the directory cannot be created.
Type
Error
Returns:
A Promise that resolves when the append operation is complete.
Type
Promise.<void>

(static) appendFileSync(scope, filePath, data, optionsopt) → {void}

Description:
  • Synchronously appends data to a file, creating directories as needed.
Example
fs.appendFileSync(fs.BOX, 'data/myfile.txt', 'Hello, World!', 'utf8');
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
data string | Buffer The data to append to the file.
options object | string <optional>
 The encoding or an options object.
Throws:
If the file path is outside the secure scope or if the directory cannot be created.
Type
Error
Returns:
Type
void

(static) copyDir(sourceScope, sourcePath, destScope, destPath) → {Promise.<void>}

Description:
  • Asynchronously copies a directory from one location to another within the same scope.
Example
fs.copyDir(fs.BOX, 'data/oldDir', fs.BOX, 'data/newDir').then(() => {
  console.log('Directory copied successfully');
});
Parameters:
Name Type Description
sourceScope string The scope of the source directory (fs.BOX or fs.WEB).
sourcePath string The path to the source directory, relative to the source scope.
destScope string The scope of the destination directory (fs.BOX or fs.WEB).
destPath string The path to the destination directory, relative to the destination scope.
Throws:
if the source directory does not exist.
Type
Error
Returns:
A Promise that resolves when the directory is copied.
Type
Promise.<void>

(static) copyDirSync(sourceScope, sourcePath, destScope, destPath) → {void}

Description:
  • Synchronously copies a directory from one location to another within the same scope.
Example
fs.copyDirSync(fs.BOX, 'data/oldDir', fs.BOX, 'data/newDir');
Parameters:
Name Type Description
sourceScope string The scope of the source directory (fs.BOX or fs.WEB).
sourcePath string The path to the source directory, relative to the source scope.
destScope string The scope of the destination directory (fs.BOX or fs.WEB).
destPath string The path to the destination directory, relative to the destination scope.
Throws:
if the source directory does not exist.
Type
Error
Returns:
Type
void

(static) copyFile(sourceScope, sourcePath, destScope, destPath) → {Promise.<void>}

Description:
  • Asynchronously copies a file from one location to another within the same scope.
Example
fs.copyFile(fs.BOX, 'data/file.txt', fs.BOX, 'data/copy.txt').then(() => {
  console.log('File copied successfully');
});
Parameters:
Name Type Description
sourceScope string The scope of the source file (fs.BOX or fs.WEB).
sourcePath string The path to the source file, relative to the source scope.
destScope string The scope of the destination file (fs.BOX or fs.WEB).
destPath string The path to the destination file, relative to the destination scope.
Throws:
if the source file does not exist.
Type
Error
Returns:
A Promise that resolves when the file is copied.
Type
Promise.<void>

(static) copyFileSync(sourceScope, sourcePath, destScope, destPath) → {void}

Description:
  • Synchronously copies a file from one location to another within the same scope.
Example
fs.copyFileSync(fs.BOX, 'data/myfile.txt', fs.BOX, 'data/backup/myfile.txt');
Parameters:
Name Type Description
sourceScope string The scope of the source file (fs.BOX or fs.WEB).
sourcePath string The path to the source file, relative to the source scope.
destScope string The scope of the destination file (fs.BOX or fs.WEB).
destPath string The path to the destination file, relative to the destination scope.
Throws:
if the source file does not exist.
Type
Error
Returns:
Type
void

(static) deleteFile(scope, filePath) → {Promise.<void>}

Description:
  • Asynchronously deletes a file.
Example
fs.deleteFile(fs.BOX, 'data/file.txt').then(() => {
  console.log('File deleted successfully');
});
Parameters:
Name Type Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
Throws:
If the file does not exist or is outside the secure scope.
Type
Error
Returns:
A Promise that resolves when the file is deleted.
Type
Promise.<void>

(static) deleteFileSync(scope, filePath) → {void}

Description:
  • Synchronously deletes a file.
Example
fs.deleteFileSync(fs.BOX, 'data/myfile.txt');
Parameters:
Name Type Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
Throws:
If the file does not exist or is outside the secure scope.
Type
Error
Returns:
Type
void

(static) exists(scope, filePath) → {Promise.<boolean>}

Description:
  • Asynchronously checks if a file exists.
Example
fs.exists(fs.BOX, 'data/file.txt').then(exists => {
  console.log(exists);
});
Parameters:
Name Type Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
Throws:
If the file path is outside the secure scope.
Type
Error
Returns:
A Promise that resolves with true if the file exists, false otherwise.
Type
Promise.<boolean>

(static) existsSync(scope, filePath) → {boolean}

Description:
  • Synchronously checks if a file exists.
Example
const exists = fs.existsSync(fs.BOX, 'data/myfile.txt');
console.log(exists); // Outputs true if myfile.txt exists, false otherwise
Parameters:
Name Type Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
Returns:
True if the file exists, false otherwise.
Type
boolean

(static) listDirs(scope, dirPath) → {Promise.<Array.<string>>}

Description:
  • Asynchronously lists subdirectory names only (non-recursive).
Example
const dirs = await fs.listDirs(fs.BOX, 'data');
Parameters:
Name Type Description
scope string fs.BOX or fs.WEB
dirPath string Directory path relative to scope or script
Returns:
Type
Promise.<Array.<string>>

(static) listDirsSync(scope, dirPath) → {Array.<string>}

Description:
  • Synchronously lists subdirectory names only (non-recursive).
Example
const dirs = fs.listDirsSync(fs.BOX, 'data');
Parameters:
Name Type Description
scope string fs.BOX or fs.WEB
dirPath string Directory path relative to scope or script
Returns:
Directory names
Type
Array.<string>

(static) listFiles(scope, dirPath) → {Promise.<Array.<string>>}

Description:
  • Asynchronously lists file names only in a directory (non-recursive).
Example
const files = await fs.listFiles(fs.BOX, 'data');
Parameters:
Name Type Description
scope string fs.BOX or fs.WEB
dirPath string Directory path relative to scope or script
Returns:
Type
Promise.<Array.<string>>

(static) listFilesSync(scope, dirPath) → {Array.<string>}

Description:
  • Synchronously lists file names only in a directory (non-recursive).
Example
const files = fs.listFilesSync(fs.BOX, 'data');
Parameters:
Name Type Description
scope string fs.BOX or fs.WEB
dirPath string Directory path relative to scope or script
Returns:
File names
Type
Array.<string>

(static) mkdir(scope, dirPath) → {Promise.<void>}

Description:
  • Asynchronously creates a directory and its parent directories if they do not exist.
Example
fs.mkdir(fs.BOX, 'data/newdir').then(() => {
  console.log('Directory created successfully');
});
Parameters:
Name Type Description
scope string The scope to operate in (fs.BOX or fs.WEB).
dirPath string The path to the directory, relative to the scope or script.
Throws:
If the directory path is outside the secure scope or if the directory cannot be created.
Type
Error
Returns:
A Promise that resolves when the directory is created.
Type
Promise.<void>

(static) mkdirSync(scope, dirPath) → {void}

Description:
  • Synchronously creates a directory and its parent directories if they do not exist.
Example
fs.mkdirSync(fs.BOX, 'data/newdir');
Parameters:
Name Type Description
scope string The scope to operate in (fs.BOX or fs.WEB).
dirPath string The path to the directory, relative to the scope or script.
Throws:
If the directory path is outside the secure scope or if the directory cannot be created.
Type
Error
Returns:
Type
void

(static) moveDir(sourceScope, sourcePath, destScope, destPath) → {Promise.<string>}

Description:
  • Asynchronously moves a directory from one location to another within the same scope.
Example
fs.moveDir(fs.BOX, 'data/oldDir', fs.BOX, 'data/newDir').then(newPath => {
  console.log('Directory moved to:', newPath);
});
Parameters:
Name Type Description
sourceScope string The scope of the source directory (fs.BOX or fs.WEB).
sourcePath string The path to the source directory, relative to the source scope.
destScope string The scope of the destination directory (fs.BOX or fs.WEB).
destPath string The path to the destination directory, relative to the destination scope.
Throws:
if the source directory does not exist.
Type
Error
Returns:
A Promise that resolves with the new absolute path of the moved directory.
Type
Promise.<string>

(static) moveDirSync(sourceScope, sourcePath, destScope, destPath) → {string}

Description:
  • Synchronously moves a directory from one location to another within the same scope.
Example
fs.moveDirSync(fs.BOX, 'data/oldDir', fs.BOX, 'data/newDir');
Parameters:
Name Type Description
sourceScope string The scope of the source directory (fs.BOX or fs.WEB).
sourcePath string The path to the source directory, relative to the source scope.
destScope string The scope of the destination directory (fs.BOX or fs.WEB).
destPath string The path to the destination directory, relative to the destination scope.
Throws:
if the source directory does not exist.
Type
Error
Returns:
The new absolute path of the moved directory.
Type
string

(static) moveFile(sourceScope, sourcePath, destScope, destPath) → {Promise.<string>}

Description:
  • Asynchronously moves a file from one location to another within the same scope.
Example
fs.moveFile(fs.BOX, 'data/file.txt', fs.BOX, 'data/newfile.txt').then(newPath => {
  console.log('File moved to:', newPath);
});
Parameters:
Name Type Description
sourceScope string The scope of the source file (fs.BOX or fs.WEB).
sourcePath string The path to the source file, relative to the source scope.
destScope string The scope of the destination file (fs.BOX or fs.WEB).
destPath string The path to the destination file, relative to the destination scope.
Throws:
  • If the source and destination scopes are different.
    Type
    Error
  • If the source file does not exist.
    Type
    Error
Returns:
A Promise that resolves with the new absolute path of the moved file.
Type
Promise.<string>

(static) moveFileSync(sourceScope, sourcePath, destScope, destPath) → {string}

Description:
  • Synchronously moves a file from one location to another within the same scope.
Example
const newPath = fs.moveFileSync(fs.BOX, 'data/myfile.txt', fs.BOX, 'data/archived/myfile.txt');
Parameters:
Name Type Description
sourceScope string The scope of the source file (fs.BOX or fs.WEB).
sourcePath string The path to the source file, relative to the source scope.
destScope string The scope of the destination file (fs.BOX or fs.WEB).
destPath string The path to the destination file, relative to the destination scope.
Throws:
if the source file does not exist.
Type
Error
Returns:
The new absolute path of the moved file.
Type
string

(static) readFile(scope, filePath, optionsopt) → {Promise.<(string|Buffer)>}

Description:
  • Asynchronously reads the entire contents of a file.
Example
fs.readFile(fs.BOX, 'data/file.txt', 'utf8').then(contents => {
  console.log(contents);
});
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
options object | string <optional>
 The encoding or an options object.
Throws:
If the file does not exist or is outside the secure scope.
Type
Error
Returns:
A Promise that resolves with the contents of the file.
Type
Promise.<(string|Buffer)>

(static) readFileSync(scope, filePath, optionsopt) → {string|Buffer}

Description:
  • Synchronously reads the entire contents of a file.
Example
const content = fs.readFileSync(fs.BOX, 'data/myfile.txt', 'utf8');
console.log(content); // Outputs the content of myfile.txt
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
options object | string <optional>
 The encoding or an options object.
Throws:
If the file does not exist or is outside the secure scope.
Type
Error
Returns:
The contents of the file.
Type
string | Buffer

(static) readJSON(scope, filePath, optionsopt) → {Promise.<object>}

Description:
  • Asynchronously reads a JSON file and parses it.
Example
const data = await fs.readJSON(fs.BOX, 'data/myfile.json');
console.log(data); // Outputs the parsed JSON object
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
options object | string <optional>
 The encoding or an options object.
Throws:
If the file does not exist or is outside the secure scope or it is not valid JSON.
Type
Error
Returns:
A Promise that resolves with the parsed JSON object.
Type
Promise.<object>

(static) readJSONSync(scope, filePath, optionsopt) → {object}

Description:
  • Synchronously reads a JSON file and parses it.
Example
const data = fs.readJSONSync(fs.BOX, 'data/myfile.json');
console.log(data); // Outputs the parsed JSON object
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
options object | string <optional>
 The encoding or an options object.
Throws:
If the file does not exist or is outside the secure scope or it is not valid JSON.
Type
Error
Returns:
The parsed JSON object.
Type
object

(static) readdir(scope, dirPath) → {Promise.<Array.<string>>}

Description:
  • Asynchronously lists all entry names in a directory (non-recursive).
Example
const names = await fs.readdir(fs.BOX, 'data');
Parameters:
Name Type Description
scope string fs.BOX or fs.WEB
dirPath string Directory path relative to scope or script
Returns:
Type
Promise.<Array.<string>>

(static) readdirSync(scope, dirPath) → {Array.<string>}

Description:
  • Synchronously lists all entry names in a directory (non-recursive).
Example
const names = fs.readdirSync(fs.BOX, 'data');
Parameters:
Name Type Description
scope string fs.BOX or fs.WEB
dirPath string Directory path relative to scope or script
Returns:
Entry names (files and directories)
Type
Array.<string>

(static) rmdir(scope, dirPath, optionsopt) → {Promise.<void>}

Description:
  • Asynchronously removes a directory.
Example
fs.rmdir(fs.BOX, 'data/oldDir', { recursive: true }).then(() => {
  console.log('Directory removed successfully');
});
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
dirPath string The path to the directory, relative to the scope or script.
options object <optional>
 Options for the removal. - `recursive`: If true, removes the directory and its contents recursively.
Throws:
If the directory does not exist or is outside the secure scope.
Type
Error
Returns:
A Promise that resolves when the directory is removed.
Type
Promise.<void>

(static) rmdirSync(scope, dirPath, optionsopt) → {void}

Description:
  • Synchronously removes a directory.
Example
fs.rmdirSync(fs.BOX, 'data/oldDir', { recursive: true });
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
dirPath string The path to the directory, relative to the scope or script.
options object <optional>
 Options for the removal. - `recursive`: If true, removes the directory and its contents recursively.
Throws:
If the directory is not empty and `recursive` is false.
Type
Error
Returns:
Type
void

(static) stat(scope, filePath) → {Promise.<{size: number, mtimeMs: number, ctimeMs: number, birthtimeMs: number, isFile: boolean, isDirectory: boolean, isSymbolicLink: boolean, mode: number}>}

Description:
  • Asynchronously returns metadata for a file or directory.
Example
const info = await fs.stat(fs.BOX, 'data/file.txt');
Parameters:
Name Type Description
scope string fs.BOX or fs.WEB
filePath string Path relative to scope or script
Throws:
If the path does not exist or is outside the secure scope
Type
Error
Returns:
Type
Promise.<{size: number, mtimeMs: number, ctimeMs: number, birthtimeMs: number, isFile: boolean, isDirectory: boolean, isSymbolicLink: boolean, mode: number}>

(static) statSync(scope, filePath) → {Object}

Description:
  • Synchronously returns metadata for a file or directory.
Example
const info = fs.statSync(fs.BOX, 'data/file.txt');
Parameters:
Name Type Description
scope string fs.BOX or fs.WEB
filePath string Path relative to scope or script
Throws:
If the path does not exist or is outside the secure scope
Type
Error
Returns:
Type
Object

(static) walk(scope, dirPath, optionsopt) → {Promise.<Array.<string>>}

Description:
  • Asynchronously walks a directory tree and returns relative paths (forward slashes). Symlink directories are not descended into (v1).
Example
const paths = await fs.walk(fs.BOX, 'data', { includeDirs: true });
Parameters:
Name Type Attributes Description
scope string fs.BOX or fs.WEB
dirPath string Root directory to walk
options object <optional>
Properties
Name Type Attributes Default Description
includeDirs boolean <optional>
 false Include directory paths in the result
maxDepth number <optional>
 Max directory depth (1 = immediate children only); omit for unlimited
Returns:
Type
Promise.<Array.<string>>

(static) walkSync(scope, dirPath, optionsopt) → {Array.<string>}

Description:
  • Synchronously walks a directory tree and returns relative paths (forward slashes). Symlink directories are not descended into (v1).
Example
const paths = fs.walkSync(fs.BOX, 'data', { includeDirs: true, maxDepth: 2 });
Parameters:
Name Type Attributes Description
scope string fs.BOX or fs.WEB
dirPath string Root directory to walk
options object <optional>
Properties
Name Type Attributes Default Description
includeDirs boolean <optional>
 false Include directory paths in the result
maxDepth number <optional>
 Max directory depth (1 = immediate children only); omit for unlimited
Returns:
Relative paths from dirPath
Type
Array.<string>

(static) writeFile(scope, filePath, data, optionsopt) → {Promise.<void>}

Description:
  • Asynchronously writes data to a file, replacing the file if it already exists.
Example
fs.writeFile(fs.BOX, 'data/file.txt', 'Hello, world!', 'utf8').then(() => {
  console.log('File written successfully');
});
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
data string | Buffer The data to write.
options object | string <optional>
 The encoding or an options object.
Throws:
If the file path is outside the secure scope or if the directory cannot be created.
Type
Error
Returns:
A Promise that resolves when the write operation is complete.
Type
Promise.<void>

(static) writeFileSync(scope, filePath, data, optionsopt) → {void}

Description:
  • Synchronously writes data to a file, creating directories as needed.
Example
fs.writeFileSync(fs.BOX, 'data/myfile.txt', 'Hello, World!', 'utf8');
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
data string | Buffer The data to write to the file.
options object | string <optional>
 The encoding or an options object.
Throws:
If the file path is outside the secure scope or if the directory cannot be created.
Type
Error
Returns:
Type
void

(static) writeJSON(scope, filePath, data, optionsopt) → {Promise.<void>}

Description:
  • Asynchronously writes a JSON object to a file, creating directories as needed.
Example
await fs.writeJSON(fs.BOX, 'data/myfile.json', { key: 'value' });
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
data object The JSON object to write to the file.
options object | string <optional>
 The encoding or an options object.
Throws:
If the file path is outside the secure scope or if the directory cannot be created.
Type
Error
Returns:
A Promise that resolves when the write operation is complete.
Type
Promise.<void>

(static) writeJSONSync(scope, filePath, data, optionsopt) → {void}

Description:
  • Synchronously writes a JSON object to a file, creating directories as needed.
Example
fs.writeJSONSync(fs.BOX, 'data/myfile.json', { key: 'value' });
Parameters:
Name Type Attributes Description
scope string The scope to operate in (fs.BOX or fs.WEB).
filePath string The path to the file, relative to the scope or script.
data object The JSON object to write to the file.
options object | string <optional>
 The encoding or an options object.
Throws:
If the file path is outside the secure scope or if the directory cannot be created.
Type
Error
Returns:
Type
void