feat(ext/node): add experimental node:vfs polyfill

[divybot]

Summary

Adds an experimental node:vfs polyfill to Deno, providing an in-memory virtual filesystem with an fs-compatible API.

The implementation is ported from @platformatic/vfs (the package extracted from nodejs/node#61478, which itself is currently open and experimental).

What's included

• VirtualFileSystem with sync, callback, and promises APIs.
• MemoryProvider (the default storage backend) and VirtualProvider base class for custom providers.
• File-descriptor table for openSync/readSync/closeSync/fstatSync.
• createReadStream (Readable) lazily wired to node:stream.
• Mount / unmount state tracking and process.emit("vfs-mount" / -unmount) events.
• VirtualStats + VirtualDirent fs-compatible shapes.
• Symlink + lstat/realpath resolution with loop detection.
• Optional virtual cwd ({ virtualCwd: true } patches process.cwd/process.chdir).
• TypeScript definitions in cli/tsc/dts/node/vfs.d.cts.

What's intentionally left out

Node's mount() machinery patches Node-internal require(), Module._resolveFilename, and core fs functions (readFileSync, statSync, existsSync, readdirSync, realpathSync, watch, ...) so that the rest of the process transparently sees the virtual files. That half doesn't translate to Deno's loaders and is intentionally not implemented in this polyfill - the VirtualFileSystem instance itself is the namespace through which callers interact with the virtual files. Mount/unmount state is still tracked, so user code that branches on vfs.mounted or listens for the vfs-mount/vfs-unmount events continues to work.

Example

import { create } from "node:vfs";

const vfs = create();
vfs.mkdirSync("/app", { recursive: true });
vfs.writeFileSync("/app/file.txt", "hello");
vfs.readFileSync("/app/file.txt", "utf8"); // 'hello'

// Mount, observe the lifecycle:
vfs.mount("/app");
vfs.shouldHandle("/app/file.txt"); // true

// Promises API:
await vfs.promises.readFile("/app/file.txt", "utf8");

Test plan

• cargo build --bin deno (clean build)
• cargo build -p deno_node (cargo check)
• tools/lint.js --js
• deno fmt --check clean for changed files
• target/debug/deno test --no-check --config import_map.json tests/unit_node/vfs_test.ts - 26 passed, 0 failed

The new spec coverage exercises:

• writeFileSync/readFileSync round-trip (Buffer + string encoding paths)
• existsSync (present + missing)
• statSync (size, isFile/isDirectory)
• mkdirSync recursive + readdirSync (with and without withFileTypes)
• unlinkSync, renameSync, copyFileSync
• appendFileSync (multi-step append)
• ENOENT / EEXIST / EROFS error codes
• readonly provider via MemoryProvider.setReadOnly()
• symlinkSync / readlinkSync / lstatSync + symlink-following statSync
• File descriptor open/read/fstat/close round-trip
• mount + shouldHandle + unmount lifecycle, double-mount throws
• Callback API readFile/writeFile
• Promises API readFile/writeFile/mkdir/readdir/stat + missing-file rejection
• Custom provider extending VirtualProvider
• createReadStream consumed via for await
• virtualCwd: true chdir/cwd round-trip + cwd() throws when disabled
• internalModuleStat return values for dirs, files, and missing

Closes denoland/divybot#371

[littledivy]

This is the PR that merged in Node. Base your implementation on this nodejs/node#63115

[bartlomieju]

Has this even landed in Node yet?

[divybot]

Yes — landed upstream as nodejs/node#63115, merged 2026-05-23 (commit c9562ddb82dde83eb6e9c62aa8055b345a46b575) and shipped behind --experimental-vfs. The original PR description here pointed at the broader nodejs/node#61478, which is still open and tracks the mount() / require-hook integration as a follow-up.

@littledivy flagged the same thing yesterday, and I've just force-pushed a rewrite to base the implementation on the merged sub-PR. New surface matches upstream: VirtualFileSystem, VirtualProvider, MemoryProvider, RealFSProvider, VirtualFileHandle / MemoryFileHandle, VirtualDir, the polling VFSWatcher / VFSStatWatcher / VFSWatchAsyncIterable, plus the full sync / callback / promises method set documented in doc/api/vfs.md. The Deno-specific extensions from the previous draft (mount(), virtualCwd, internalModuleStat, vfs-mount/-unmount process events) have been dropped to keep parity. Stats are real fs.Stats instances now.

[littledivy]

It's experimental. Let's wait for stable. Closing to free queue