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