Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import fs from "node:fs";

const s = fs.statSync("package.json");
console.log(s.size, s.mtime, s.isFile());

Try it

Node.js Fields and type checks

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.

Node.js Times, comparisons and BigIntStats

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

NODE
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

  • ctime is not creation time. Use birthtime for that, but treat it with care: some Linux file systems and Node builds report 0 or copy ctime.
  • mtime changes when contents change; ctime changes for that and also for chmod, chown and renames. You cannot set ctime yourself.
  • Compare identity with dev and ino, not paths, to find out whether two paths are the same file (hard links share both). Use bigint: true when inode numbers are huge.
  • Symlinks: isSymbolicLink() is always false for results of stat(), because it follows the link. Use lstat().
  • Timestamp precision depends on the file system; some round to seconds. Ms fields may contain fractions.
  • The Date fields are computed lazily, so reading mtimeMs is cheaper in hot loops.
  • Type bits: mode & fs.constants.S_IFMT can be compared with S_IFREG, S_IFDIR and the other constants. The is* methods wrap that.
  • Do not construct it: new fs.Stats() is deprecated.