{ } qjs-modules

fsPromises

Source: lib/fsPromises.js (pure JS)

Promise-based filesystem API mirroring Node's fs/promises. Every export listed here is a real implementation (each wraps the matching *Sync function from fs) — none of them are stubs.

It is reachable three ways, all the same functions: import ... from 'fsPromises', import ... from 'fs/promises' (or node:fs/promises; qjsm aliases the subpath) and fs.promises (loaded on first access). fs itself carries the Node callback API (fs.readFile(path, cb)), see fs.

Exports

All functions return promises (watch() returns an async iterator instead).

FunctionArgsDescription
open(filename, flags='r', mode=0o644)1–3Opens a file, resolving to a FileHandle-like object whose methods (read, write, readFile, writeFile, appendFile, stat, chmod, chown, truncate, utimes, sync, datasync, close) all return promises.
readFile(file, options)1–2Reads an entire file.
writeFile(file, data, options)2–3Writes an entire file.
appendFile(path, data, options)2–3Appends to a file, creating it if needed.
access(pathname, mode)2Checks accessibility.
stat(path) / lstat(path, options)1–2File status.
readdir(path, options)1–2Lists a directory (withFileTypes, recursive).
opendir(path, options)1–2Opens a directory as an iterable Dir (see fs.md).
mkdir(path, options=0o777)1–2Creates a directory; options is a mode number or {recursive, mode}.
mkdtemp(prefix, options)1–2Creates a fresh, uniquely-named directory under prefix.
rm(path, options)1–2Removes a file, or (with {recursive: true}) a directory tree; {force: true} ignores a missing path.
rmdir(path, options)1–2Removes an empty directory.
unlink(path)1Removes a file.
rename(oldname, newname)2Renames.
truncate(path, len)2Truncates.
copyFile(src, dest, mode)2–3Copies a file.
cp(src, dest, options)2–3Copies a file, or (with {recursive: true}) a directory tree.
link(existingPath, newPath) / symlink(target, path)2Creates links.
readlink(path) / realpath(path)1Resolves links.
chmod(path, mode)2Changes mode (same fd-based approach as fs.chmodSync — see fs.md).
chown(path, uid, gid)3Changes ownership (same caveat as chmod).
utimes(path, atime, mtime)3Sets access/modification times.
watch(filename, options)1–2Returns an AsyncIterable<{eventType, filename}> (see below).

Not implemented: lchmod, lchown, lutimes

lchmod doesn't exist here at all, matching upstream Node (removed except on macOS). lchown(path, uid, gid) and lutimes(path, atime, mtime) exist but always reject with "not implemented": they need the non-symlink-following lchown(2)/lutimes(2) (or utimensat(2) with AT_SYMLINK_NOFOLLOW) syscalls, and no native binding exposes those (only the fd-based fchown/futimes, which — via open() — follow a symlink instead of operating on it). See BUGS's fspromises-lchown-lutimes-unimplemented.

watch(filename, options)

Node-compatible fsPromises.watch(), wrapping fs.watch()'s FSWatcher as an async iterator instead of a callback:

import { watch } from 'fsPromises';

for await(const { eventType, filename } of watch('./some-dir')) {
  console.log(eventType, filename);
}

options.signal (an AbortSignal) ends the iteration when aborted, closing the underlying watcher.

Export list

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

Functions: 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()

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: 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