Filesystem Module

Core Operations

Fundamental filesystem methods for native I/O operations.

These methods descend directly from the FSCore instance and interact natively with the underlying XHSC engine.

ls

Retrieves the contents of a directory.

typescript

ls(p: string, options?: { stats?: boolean; recursive?: boolean }): string[] | [string, FileStats][]

typescript

// Simple list
const files = __sys__.fs.ls("/var/log/app");

// Detailed list with native XHSC FileStats
const detailed = __sys__.fs.ls("/var/log/app", { stats: true });

read / readSync

Reads file contents asynchronously or synchronously.

typescript

read(p: string, options?: { bytes?: boolean }): Promise<string>
readSync(p: string, options?: { bytes?: boolean }): string

typescript

const data = await __sys__.fs.read("CWD://config.json");
const template = __sys__.fs.readSync("ROOT://index.html");

Streams

High-performance streams processed entirely by the Go engine.

typescript

createReadStream(p: string, options?: { start?: number; end?: number }): Readable
createWriteStream(p: string): Writable & { close(): void }

typescript

const stream = __sys__.fs.createReadStream("ROOT://big-data.csv");
stream.pipe(res);

writeFile / writeFileSync

Writes data to storage. Parent directories are created automatically.

typescript

writeFile(p: string, data: any, options?: { append?: boolean; ensureFile?: boolean }): Promise<void>

Copy & Move

.copy(src, dest)

Duplicate files or directories.

.move(src, dest)

Relocate or rename entities.

Deletion & Structure

rm(p, options?)

Deletes a file or directory. Use force: true for recursive deletion.

mkdir(p, options?)

Creates directories. parents: true enables recursive creation (mkdir -p).

Stateful Handles (open/close)

The open method provides a stateful toolbox for efficient multi-operation tasks on a single handle.

Flag	Mode	Description
'r'	Read	Open for reading (default). Fails if missing.
'r+'	R/W	Open for reading and writing. Fails if missing.
'w'	Write	Open for writing. Created if missing, truncated if exists.
'a'	Append	Open for appending. Created if missing.

FileHandle Toolbox

Using the callback pattern in open gives you access to a toolbox with read(), write(), and seek() methods that communicate via optimized IPC sockets.

typescript

await __sys__.fs.open("data.bin", "r+", async (file) => {
    const header = await file.read(10);
    await file.seek(0, 2); // Jump to EOF
    await file.write(" [EOF SIGNATURE]");
});

Utility Primitives

.rmMany(paths[])

Bulk deletion of multiple paths.

.touch(path)

Create empty file or update timestamp.

.link(src, dest)

Create symbolic links.

.chmod(path, mode)

Change Unix permissions (e.g., '755').

Helpers & Utils

Explore JSON handling, line-by-line reading, and automated directory ensures.