Node.js Reference ยท fs and fs/promises
The fs.Stats class
Reference for fs.Stats in Node.js: size, mode and permission bits, atime/mtime/ctime/birthtime, type-check methods, BigIntStats and what each field means.
An fs.Stats object describes one file system entry. You never create it yourself; it is what fs.stat(), fs.lstat(), fs.fstat() and filehandle.stat() hand back. It carries numbers (size, owner, permissions), four timestamps and seven methods that tell you what kind of entry it is.
With the { bigint: true } option you get a BigIntStats object instead. It has the same fields as bigint values, plus extra nanosecond-precision time fields.
import fs from "node:fs"; const s = fs.statSync("package.json"); console.log(s.size, s.mtime, s.isFile());
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
class Stats { dev, ino, mode, nlink, uid, gid, rdev, size, blksize, blocks // numbers atimeMs, mtimeMs, ctimeMs, birthtimeMs // numbers (milliseconds) atime, mtime, ctime, birthtime // Date objects isFile(): boolean isDirectory(): boolean isSymbolicLink(): boolean // only meaningful from lstat() isBlockDevice(): boolean isCharacterDevice(): boolean isFIFO(): boolean isSocket(): boolean } // BigIntStats: numeric fields are bigint; adds atimeNs, mtimeNs, ctimeNs, birthtimeNs
| Field | Meaning |
|---|---|
size |
Size in bytes (for symlinks, the length of the target path). |
mode |
File type bits plus permission bits. Use mode & 0o777 for permissions. |
uid, gid |
Numeric owner and group (0 on Windows). |
nlink |
Number of hard links. |
ino, dev |
Inode number and device; together they identify a file uniquely. |
blksize, blocks |
Preferred I/O block size and 512-byte blocks allocated. |
atime |
Last access. |
mtime |
Last content change. |
ctime |
Last status change (permissions, owner, rename, content). Not "creation". |
birthtime |
Creation time, where the system records it. |
Usage notes
ctimeis not creation time. Usebirthtimefor that, but treat it with care: some Linux file systems and Node builds report0or copyctime.mtimechanges when contents change;ctimechanges for that and also forchmod,chownand renames. You cannot setctimeyourself.- Compare identity with
devandino, not paths, to find out whether two paths are the same file (hard links share both). Usebigint: truewhen inode numbers are huge. - Symlinks:
isSymbolicLink()is alwaysfalsefor results ofstat(), because it follows the link. Uselstat(). - Timestamp precision depends on the file system; some round to seconds.
Msfields may contain fractions. - The
Datefields are computed lazily, so readingmtimeMsis cheaper in hot loops. - Type bits:
mode & fs.constants.S_IFMTcan be compared withS_IFREG,S_IFDIRand the other constants. Theis*methods wrap that. - Do not construct it:
new fs.Stats()is deprecated.