fs

A secure file system module for Gingee that provides secure sandboxed synchronous and asynchronous file operations. NOTE: path with leading slash indicates path from scope root, path without leading slash indicates path relative to the executing script 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: path with leading slash indicates path from scope root, path without leading slash indicates path relative to the executing script 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) 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) 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) 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) 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) 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