fs
Source: lib/fs.js (pure JS) — has a default export object bundling the API
A Node-fs-style filesystem module with synchronous and stream APIs, built on
QuickJS std/os. All promise-returning functions live in the separate
fsPromises module (matching Node/Bun, where non-Sync
names on fs are callback-based, not promise-based) — fs itself has no
promise API of its own.
Standard streams & helpers
stdin, stdout, stderr (constants). Buffer helpers: buffer(length),
bufferFrom(chunk, offset, length), bufferSize(buf), bufferArgument(arg),
bufferArguments(arg, offset, length), stringOrBufferArguments(arg, …),
bufferToString(buf, offset, length), throwIfNull(error, fn, …).
Classes
| Class | Description |
|---|---|
Stats | stat-result object (isFile(), isDirectory(), size, times, mode, …). |
Dirent | readdir/opendir-entry object (isFile(), isDirectory(), name, …). |
FileHandle | Open-file handle with read/write/close methods (sync here; see fsPromises's open() for the promise-returning wrapper). |
Dir | Directory handle returned by opendirSync() — iterable, plus readSync()/closeSync(). |
inotify_event | ArrayBuffer subclass decoding an inotify event. |
Synchronous API
| Function | Args | Description |
|---|---|---|
openSync(filename, flags='r', mode=0o644) | 1–3 | Opens a file → fd. |
fopenSync(filename, flags, mode) / fdopenSync(fd, flags) | 1–3 | Open as a FILE. |
closeSync(fd) | 1 | Closes an fd. |
readSync(fd, buffer, offset, length, position?) | 4–5 | Reads into a buffer; a numeric position reads there and leaves the offset alone (Node's pread). |
writeSync(fd, buffer, offset, length, position?) | 4–5 | Writes from a buffer; position as for readSync(). |
readvSync(fd, buffers, position?) | 2–3 | Fills an array of buffers in order in one call (readv, preadv with a numeric position). |
writevSync(fd, buffers, position?) | 2–3 | Writes an array of buffers in order in one call (writev, pwritev). |
readFileSync(file, options) | 1–2 | Reads a whole file. |
openAsBlob(path, options?) | 1–2 | Node's fs.openAsBlob(): a promise of a Blob over a read-only mapping of the file (mmap), no copy; options.type sets the MIME type. Throws synchronously when the file cannot be opened or is a directory. The Blob follows the file: changed bytes show through, and truncating the file while the Blob lives makes a read fault (SIGBUS), where Node throws NotReadableError. |
openAsBlobSync(path, options?) | 1–2 | The same, returning the Blob directly (no Node/Bun/Deno equivalent). |
writeFileSync(file, data, options) | 2–3 | Writes a whole file. |
appendFileSync(path, data, options) | 2–3 | Appends to a file, creating it if needed. |
readdirSync(path, options) | 1–2 | Lists a directory (withFileTypes, recursive). |
opendirSync(path) | 1 | Opens a directory as an iterable Dir. |
statSync / lstatSync(path) | 1 | File status. |
existsSync(path) | 1 | Existence test. |
mkdirSync(path, options=0o777) | 1–2 | Creates a directory; options is a mode number or {recursive, mode}. |
mkdtempSync(prefix) | 1 | Creates a fresh, uniquely-named directory under prefix. |
renameSync(old, new) | 2 | Renames. |
unlinkSync(path) | 1 | Removes a file. |
rmdirSync(path) | 1 | Removes an empty directory. |
rmSync(path, options) | 1–2 | Removes a file or (with {recursive: true}) a directory tree; {force: true} ignores a missing path. |
copyFileSync(src, dest, flags) | 2–3 | Copies a file. |
cpSync(src, dest, options) | 2–3 | Copies a file, or (with {recursive: true}) a directory tree. |
linkSync / symlinkSync | 2 | Creates links. |
readlinkSync / realpathSync(path) | 1 | Resolves links. |
accessSync(pathname, mode) | 2 | Accessibility check. |
chmodSync(path, mode) / chownSync(path, uid, gid) | 2–3 | Changes mode/ownership (opens the path and uses the fd-based syscall — no path-based binding is exposed). |
fstatSync(fd) | 1 | Stats of an open fd. |
ftruncateSync(fd, len=0) | 1–2 | Truncates an open fd. |
fsyncSync(fd) / fdatasyncSync(fd) | 1 | Flushes an open fd to disk. |
truncateSync(path, len=0) | 1–2 | Truncates a file (same fd-based approach as chmodSync/chownSync). |
utimesSync(path, atime, mtime) | 3 | Sets access/modification times (Date or seconds-since-epoch). |
seek(fd, offset, whence) / tell(file) | 1–3 | File-position control. |
sizeSync(file) / nameSync(file) / fileno(file) | 1 | File metadata. |
getcwd() / chdir(path) / isatty(file) | 0–1 | Process/file helpers. |
tmpfileSync() / mkstempSync(template) / tempnamSync(dir, pfx) | 0–2 | Temp files. |
flushSync(f) / pipe() | 0–1 | Flush / create a pipe. |
puts(fd, str) / gets(fd) | 1–2 | Line write / read. |
There's no path-based chmod(2)/chown(2)/truncate(2) binding available (only
the fd-based fchmod/fchown/ftruncate used by FileHandle), so the *Sync
versions above open the path (read-only for chmodSync/chownSync, write-only
for truncateSync) and use those instead — this doesn't work for a symlink's
own metadata (that needs the non-following lchmod/lchown/lutimes syscalls,
which aren't implemented; see BUGS).
Streaming readers
| Function | Args | Description |
|---|---|---|
readerSync(input, bufferOrBufSize=1024) | 1–2 | Generator of chunks. |
readAllSync(input, bufSize) | 1–2 | Reads everything (sync). |
readFullySync(input, buf, start, n) | 2–4 | Fills a buffer fully. |
createReadStream(path, options) | 1–2 | Node-style readable stream. |
createWriteStream(path, options) | 1–2 | Node-style writable stream. |
The promise-based reader()/readAll() (async-iterator/fd equivalents of the
two above) live in fsPromises, along with the non-standard
raw-fd read()/write() — see that module's doc for why they're there
despite not being part of Node/Bun's fs/promises.
Event helpers
onRead(file, handler), waitRead(file), onWrite(file, handler),
waitWrite(file).
watch(filename, options, callback)
Node-compatible fs.watch(), backed by inotify (via the native misc
module). Watches a single path (not recursive - matching Node's own
Linux behavior) and returns an FSWatcher (EventEmitter) that emits
'change'/'rename' with the affected entry's name, mirroring Node's
(eventType, filename) callback shape:
import { watch } from 'fs';
const w = watch('./some-dir', {}, (eventType, filename) => {
console.log(eventType, filename); // 'rename' | 'change', e.g. "foo.txt"
});
w.close(); // stop watchingoptions.mask— raw inotify event mask (default: all events).options.signal— anAbortSignal(see theabortmodule); aborting it closes the watcher, same as calling.close().- The watcher emits
'error'if the underlying inotify read fails, and'close'once, whether closed explicitly, viaoptions.signal, or after an error. - An invalid path throws synchronously (matching Node), rather than returning an error value.
See also fsPromises.watch() for the async-iterator form.
Constants
constants (object) plus individual FD_CLOEXEC, F_* (fcntl), and O_*
(open) flag exports.
Callback API and fs.promises
Every *Sync function has the Node callback form, derived from it: readFile,
writeFile, appendFile, access, stat, lstat, fstat, readdir, mkdir,
mkdtemp, rmdir, rm, unlink, rename, readlink, realpath, symlink, link,
truncate, ftruncate, fsync, fdatasync, copyFile, cp, chmod, chown,
utimes, open, close, read, write, exists. The work runs synchronously and the
callback on a later tick (cb(err) or cb(null, result)). fs.promises is the
fsPromises module, loaded on first access; fs/promises resolves to it as well.
No ReadStream/WriteStream.
Export list
Generated by utilities/doc-api.js from the fs dump of utilities/api-surface.sh: 425 members. Edit the text above this block, not the block.
Functions: InvalidBuffer(), access(), accessSync(), appendFile(), appendFileSync(), buffer(), bufferArgument(), bufferArguments(), bufferFrom(), bufferSize(), bufferToString(), chdir(), chmod(), chmodSync(), chown(), chownSync(), close(), closeSync(), copyFile(), copyFileSync(), cp(), cpSync(), createReadStream(), createWriteStream(), exists(), existsSync(), fdatasync(), fdatasyncSync(), fdopenSync(), fileno(), flushSync(), fopenSync(), fstat(), fstatSync(), fsync(), fsyncSync(), ftruncate(), ftruncateSync(), getcwd(), gets(), isatty(), lchownSync(), link(), linkSync(), lstat(), lstatSync(), lutimesSync(), mkdir(), mkdirSync(), mkdtemp(), mkdtempSync(), mkstempSync(), nameSync(), onRead(), onWrite(), open(), openAsBlob(), openAsBlobSync(), openSync(), opendirSync(), pipe(), puts(), read(), readAllSync(), readFile(), readFileSync(), readFullySync(), readSync(), readdir(), readdirSync(), readerSync(), readlink(), readlinkSync(), readv(), readvSync(), realpath(), realpathSync(), rename(), renameSync(), rm(), rmSync(), rmdir(), rmdirSync(), seek(), sizeSync(), stat(), statSync(), stringOrBufferArguments(), symlink(), symlinkSync(), tell(), tempnamSync(), throwIfNull(), tmpfileSync(), truncate(), truncateSync(), unlink(), unlinkSync(), utimes(), utimesSync(), waitRead(), waitWrite(), walkSync(), watch(), write(), writeFile(), writeFileSync(), writeSync(), writev(), writevSync(), promises[Symbol.toStringTag]()
Values: FD_CLOEXEC = 1, F_DUPFD = 0, F_DUPFD_CLOEXEC = 1030, F_GETFD = 1, F_GETFL = 3, F_GETLK = 5, F_RDLCK = 0, F_SETFD = 2, F_SETFL = 4, F_SETLK = 6, F_SETLKW = 7, F_UNLCK = 2, F_WRLCK = 1, O_ASYNC = 8192, O_CLOEXEC = 524288, O_DSYNC = 4096, O_NOCTTY = 256, O_NONBLOCK = 2048, O_SYNC = 1052672
Dir
class, constructible
- methods:
closeSync(),readSync(),[Symbol.iterator]() - properties:
path (get)
Dirent
class, constructible
- methods:
isBlockDevice(),isCharacterDevice(),isDirectory(),isFIFO(),isFile(),isSocket(),isSymbolicLink() - properties:
name,[Symbol.toStringTag]
FileHandle
class, constructible
- methods:
appendFile(),chmod(),chown(),close(),datasync(),read(),readFile(),readv(),stat(),sync(),truncate(),utimes(),write(),writeFile(),writev() - properties:
fd (get),[Symbol.toStringTag]
Stats
class, constructible
- methods:
isBlockDevice(),isCharacterDevice(),isDirectory(),isFIFO(),isFile(),isSocket(),isSymbolicLink() - properties:
atime,blocks,ctime,dev,gid,ino,mode,mtime,nlink,rdev,size,uid,[Symbol.toStringTag]
inotify_event
class, constructible
- static methods:
from() - methods:
toString() - properties:
cookie (get/set),len (get/set),mask (get/set),name (get/set),wd (get/set)
constants
object
- static values:
COPYFILE_EXCL = 1,COPYFILE_FICLONE = 2,COPYFILE_FICLONE_FORCE = 4,F_OK = 0,O_APPEND = 1024,O_CREAT = 64,O_DIRECT = 16384,O_DIRECTORY = 65536,O_DSYNC = 4096,O_EXCL = 128,O_NOATIME = 262144,O_NOCTTY = 256,O_NOFOLLOW = 131072,O_NONBLOCK = 2048,O_RDONLY = 0,O_RDWR = 2,O_SYNC = 1052672,O_TRUNC = 512,O_WRONLY = 1,R_OK = 4,S_IFBLK = 24576,S_IFCHR = 8192,S_IFDIR = 16384,S_IFIFO = 4096,S_IFLNK = 40960,S_IFMT = 61440,S_IFREG = 32768,S_IFSOCK = 49152,S_IRGRP = 32,S_IROTH = 4,S_IRUSR = 256,S_IRWXG = 56,S_IRWXO = 7,S_IRWXU = 448,S_IWGRP = 16,S_IWOTH = 2,S_IWUSR = 128,S_IXGRP = 8,S_IXOTH = 1,S_IXUSR = 64,W_OK = 2,X_OK = 1
default
object
- static methods:
Stats(),access(),accessSync(),appendFile(),buffer(),bufferFrom(),bufferSize(),bufferToString(),chdir(),chmod(),chown(),close(),closeSync(),copyFile(),cp(),createReadStream(),createWriteStream(),exists(),existsSync(),fdatasync(),fdatasyncSync(),fdopenSync(),fileno(),fopenSync(),fstat(),fstatSync(),fsync(),fsyncSync(),ftruncate(),ftruncateSync(),getcwd(),gets(),isatty(),link(),lstat(),lstatSync(),mkdir(),mkdirSync(),mkdtemp(),mkstempSync(),nameSync(),onRead(),onWrite(),open(),openAsBlob(),openAsBlobSync(),openSync(),pipe(),puts(),read(),readAllSync(),readFile(),readFileSync(),readSync(),readdir(),readdirSync(),readerSync(),readlink(),readlinkSync(),readv(),readvSync(),realpath(),realpathSync(),rename(),renameSync(),rm(),rmdir(),seek(),sizeSync(),stat(),statSync(),symlink(),symlinkSync(),tell(),tempnamSync(),tmpfileSync(),truncate(),unlink(),unlinkSync(),utimes(),waitRead(),waitWrite(),walkSync(),watch(),write(),writeFile(),writeFileSync(),writeSync(),writev(),writevSync() - static values:
EACCES = 13,EAGAIN = 11,EBUSY = 16,EEXIST = 17,EINVAL = 22,EIO = 5,ENOENT = 2,ENOSPC = 28,ENOSYS = 38,EPERM = 1,EWOULDBLOCK = 11,FD_CLOEXEC = 1,F_DUPFD = 0,F_DUPFD_CLOEXEC = 1030,F_GETFD = 1,F_GETFL = 3,F_GETLK = 5,F_RDLCK = 0,F_SETFD = 2,F_SETFL = 4,F_SETLK = 6,F_SETLKW = 7,F_UNLCK = 2,F_WRLCK = 1,O_APPEND = 1024,O_ASYNC = 8192,O_CLOEXEC = 524288,O_CREAT = 64,O_DSYNC = 4096,O_EXCL = 128,O_NOCTTY = 256,O_NONBLOCK = 2048,O_RDONLY = 0,O_RDWR = 2,O_SYNC = 1052672,O_TRUNC = 512,O_WRONLY = 1,constants,promises,stderr,stdin,stdout
promises
object
- static methods:
access(),appendFile(),chmod(),chown(),copyFile(),cp(),lchown(),link(),lstat(),lutimes(),mkdir(),mkdtemp(),mkdtempDisposable(),open(),opendir(),readFile(),readdir(),readlink(),realpath(),rename(),rm(),rmdir(),stat(),symlink(),truncate(),unlink(),utimes(),watch(),writeFile() - static values:
constants
stderr
object
- static methods:
columns(),fd(),getColorDepth(),getWindowSize(),hasColors(),isTTY(),rows()
stdin
object
- static methods:
columns(),fd(),isTTY(),rows()
stdout
object
- static methods:
columns(),fd(),getColorDepth(),getWindowSize(),hasColors(),isTTY(),rows()