node:fs

const fs = require("node:fs");

fs.writeFileSync("out.txt", "written by Elide\n");
const text = fs.readFileSync("out.txt", "utf8");

const st = fs.statSync("out.txt");
console.log(st.isFile(), st.size);

try {
  fs.readFileSync("does-not-exist");
} catch (err) {
  console.log(err.code, err.errno, err.syscall); // ENOENT -2 open
}

Asynchronous API (callbacks)

Every operation with a Node callback form is supported; the last argument is a Node-style (err, ...results) callback invoked on the event loop. The names are the base names (no Sync suffix): readFile, writeFile, appendFile, open, close, read, write, mkdir, rm, rmdir, unlink, rename, copyFile, cp, link, symlink, readlink, readdir, opendir, glob, realpath, mkdtemp, stat, lstat, fstat, statfs, access, chmod / lchmod / fchmod, chown / lchown / fchown, utimes / lutimes / futimes, truncate, ftruncate, fsync, fdatasync. fs.exists(path, cb) is also provided — its callback receives a single boolean, matching Node's legacy signature.

const fs = require("node:fs");

fs.writeFile("out.txt", "async write\n", (err) => {
  if (err) throw err;
  fs.readFile("out.txt", "utf8", (err, text) => {
    console.log(text.trimEnd());
  });
});

Promise API (fs.promises / node:fs/promises)

The promise API resolves via require('node:fs/promises'), import 'node:fs/promises', or require('fs').promises — all yield the same namespace. Each operation returns a Promise; failures reject with the same Node SystemError shape as the synchronous API.

import { readFile, writeFile } from "node:fs/promises";

await writeFile("out.txt", "via promises\n");
console.log((await readFile("out.txt", "utf8")).trimEnd());

FileHandle

import { open } from "node:fs/promises";

const fh = await open("out.txt", "r");
try {
  const { bytesRead, buffer } = await fh.read(Buffer.alloc(64), 0, 64, 0);
  console.log(buffer.subarray(0, bytesRead).toString("utf8"));
} finally {
  await fh.close();
}

Cancellation (AbortSignal)

File streams

import { createReadStream, createWriteStream } from "node:fs";

createReadStream("big.log").pipe(createWriteStream("copy.log"));

The FileHandle stream helpers reuse the open descriptor: fileHandle.createReadStream(), createWriteStream(), readableWebStream() (a WHATWG ReadableStream), and readLines() (an async iterable of lines). Unlike the top-level streams these default to autoClose: false — the FileHandle owns the descriptor.

Watching

const watcher = fs.watch("./src", { recursive: true }, (event, file) => {
  console.log(event, file);
});
// later: watcher.close();

Capability sandbox

Elide can confine filesystem access with a per-path, per-operation capability policy, modeled on Deno's read/write scoping but enforced at a single host-side gate shared by every guest language:

• Each capability (read, write) is either fully granted or restricted to a set of path roots; a path is allowed only when it is at or under a granted root.
• Checks canonicalize the target (toRealPath) before matching, so .. and symlink escapes cannot evade the policy. The operation then runs against the resolved-ancestor path, so an ancestor symlink cannot be swapped between the check and the syscall (the remaining check→use window — a swap of the final component itself — needs openat/O_NOFOLLOW and is tracked as hardening).
• A denied node:fs operation fails with a Node EACCES SystemError; a denied polyglot operation fails with the engine's SecurityException.
• The same FsPolicy gates node:fs, node:fs/promises, streams, watchers, and the polyglot FileSystem (Python open, JS import, JVM file access) — one sandbox for the whole runtime.

The default policy grants all access, matching the historical behavior; a restricted policy is opt-in.

Enabling it from the command line

The sandbox is activated by global flags. They are honored wherever Elide builds a guest runtime — elide run, the implicit elide form, inline snippets (-s/--snippet), and the elide mcp server — and apply to every guest language:

• --sandbox turns the sandbox on. With no grants it denies all filesystem access; pair it with --allow-read / --allow-write to open holes.
• --allow-read[=PATHS] grants reads. Bare --allow-read grants every read; --allow-read=/a,/b scopes it to those roots. Repeatable, and any occurrence implies --sandbox.
• --allow-write[=PATHS] grants writes, with the same bare-vs-scoped semantics.
• --fs-audit logs each access decision to stderr.

# Read-only access confined to the project directory:
 elide --sandbox --allow-read=. server.js

# Read anywhere, write only to a scratch dir:
 elide --allow-read --allow-write=/tmp/scratch build.js

Known differences from Node

Some details cannot be reproduced faithfully through java.nio and are documented rather than faked:

• statfsSync reports bsize and the block counts from the JDK FileStore; the on-disk filesystem type and the inode counters (files / ffree) are reported as 0.
• lchmodSync throws ENOSYS (it has no portable POSIX implementation, matching Node on Linux).
• stat/lstat/readdir resolve the real file type (regular, directory, symlink, block/character device, FIFO, socket) from the raw st_mode on POSIX. On platforms without the unix attribute view (e.g. Windows) special files fall back to "unknown".
• birthtime is best-effort on Linux: the JDK cannot read statx's creation time, so it mirrors the JDK's creationTime() (often the change time). ctime uses the real unix:ctime where available.
• fs.watch uses one OS watch instance per watcher (Linux inotify is not multiplexed as libuv does), so a process that holds very many concurrent watchers can hit the kernel's max_user_instances limit. Always close() watchers you no longer need; dropped ones are reclaimed only best-effort on GC.
• glob / globSync use a Node-style matcher: , * (globstar — a leading **/ matches top-level entries too), ?, character classes ([...]/[!...]), and brace alternation ({a,b}). Extended-glob groups (@(...), +(...), !(...)) are not supported.

Not yet implemented

• fs.openAsBlob.

See also

• Node.js upstream:
• node:os API Reference
• node:path API Reference