API fs

fs

Opt-in native file-system module.

Script API Reference · Host BuiltInModules

Enable and Import

The module is disabled by default. The host must add BuiltInModules.FileSystem before constructing the engine:

using AuroraScript.Runtime.Package;

var options = EngineOptions.Default.WithBuiltIns(builtIns =>
    builtIns.Add(BuiltInModules.FileSystem));

Script code then imports the bare module path. fs is an import alias, not a global object.

import fs from "fs";

Every path parameter accepts either a non-empty string or Path. Relative file-system paths use the host process working directory; use Path.baseModule(...) when a path should be relative to the importing script.

Quick Reference

Method	Returns	Purpose
readText(path)	string	Read a text file.
readBytes(path)	UInt8Array	Read all bytes.
writeText(path, text)	boolean	Create or replace text.
writeBytes(path, bytes)	boolean	Create or replace bytes.
appendText(path, text)	boolean	Append text.
appendBytes(path, bytes)	boolean	Append bytes.
exist(path)	boolean	Test for a file or directory.
isFile(path)	boolean	Test for a file.
isDir(path)	boolean	Test for a directory.
size(path)	number	Get a file's byte length.
mkDir(path)	boolean	Create a directory tree.
dir(path)	string[]	List top-level names.
copy(source, destination, overwrite?)	boolean	Copy a file or directory tree.
move(source, destination, overwrite?)	boolean	Move a file or directory.
delete(path, recursive?)	boolean	Delete a file or directory.

Reading and Writing

fs.readText(path)

fs.readText(path: string|Path): string

Reads the complete text file using .NET's UTF-8 text-file behavior.

fs.readBytes(path)

fs.readBytes(path: string|Path): UInt8Array

Reads the complete file into a new UInt8Array.

fs.writeText(path, text)

fs.writeText(path: string|Path, text: string): boolean

Creates or replaces a text file and returns true. Missing parent directories are not created automatically.

fs.writeBytes(path, bytes)

fs.writeBytes(path: string|Path, bytes: UInt8Array): boolean

Creates or replaces a binary file and returns true. Missing parent directories are not created automatically.

fs.appendText(path, text)

fs.appendText(path: string|Path, text: string): boolean

Appends text and returns true. The file is created if it does not exist, but its parent directory must exist.

fs.appendBytes(path, bytes)

fs.appendBytes(path: string|Path, bytes: UInt8Array): boolean

Appends bytes and returns true. The file is created if it does not exist, but its parent directory must exist.

import fs from "fs";

export func save(root) {
    var file = new Path(root, "logs", "latest.txt");
    fs.mkDir(file.directoryName());
    fs.writeText(file, "started\n");
    return fs.appendText(file, "ready\n");
}

Inspection and Directories

fs.exist(path)

fs.exist(path: string|Path): boolean

Returns true when either a file or directory exists.

fs.isFile(path)

fs.isFile(path: string|Path): boolean

Returns true only for an existing file.

fs.isDir(path)

fs.isDir(path: string|Path): boolean

Returns true only for an existing directory.

The three existence tests return false for a missing path; they do not distinguish a missing path from an inaccessible path when the underlying .NET existence check reports false.

fs.size(path)

fs.size(path: string|Path): number

Returns the byte length of an existing file as a script number. A missing file or directory path raises AuroraRuntimeException; directory aggregate size is not calculated. Integer precision is exact through Number.MAX_SAFE_INTEGER.

fs.mkDir(path)

fs.mkDir(path: string|Path): boolean

Creates the directory and all missing parents. Returns true when the directory already exists or creation succeeds.

fs.dir(path)

fs.dir(path: string|Path): string[]

Returns only the names of immediate child files and directories. It is not recursive. Results are sorted using ordinal comparison so ordering is deterministic and culture-independent.

import fs from "fs";

export func inventory(directory) {
    return {
        exists: fs.isDir(directory),
        entries: fs.dir(directory)
    };
}

Copying, Moving, and Deleting

fs.copy(source, destination, overwrite = false)

fs.copy(
    source: string|Path,
    destination: string|Path,
    overwrite?: boolean
): boolean

Copies a file or recursively copies a directory tree and returns true.

• Existing destinations are rejected unless overwrite is explicitly true. An existing destination directory is merged rather than cleared, so unrelated destination entries remain.
• A directory cannot be copied into itself or one of its descendants.
• Directory symbolic links/reparse points are rejected instead of followed.
• A file copy requires the destination parent to exist. A directory copy creates the destination path and missing parents.

fs.move(source, destination, overwrite = false)

fs.move(
    source: string|Path,
    destination: string|Path,
    overwrite?: boolean
): boolean

Moves a file or directory and returns true. With overwrite = true, an existing destination file is overwritten and an existing destination directory is removed before the move. A directory cannot be moved into itself or a descendant.

fs.delete(path, recursive = false)

fs.delete(path: string|Path, recursive?: boolean): boolean

Deletes a file or directory. Returns false when the path does not exist. A non-empty directory fails unless recursive is explicitly true.

import fs from "fs";

export func replaceTree(source, destination) {
    if (fs.exist(destination)) {
        fs.delete(destination, true);
    }
    return fs.copy(source, destination);
}

Errors and Security

Invalid argument types and file-system failures are reported as AuroraRuntimeException. Messages identify the fs method and affected path, but scripts should not depend on operating-system-specific message text.

fs grants direct access under the identity of the host process; it is not confined to the script source root. Validate or construct paths in trusted host code, use Path.isUnderRoot for application-level containment checks, and rely on process/OS isolation for untrusted scripts.