The file-system module

Reference for node:fs and node:fs/promises in Cruft: reading and writing files, stat and permissions, directories and glob, watching, and fd-level I/O, in synchronous, callback, and promise forms. States which methods are real operations and which are shape-only stubs. All access is capability-gated.

Filesystem access in Cruft, exposed the way Node exposes it: synchronous (…Sync), Node-style callback, and promise (node:fs/promises) forms of the same operations. Per the compatibility map this module is at the focused depth tier: read/write, stat, readdir, glob, watch, and fd-level I/O are implemented as real operations; binary reads return a real Node Buffer (ArrayBuffer.isView is true, instanceof Uint8Array is true, and constructor.name is "Buffer"). Errors on the ordinary missing-file path carry Node-style .code (for example ENOENT), plus errno, syscall, and path where applicable. All operations are capability-gated through the runtime's capability layer. This page enumerates what is actually installed; anything not listed here is not present.

Import forms

All four specifiers resolve, in both module systems:

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

// CJS
const fs = require("node:fs");        // or require("fs")
const fsp = require("node:fs/promises"); // or require("fs/promises")

node:fs/promises is a distinct namespace (the promise API, not all of fs); it is also reachable as fs.promises.

Reading and writing files

Round-trip:

import fs from "node:fs";
fs.writeFileSync("/tmp/fsdemo/hello.txt", "hello cruft\n");
console.log(JSON.stringify(fs.readFileSync("/tmp/fsdemo/hello.txt", "utf8")));

$ cruft /tmp/demo.mjs
"hello cruft\n"

Binary reads return a real Node Buffer:

import fs from "node:fs";
const buf = fs.readFileSync("/tmp/fsdemo/hello.txt");
console.log(buf.constructor.name);
console.log(buf instanceof Uint8Array);
console.log(ArrayBuffer.isView(buf));
console.log(Array.from(buf.slice(0, 5)));

$ cruft /tmp/demo.mjs
Buffer
true
true
[ 104, 101, 108, 108, 111 ]

Metadata and permissions

import fs from "node:fs";
const st = fs.statSync("/tmp/fsdemo/hello.txt");
console.log(st.size, st.isFile(), st.isDirectory());

$ cruft /tmp/demo.mjs
12 true false

Directories and glob

import fs from "node:fs";
// cwd is /tmp/fsdemo
console.log(fs.globSync("*.txt").sort());
console.log(fs.globSync("**/*.txt").sort());

$ cruft /tmp/demo.mjs
[ 'h2.txt', 'hello.txt', 'p.txt', 'w.txt' ]
[ 'h2.txt', 'hello.txt', 'p.txt', 'sub/a.txt', 'sub/b.txt', 'w.txt' ]

Watching

import fs from "node:fs";
const w = fs.watch("/tmp/fsdemo");
console.log(typeof w.close, typeof w.on, typeof w.ref);
w.close();

$ cruft /tmp/demo.mjs
function function function

fd-level I/O

import fs from "node:fs";
const fd = fs.openSync("/tmp/fsdemo/hello.txt", "r");
const buf = new Uint8Array(5);
const n = fs.readSync(fd, buf, 0, 5, 0);
fs.closeSync(fd);
console.log(n, Array.from(buf));

$ cruft /tmp/demo.mjs
5 [ 104, 101, 108, 108, 111 ]

Promises API (node:fs/promises)

Every callback-form method above is mirrored as a promise on fs/promises (and fs.promises), plus constants:

Differences from Node worth knowing:

• open(path, flags) resolves a minimal FileHandle: fd, stat(), close(). Deeper FileHandle methods (read, write, readFile, createReadStream, …) are not on the handle.
• glob(pattern) returns an async iterator (Node-faithful): iterate it with for await (… of glob(…)); it is not an array, so Array.isArray is false and it has no Symbol.iterator.
• promises.watch returns an event-emitter watcher (close, on, off, ref, unref) that holds the loop open — not an async iterator (no Symbol.asyncIterator), and not undefined. Its ref/unref are no-ops: the watcher keeps the loop alive until you close() it, unref notwithstanding.

import { readFile, writeFile, glob } from "node:fs/promises";
await writeFile("/tmp/fsdemo/p.txt", "promise data\n");
console.log(JSON.stringify(await readFile("/tmp/fsdemo/p.txt", "utf8")));
const matches = [];
for await (const m of glob("*.txt")) matches.push(m); // async iterator, cwd /tmp/fsdemo
console.log(matches.includes("p.txt"));

$ cruft /tmp/demo.mjs
"promise data\n"
true

Not implemented / gaps

This list reflects the installed API surface. Unlisted APIs are not present. Do not assume Node parity beyond what this page documents.

• Callback wrappers over the …Sync impls: top-level chown, lchmod, lchown, readv, and writev callback forms are functional (their callbacks fire with real results/errors) rather than throw-on-call stubs.
• Class stubs: Stats, Dirent, Dir are present but not constructable (constructor throws). ReadStream, WriteStream, FileReadStream, FileWriteStream, Utf8Stream exist as shape-only constructor stubs; use createReadStream / createWriteStream for real streams.
• FileHandle is minimal: fd, stat(), close() only (see above).
• No BigInt stats: { bigint: true } options are not honored; stats fields are numbers.
• No fs.Dirent recursion options beyond what is documented; readdirSync { recursive: true } behavior beyond names/Dirents should be probed before relying on it.
• promises.watch returns an event-emitter watcher (close/on/off/ref/unref) with no async-iterator support, not undefined.
• Device/FIFO/socket stat predicates always return false.
• openAsBlob reports an empty type ("").