In the previous lesson we used exactly two functions of fs: readFile and writeFile. With them Escena Viva already reads its catalog from disk, and that settled the debt we had been carrying since Module 1. But a single loose file is the simplest case in the file system.

Real applications work with directory trees: you need to know whether something exists and what it is, how much space it takes and when it was modified; to create folders that do not exist yet, list what is inside, delete the old stuff, move files around and, sometimes, read one specific chunk of a huge file without loading it whole. This lesson walks through that second half of fs and ends by building something Escena Viva already needs: a report store that organizes outputs by month, saves the day's occupancy report, lists what is there with its size and date, and automatically purges anything older than a certain age.

1. stat and the Stats object
2. stat versus lstat: symbolic links
3. Walking directories: readdir and withFileTypes
4. Creating and deleting trees: mkdir, rm, rename, copyFile
5. fs.constants, permissions and access
6. File descriptors and the FileHandle API
7. Watching for changes: watch versus watchFile
8. The Escena Viva report store

stat answers the question "what does the operating system know about this path?". It returns a Stats object with the file's metadata: not its content, but its record card.

Two classic confusions: ctime does not mean creation time, but the change time of the metadata — renaming or changing permissions updates it without touching the content — and size on a directory is not the weight of what it contains, but that of the directory entry itself. To know how much a folder takes you have to walk it and add up.

Like any fs operation, stat fails with ENOENT if the path does not exist. That makes it the usual — and correct — way of answering "does this exist and what is it?" in a single call: wrap it in a try/catch that returns null on ENOENT and propagates any other code, exactly as we did in the previous lesson with readIfExists.

A symbolic link is a file that points to another path. The difference between the two functions is what they do when they run into one:

The practical consequence matters: isSymbolicLink() always returns false with stat, because by then you have already jumped to the target; and if the link points to something deleted — a broken link — stat fails with ENOENT while lstat works and describes the link for you. Rule: use stat when you care about the content (the normal case) and lstat when you are walking or deleting a tree, so you do not follow links by accident and end up outside the directory you thought you were processing.

By default readdir returns names only, with no path and no hint about what each thing is. The natural impulse is to call stat on each one — for (const name of await fs.readdir(dir)) { const info = await fs.stat(${dir}/${name}); ... } — and with 5 entries it makes no difference; with 50,000 it means 50,000 extra system calls.

The withFileTypes option solves it: the operating system already knows the type of every entry while listing the directory, so Node hands it to you for free in the shape of Dirent objects.

A Dirent offers the same predicates as Stats (isFile, isDirectory, isSymbolicLink) but carries no size or mtime: if you need size or date, then you do need stat. The rule is to filter by type first with Dirent and call stat only on what you truly care about. readdir also accepts recursive: true to walk the whole tree in one go, and it guarantees no ordering: if you need the reports sorted by date, sort them yourself.

Three details that save debugging sessions. First: mkdir with recursive is idempotent, so calling it before writing is the clean way of guaranteeing the destination, with no prior checks and no race conditions. Second: rm without recursive on a directory fails with ERR_FS_EISDIR; and rm with force and recursive asks nothing at all, so an rm(computedPath, {recursive: true, force: true}) with a badly computed path deletes whatever you put in front of it — always validate the path first. Third: rename fails with EXDEV if source and target live on different disks or volumes; there you have to copy and delete.

fs.constants gathers the numeric values the operating system expects. The ones you use daily are these:

access returns nothing: it succeeds or it throws. And here it is worth remembering the previous lesson: using it as a step before an operation reintroduces the TOCTOU race condition. Its legitimate use is diagnostic, at startup, to give a clear message ("I cannot write into reports/") instead of a cryptic EACCES twenty minutes later.

Permissions are changed with chmod in octal notation: await fs.chmod(file, 0o600) leaves a file readable and writable only by its owner, which is what personal buyer data deserves (we will come back to it in Module 11). On Windows the permission model is different and chmod only affects the read-only bit.

readFile opens, reads whole and closes. When you need more control — reading only the first bytes, writing at a specific position, doing many operations on the same file without reopening it — you work with a file descriptor: an identifier the operating system hands you on opening, representing that particular open file.

In node:fs/promises, open() returns a FileHandle object wrapping that descriptor:

The try/finally is not optional. Every open descriptor occupies an entry in an operating system table with a per-process limit (usually a few thousand); if a function opens files and does not close them, every call leaks a descriptor and, after a few hours in production, the process starts failing with EMFILE: too many open files in operations that have nothing to do with it. And notice where the close goes: in the finally, not at the end of the try, because there any error from the read would take the close down with it. It is the same reasoning you will apply to database connections in Module 7.

sync() is the piece that completes the atomic write of the previous lesson: writing the temporary file, sync() and only then rename guarantees the content is physically on disk before the name change.

Reacting to changes in a file sounds trivial and it is not. Node offers two mechanisms of opposite character:

fs.watch has a well-deserved bad reputation: it can emit two events for a single save (many editors write a temporary file and rename it), the eventType field ('rename' or 'change') does not always mean what it seems, the file name arrives as null on some platforms, and on networks or mounted volumes sometimes nothing arrives at all.

The debounce pattern with setTimeout is not decoration: without it, a single save triggers two or three reloads. And notice the watcher.close(): a watcher keeps the process alive, so you have to close it for the program to be able to finish. In serious watching projects, the honest recommendation is to use a library such as chokidar, which exists precisely to smooth out all these differences.

Let's put it all together in a real module. src/reports/occupancy.js already knows how to compute summarizeByVenue since Module 2; what is missing is where to store those reports, how to list them and how to keep them from growing without limit.

Three design decisions deserve comment. The monthly partitioning (reports/2026-08/) avoids the classic problem of dumping a hundred thousand files into a single directory, where any readdir becomes slow, and it also turns the purge into an rm of a whole folder instead of a thousand separate deletions. The flag: 'wx' by default makes regenerating an already saved day's report an explicit error rather than a silent overwrite: if you really want it, you ask for it. And purgeReports runs a dry run by default, because a function that deletes recursively must demand that you confirm your intent, not the other way around. Notice as well that the paths are composed with template strings: it works on Linux and macOS, but it is exactly the mistake the next lesson will fix with path.join.

• Calling stat on every readdir entry. Use withFileTypes and save stat for when you actually need size or mtime.
• Reading ctime as the creation date. It is the date of the last metadata change. For creation, birthtime — and only if your system keeps it.
• mkdir without recursive fails with EEXIST if the folder already exists and with ENOENT if a parent is missing. With recursive: true both problems disappear.
• Leaving descriptors open. Every open() needs its close() in a finally. The late symptom is EMFILE somewhere unrelated to the failure.
• copyFile overwrites by default (pass fs.constants.COPYFILE_EXCL if you do not want that), and readdir guarantees no ordering: sort explicitly.
• Tip: any function that deletes should have a dry-run mode and use it by default; rm with recursive and force asks nobody for confirmation. And if fs.watch fires duplicate callbacks at you, do not go looking for the bug in your code: that is normal behavior, apply debouncing.

Write src/lab/measure-folder.js that takes a path from process.argv and walks the tree recursively, computing: total number of files, number of directories, total size in bytes and the five largest files. It must use readdir with withFileTypes, not follow symbolic links (lstat) and print the result with console.table on stdout.

Write src/reports/generate.js that uses getCatalog() and summarizeByVenue() to build the day's report, saves it with saveReport(), prints the full listing with listReports() and runs purgeReports(6) in dry-run mode, stating what would be deleted. It accepts --overwrite and --purge to move from simulation to action.

Write a function rotateLog(file, maxSizeBytes) that, if the file exceeds the given size, renames it to file.YYYY-MM-DDTHH-mm-ss and leaves the original empty, keeping at most the five most recent rotations and deleting the rest. It must work even if the file does not exist yet.

Solution 1. The recursive walk with withFileTypes is the pattern you will see again and again:

When it finishes, largest.sort((a, b) => b.bytes - a.bytes).slice(0, 5) gives the five biggest. Skipping symbolic links is not theoretical fussiness: a link pointing to an ancestor turns the walk into an infinite loop.

Solution 2. What matters is the order of the operations and that the write coexists with the EEXIST:

Solution 3. Rotation combines stat, rename and a purge in reverse order:

Two details: the : and . of the ISO stamp are replaced because they are not valid in file names on Windows, and sorting the rotations alphabetically is the same as sorting them by date because the ISO format is designed for that. Slicing the path with lastIndexOf('/') is exactly what path.dirname and path.basename will do properly — and portably — in the next lesson.

You now know the part of fs that goes beyond reading and writing one file. You can query metadata with stat and read a Stats object without confusing ctime with the creation date; you tell stat from lstat and understand why isSymbolicLink() only makes sense with the latter; you walk directories with readdir and withFileTypes, avoiding the per-entry stat that multiplies system calls; you create and destroy trees with mkdir({recursive}) — idempotent, and therefore the clean way to guarantee a destination — and with rm({recursive, force}), which asks nobody anything; you move with rename knowing it fails with EXDEV across volumes; and you copy with copyFile remembering it overwrites unless COPYFILE_EXCL.

You have also seen file descriptors and the FileHandle API, with the rule that admits no exceptions: every open() carries its close() in a finally, or sooner or later the EMFILE arrives. And you know the two watchers, watch and watchFile, with their opposite characters and the need for debouncing. Escena Viva, for its part, has gained src/reports/report-store.js with saveReport, listReports and purgeReports: reports are organized by month, they are not overwritten by accident thanks to flag: 'wx', they are listed with their size and date, and they are purged in dry-run mode unless you confirm otherwise.

One loose end remains, and it is a big one: every path in this module is built by gluing strings with /. It works on your machine and breaks the moment somebody runs the project from another directory or on Windows. In Cross-Platform Paths with the path Module we will see why concatenating paths is a mistake, the exact difference between join and resolve, the gulf between process.cwd() and __dirname, how a ../../etc/passwd sneaks into a path built from user data, and we will centralize the project's whole path configuration in src/config/paths.js to refactor what we wrote in these two lessons.