The node:fs
module enables interacting with the file system in a
way modeled on standard POSIX functions.
To use the promise-based APIs:
import * as fs from 'node:fs/promises';
To use the callback and sync APIs:
import * as fs from 'node:fs';
All file system operations have synchronous, callback, and promise-based forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM).
The `node:fs` module enables interacting with the file system in a way modeled on standard POSIX functions. To use the promise-based APIs: ```js import * as fs from 'node:fs/promises'; ``` To use the callback and sync APIs: ```js import * as fs from 'node:fs'; ``` All file system operations have synchronous, callback, and promise-based forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM).
A class representing a directory stream.
Created by {@link opendir }, {@link opendirSync }, or fsPromises.opendir()
.
import { opendir } from 'node:fs/promises';
try {
const dir = await opendir('./');
for await (const dirent of dir)
console.log(dirent.name);
} catch (err) {
console.error(err);
}
When using the async iterator, the fs.Dir
object will be automatically
closed after the iterator exits.
A class representing a directory stream. Created by {@link opendir }, {@link opendirSync }, or `fsPromises.opendir()`. ```js import { opendir } from 'node:fs/promises'; try { const dir = await opendir('./'); for await (const dirent of dir) console.log(dirent.name); } catch (err) { console.error(err); } ``` When using the async iterator, the `fs.Dir` object will be automatically closed after the iterator exits.
A representation of a directory entry, which can be a file or a subdirectory
within the directory, as returned by reading from an fs.Dir
. The
directory entry is a combination of the file name and file type pairs.
Additionally, when {@link readdir } or {@link readdirSync } is called with
the withFileTypes
option set to true
, the resulting array is filled with fs.Dirent
objects, rather than strings or Buffer
s.
A representation of a directory entry, which can be a file or a subdirectory within the directory, as returned by reading from an `fs.Dir`. The directory entry is a combination of the file name and file type pairs. Additionally, when {@link readdir } or {@link readdirSync } is called with the `withFileTypes` option set to `true`, the resulting array is filled with `fs.Dirent` objects, rather than strings or `Buffer` s.
Synchronous lstat(2) - Get file status. Does not dereference symbolic links.
Synchronous lstat(2) - Get file status. Does not dereference symbolic links.
Instances of fs.ReadStream
are created and returned using the {@link createReadStream } function.
Instances of `fs.ReadStream` are created and returned using the {@link createReadStream } function.
Asynchronously computes the canonical pathname by resolving .
, ..
, and
symbolic links.
A canonical pathname is not necessarily unique. Hard links and bind mounts can expose a file system entity through many pathnames.
This function behaves like realpath(3)
, with some exceptions:
realpath(3)
implementation supports.The callback
gets two arguments (err, resolvedPath)
. May use process.cwd
to resolve relative paths.
Only paths that can be converted to UTF8 strings are supported.
The optional options
argument can be a string specifying an encoding, or an
object with an encoding
property specifying the character encoding to use for
the path passed to the callback. If the encoding
is set to 'buffer'
,
the path returned will be passed as a Buffer
object.
If path
resolves to a socket or a pipe, the function will return a system
dependent name for that object.
Asynchronous realpath(3) - return the canonicalized absolute pathname.
Asynchronously computes the canonical pathname by resolving `.`, `..`, and symbolic links. A canonical pathname is not necessarily unique. Hard links and bind mounts can expose a file system entity through many pathnames. This function behaves like [`realpath(3)`](http://man7.org/linux/man-pages/man3/realpath.3.html), with some exceptions: 1. No case conversion is performed on case-insensitive file systems. 2. The maximum number of symbolic links is platform-independent and generally (much) higher than what the native [`realpath(3)`](http://man7.org/linux/man-pages/man3/realpath.3.html) implementation supports. The `callback` gets two arguments `(err, resolvedPath)`. May use `process.cwd` to resolve relative paths. Only paths that can be converted to UTF8 strings are supported. The optional `options` argument can be a string specifying an encoding, or an object with an `encoding` property specifying the character encoding to use for the path passed to the callback. If the `encoding` is set to `'buffer'`, the path returned will be passed as a `Buffer` object. If `path` resolves to a socket or a pipe, the function will return a system dependent name for that object. Asynchronous realpath(3) - return the canonicalized absolute pathname.
Returns the resolved pathname.
For detailed information, see the documentation of the asynchronous version of this API: {@link realpath }. Synchronous realpath(3) - return the canonicalized absolute pathname.
Returns the resolved pathname. For detailed information, see the documentation of the asynchronous version of this API: {@link realpath }. Synchronous realpath(3) - return the canonicalized absolute pathname.
Synchronous stat(2) - Get file status.
Synchronous stat(2) - Get file status.
Class: fs.StatWatcher
Class: fs.StatWatcher
A fs.Stats
object provides information about a file.
Objects returned from {@link stat }, {@link lstat }, {@link fstat }, and
their synchronous counterparts are of this type.
If bigint
in the options
passed to those methods is true, the numeric values
will be bigint
instead of number
, and the object will contain additional
nanosecond-precision properties suffixed with Ns
.
Stats {
dev: 2114,
ino: 48064969,
mode: 33188,
nlink: 1,
uid: 85,
gid: 100,
rdev: 0,
size: 527,
blksize: 4096,
blocks: 8,
atimeMs: 1318289051000.1,
mtimeMs: 1318289051000.1,
ctimeMs: 1318289051000.1,
birthtimeMs: 1318289051000.1,
atime: Mon, 10 Oct 2011 23:24:11 GMT,
mtime: Mon, 10 Oct 2011 23:24:11 GMT,
ctime: Mon, 10 Oct 2011 23:24:11 GMT,
birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
bigint
version:
BigIntStats {
dev: 2114n,
ino: 48064969n,
mode: 33188n,
nlink: 1n,
uid: 85n,
gid: 100n,
rdev: 0n,
size: 527n,
blksize: 4096n,
blocks: 8n,
atimeMs: 1318289051000n,
mtimeMs: 1318289051000n,
ctimeMs: 1318289051000n,
birthtimeMs: 1318289051000n,
atimeNs: 1318289051000000000n,
mtimeNs: 1318289051000000000n,
ctimeNs: 1318289051000000000n,
birthtimeNs: 1318289051000000000n,
atime: Mon, 10 Oct 2011 23:24:11 GMT,
mtime: Mon, 10 Oct 2011 23:24:11 GMT,
ctime: Mon, 10 Oct 2011 23:24:11 GMT,
birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
A `fs.Stats` object provides information about a file. Objects returned from {@link stat }, {@link lstat }, {@link fstat }, and their synchronous counterparts are of this type. If `bigint` in the `options` passed to those methods is true, the numeric values will be `bigint` instead of `number`, and the object will contain additional nanosecond-precision properties suffixed with `Ns`. ```console Stats { dev: 2114, ino: 48064969, mode: 33188, nlink: 1, uid: 85, gid: 100, rdev: 0, size: 527, blksize: 4096, blocks: 8, atimeMs: 1318289051000.1, mtimeMs: 1318289051000.1, ctimeMs: 1318289051000.1, birthtimeMs: 1318289051000.1, atime: Mon, 10 Oct 2011 23:24:11 GMT, mtime: Mon, 10 Oct 2011 23:24:11 GMT, ctime: Mon, 10 Oct 2011 23:24:11 GMT, birthtime: Mon, 10 Oct 2011 23:24:11 GMT } ``` `bigint` version: ```console BigIntStats { dev: 2114n, ino: 48064969n, mode: 33188n, nlink: 1n, uid: 85n, gid: 100n, rdev: 0n, size: 527n, blksize: 4096n, blocks: 8n, atimeMs: 1318289051000n, mtimeMs: 1318289051000n, ctimeMs: 1318289051000n, birthtimeMs: 1318289051000n, atimeNs: 1318289051000000000n, mtimeNs: 1318289051000000000n, ctimeNs: 1318289051000000000n, birthtimeNs: 1318289051000000000n, atime: Mon, 10 Oct 2011 23:24:11 GMT, mtime: Mon, 10 Oct 2011 23:24:11 GMT, ctime: Mon, 10 Oct 2011 23:24:11 GMT, birthtime: Mon, 10 Oct 2011 23:24:11 GMT } ```
Provides information about a mounted file system.
Objects returned from {@link statfs } and its synchronous counterpart are of
this type. If bigint
in the options
passed to those methods is true
, the
numeric values will be bigint
instead of number
.
StatFs {
type: 1397114950,
bsize: 4096,
blocks: 121938943,
bfree: 61058895,
bavail: 61058895,
files: 999,
ffree: 1000000
}
bigint
version:
StatFs {
type: 1397114950n,
bsize: 4096n,
blocks: 121938943n,
bfree: 61058895n,
bavail: 61058895n,
files: 999n,
ffree: 1000000n
}
Provides information about a mounted file system. Objects returned from {@link statfs } and its synchronous counterpart are of this type. If `bigint` in the `options` passed to those methods is `true`, the numeric values will be `bigint` instead of `number`. ```console StatFs { type: 1397114950, bsize: 4096, blocks: 121938943, bfree: 61058895, bavail: 61058895, files: 999, ffree: 1000000 } ``` `bigint` version: ```console StatFs { type: 1397114950n, bsize: 4096n, blocks: 121938943n, bfree: 61058895n, bavail: 61058895n, files: 999n, ffree: 1000000n } ```
Watch for changes on filename
. The callback listener
will be called each
time the file is accessed.
The options
argument may be omitted. If provided, it should be an object. The options
object may contain a boolean named persistent
that indicates
whether the process should continue to run as long as files are being watched.
The options
object may specify an interval
property indicating how often the
target should be polled in milliseconds.
The listener
gets two arguments the current stat object and the previous
stat object:
import { watchFile } from 'fs';
watchFile('message.text', (curr, prev) => {
console.log(`the current mtime is: ${curr.mtime}`);
console.log(`the previous mtime was: ${prev.mtime}`);
});
These stat objects are instances of fs.Stat
. If the bigint
option is true
,
the numeric values in these objects are specified as BigInt
s.
To be notified when the file was modified, not just accessed, it is necessary
to compare curr.mtimeMs
and prev.mtimeMs
.
When an fs.watchFile
operation results in an ENOENT
error, it
will invoke the listener once, with all the fields zeroed (or, for dates, the
Unix Epoch). If the file is created later on, the listener will be called
again, with the latest stat objects. This is a change in functionality since
v0.10.
Using {@link watch } is more efficient than fs.watchFile
and fs.unwatchFile
. fs.watch
should be used instead of fs.watchFile
and fs.unwatchFile
when possible.
When a file being watched by fs.watchFile()
disappears and reappears,
then the contents of previous
in the second callback event (the file's
reappearance) will be the same as the contents of previous
in the first
callback event (its disappearance).
This happens when:
Watch for changes on `filename`. The callback `listener` will be called each time the file is accessed. The `options` argument may be omitted. If provided, it should be an object. The `options` object may contain a boolean named `persistent` that indicates whether the process should continue to run as long as files are being watched. The `options` object may specify an `interval` property indicating how often the target should be polled in milliseconds. The `listener` gets two arguments the current stat object and the previous stat object: ```js import { watchFile } from 'fs'; watchFile('message.text', (curr, prev) => { console.log(`the current mtime is: ${curr.mtime}`); console.log(`the previous mtime was: ${prev.mtime}`); }); ``` These stat objects are instances of `fs.Stat`. If the `bigint` option is `true`, the numeric values in these objects are specified as `BigInt`s. To be notified when the file was modified, not just accessed, it is necessary to compare `curr.mtimeMs` and `prev.mtimeMs`. When an `fs.watchFile` operation results in an `ENOENT` error, it will invoke the listener once, with all the fields zeroed (or, for dates, the Unix Epoch). If the file is created later on, the listener will be called again, with the latest stat objects. This is a change in functionality since v0.10. Using {@link watch } is more efficient than `fs.watchFile` and `fs.unwatchFile`. `fs.watch` should be used instead of `fs.watchFile` and `fs.unwatchFile` when possible. When a file being watched by `fs.watchFile()` disappears and reappears, then the contents of `previous` in the second callback event (the file's reappearance) will be the same as the contents of `previous` in the first callback event (its disappearance). This happens when: * the file is deleted, followed by a restore * the file is renamed and then renamed a second time back to its original name
stream.Writable
Instances of fs.WriteStream
are created and returned using the {@link createWriteStream } function.
* Extends `stream.Writable` Instances of `fs.WriteStream` are created and returned using the {@link createWriteStream } function.
A parsed path object generated by path.parse() or consumed by path.format().
A parsed path object generated by path.parse() or consumed by path.format().
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close