fs

Node-style file I/O rooted at the script’s data/ folder.

File I/O shaped like Node’s fs. Every async function has a *Sync twin that blocks until it’s done.

import fs from "@native/fs";

Relative paths start at the script’s data/ folder. Without the filesystem permission everything stays inside it, and paths leading out throw. With it, absolute paths work as usual.

Overview

Reading and writing

readFile, writeFile, appendFile.

Files and directories

exists, stat, mkdir, rmdir, readdir, …

Watching

watch, FSWatcher.

Paths

fs.path.join, basename, …

Failures throw (or reject) an Error with a Node-style code such as ENOENT. See Errors.

---

Reading and writing

readFile

fs.readFile(path: string, options?: BufferEncoding | { encoding?: BufferEncoding | null } | null): Promise<string | Uint8Array>
fs.readFileSync(path: string, options?: ...): string | Uint8Array

Reads a whole file: a Uint8Array without an encoding, a string with one.

const raw = await fs.readFile("icon.png");                 // Uint8Array
const config = JSON.parse(fs.readFileSync("config.json", "utf8"));

Encodings: utf8, latin1, ascii, hex, base64, base64url, utf16le.

writeFile

fs.writeFile(path: string, data: string | BufferSource, options?: BufferEncoding | { encoding?: BufferEncoding | null } | null): Promise<void>
fs.writeFileSync(path, data, options?): void

Creates or replaces a file. Strings are written as UTF-8 unless you pass an encoding.

await fs.writeFile("output.txt", "Hello, world!");
fs.writeFileSync("dump.bin", new Uint8Array([1, 2, 3]));
fs.writeFileSync("key.bin", "deadbeef", "hex");

appendFile

fs.appendFile(path: string, data: string | BufferSource, options?): Promise<void>
fs.appendFileSync(path, data, options?): void

Same as writeFile, but appends, and creates the file when it doesn’t exist.

fs.appendFileSync("kills.log", `${new Date().toISOString()} kill\n`);

---

Files and directories

exists

fs.exists(path: string): Promise<boolean>
fs.existsSync(path: string): boolean

true when something exists at path.

if (!fs.existsSync("config.json")) fs.writeFileSync("config.json", "{}");

stat

fs.stat(path: string): Promise<Stats>
fs.statSync(path: string): Stats

Throws ENOENT when nothing is there.

const st = fs.statSync("config.json");
console.log(st.size, new Date(st.mtimeMs), st.isFile());

Stats member
size	bytes, 0 for directories
atimeMs, mtimeMs, birthtimeMs	ms since the Unix epoch
isFile(), isDirectory()
isSymbolicLink()	always false

mkdir

fs.mkdir(path: string, options?: { recursive?: boolean }): Promise<void>
fs.mkdirSync(path, options?): void

Creates a directory. With recursive it also creates missing parents and doesn’t fail when the directory already exists.

await fs.mkdir("saves/p1", { recursive: true });

rmdir

fs.rmdir(path: string, options?: { recursive?: boolean }): Promise<void>
fs.rmdirSync(path, options?): void

Removes a directory. Without recursive it must be empty (ENOTEMPTY).

fs.rmdirSync("cache", { recursive: true });

Other operations

Function
readdir(path): Promise<string[]>	entry names (not paths), without . and ..
unlink(path): Promise<void>	deletes a file
rename(oldPath, newPath): Promise<void>	moves or renames, replacing an existing file
copyFile(src, dest): Promise<void>	copies a file, replacing an existing one
truncate(path, length = 0): Promise<void>	shrinks or zero-extends to length bytes

Each has a *Sync twin.

for (const name of await fs.readdir("saves"))
    if (fs.path.extname(name) === ".tmp") await fs.unlink(fs.path.join("saves", name));

---

Watching

watch

fs.watch(path: string, listener: (eventType: "rename" | "change", filename: string | null) => void,
         options?: { recursive?: boolean; signal?: AbortSignal }): FSWatcher

Calls listener for every change: "rename" for created, deleted or renamed entries, "change" for modified ones. filename is relative to the watched path, and can be null.

const watcher = fs.watch("configs", (event, name) => console.log(event, name), { recursive: true });
watcher.close();

A listener that throws doesn’t stop the watcher. Watchers close on unload, or earlier with close(), using or an aborted signal.

---

Paths

fs.path has the common helpers of Node’s path (Windows flavour). String work only, no I/O.

Function	Example
join(...paths)	join("saves", "p1", "../p2", "a.json") → "saves\\p2\\a.json"
basename(path, suffix?)	basename("saves/p1/a.json", ".json") → "a"
dirname(path)	dirname("saves/p1/a.json") → "saves/p1"
extname(path)	extname("a.json") → ".json", extname(".bashrc") → ""
isAbsolute(path)	true for "C:\\x", "\\x", "\\\\server\\share"; false for "C:x"

---

Errors

Errors carry Node’s code (ENOENT, EEXIST, ENOTEMPTY, …) and the path you passed.

try {
    fs.readFileSync("missing.json", "utf8");
} catch (e) {
    if ((e as { code?: string }).code !== "ENOENT") throw e;
}

---

Example

A JSON settings file that reloads when you edit it.

import fs from "@native/fs";

type Settings = { fov: number; color: string };
const defaults: Settings = { fov: 90, color: "#ff4040" };
let settings = defaults;

function load(): void {
    try {
        settings = { ...defaults, ...JSON.parse(fs.readFileSync("settings.json", "utf8")) };
    } catch (e) {
        if ((e as { code?: string }).code === "ENOENT")
            fs.writeFileSync("settings.json", JSON.stringify(defaults, null, 2));
        else
            console.warn("settings.json:", e);
    }
}

load();
fs.watch(".", (event, name) => {
    if (name === "settings.json") load();
});

on("tick", () => { /* use settings.fov, settings.color */ });