{ } qjs-modules

vfs

Source: lib/vfs.js (pure JS; ArchiveProvider needs the native archive module)

Virtual file systems with a node:fs-like API, modelled on Node's node:vfs (26.4+, experimental). import vfs from 'node:vfs' resolves here under qjsm (loaders/node).

import vfs from 'node:vfs';

const v = vfs.create();                    // MemoryProvider
v.mkdirSync('/dir', { recursive: true });
v.writeFileSync('/dir/a.txt', 'hi');
v.readFileSync('/dir/a.txt', 'utf8');      // 'hi'
await v.promises.readdir('/dir');          // ['a.txt']

Exports

ExportKindDescription
create(provider?, options?)functionnew VirtualFileSystem(provider); default provider is a MemoryProvider.
VirtualFileSystemclassThe fs-like API over one provider.
VirtualProviderclassBase class of providers; subclass it for a custom file system.
MemoryProviderclassFiles, directories, symlinks in memory; setReadOnly().
RealFSProvider(root)classA real directory as the root. A path mapping, not a sandbox.
ComposableProvider(providers)classLayers providers: first is writable, reads fall through, removals hide lower copies.
ArchiveProvider(file)classRead-only view of a tar/zip/... file (not in node:vfs).
defaultobjectAll of the above, as node:vfs's default export.

VirtualFileSystem

Paths are POSIX and absolute (.. stops at /); relative paths are taken from /. Errors are SyscallError with code and path. Without an encoding readFileSync returns a Uint8Array.

GroupMembers
syncexistsSync statSync lstatSync readFileSync writeFileSync appendFileSync readdirSync mkdirSync rmdirSync unlinkSync renameSync copyFileSync realpathSync readlinkSync symlinkSync accessSync rmSync truncateSync chmodSync utimesSync mkdtempSync
fdopenSync closeSync readSync writeSync fstatSync fsyncSync ftruncateSync; fds are numbers >= 10000, buffered and written to the provider on closeSync/fsyncSync or before the next path call
callbackreadFile(path, cb) etc. for every name above that has a callback form in Node (access appendFile chmod close copyFile fstat ftruncate lstat mkdir mkdtemp open read readFile readdir readlink realpath rename rm rmdir stat symlink truncate unlink utimes write writeFile)
promisesvfs.promises.*, the same names minus the fd ones
propsprovider, readonly

readdirSync takes { withFileTypes, recursive }; mkdirSync takes { recursive } and returns the first directory created; statSync takes { throwIfNoEntry }.

Writing a provider

A provider receives absolute, normalized paths and implements path primitives; everything else (exists, access, append, copyFile, truncate, mkdtemp, rm, realpath) is derived by the base class:

PrimitiveReturns / does
statSync(path)fs.Stats (follows symlinks)
readdirSync(path)array of names
readFileSync(path)Uint8Array with the whole file
writeFileSync(path, bytes, mode?)create or replace
mkdirSync(path, recursive), rmdirSync, unlinkSync, renameSync(from, to)as in fs
optionallstatSync readlinkSync symlinkSync chmodSync utimesSync, getters readonly, supportsSymlinks

A primitive left out throws ERR_METHOD_NOT_IMPLEMENTED, or EROFS when the provider is readonly.

Not implemented

mount()/unmount() (redirecting fs, require, import), createReadStream/ createWriteStream, watch, opendir, openAsBlob, registerProvider. Providers differ from Node's: whole-file readFileSync/writeFileSync instead of open, so a custom provider is not portable to node:vfs.

Export list

Generated by utilities/doc-api.js from the vfs dump of utilities/api-surface.sh: 156 members. Edit the text above this block, not the block.

Functions: create()

ArchiveProvider

class, constructible

  • methods: lstatSync(), readFileSync(), readdirSync(), readlinkSync(), statSync()
  • properties: readonly (get), supportsSymlinks (get)

ComposableProvider

class, constructible

  • methods: chmodSync(), lstatSync(), mkdirSync(), readFileSync(), readdirSync(), readlinkSync(), renameSync(), rmdirSync(), statSync(), symlinkSync(), unlinkSync(), utimesSync(), writeFileSync()
  • properties: providers (get), readonly (get), supportsSymlinks (get)

MemoryProvider

class, constructible

  • methods: chmodSync(), lstatSync(), mkdirSync(), readFileSync(), readdirSync(), readlinkSync(), renameSync(), rmdirSync(), setReadOnly(), statSync(), symlinkSync(), unlinkSync(), utimesSync(), writeFileSync()
  • properties: readonly (get), supportsSymlinks (get)

RealFSProvider

class, constructible

  • methods: chmodSync(), lstatSync(), mkdirSync(), readFileSync(), readdirSync(), readlinkSync(), renameSync(), rmdirSync(), statSync(), symlinkSync(), unlinkSync(), utimesSync(), writeFileSync()
  • properties: rootPath (get), supportsSymlinks (get)

VirtualFileSystem

class, constructible

  • methods: access(), accessSync(), appendFile(), appendFileSync(), chmod(), chmodSync(), close(), closeSync(), copyFile(), copyFileSync(), existsSync(), fstat(), fstatSync(), fsyncSync(), ftruncate(), ftruncateSync(), lstat(), lstatSync(), mkdir(), mkdirSync(), mkdtemp(), mkdtempSync(), open(), openSync(), read(), readFile(), readFileSync(), readSync(), readdir(), readdirSync(), readlink(), readlinkSync(), realpath(), realpathSync(), rename(), renameSync(), rm(), rmSync(), rmdir(), rmdirSync(), stat(), statSync(), symlink(), symlinkSync(), truncate(), truncateSync(), unlink(), unlinkSync(), utimes(), utimesSync(), write(), writeFile(), writeFileSync(), writeSync()
  • properties: promises (get), provider (get), readonly (get), [Symbol.toStringTag]

VirtualProvider

class, constructible

  • methods: accessSync(), appendFileSync(), chmodSync(), copyFileSync(), existsSync(), lstatSync(), mkdirSync(), mkdtempSync(), readFileSync(), readdirSync(), readlinkSync(), realpathSync(), renameSync(), rmSync(), rmdirSync(), statSync(), symlinkSync(), truncateSync(), unlinkSync(), utimesSync(), writeFileSync()
  • properties: readonly (get), supportsSymlinks (get)

default

object

  • static methods: ArchiveProvider(), ComposableProvider(), MemoryProvider(), RealFSProvider(), VirtualFileSystem(), VirtualProvider(), create()