Lesson 34: Working with Files and Folders

34.1 Files and Folders from Code

This is what Node can do that nothing else in this book could: work directly with the files and folders on your computer. Node comes with a built-in module for it, fs, for file system, and another, path, for building file paths correctly on any operating system. Built-in modules are imported like packages, but need no installing. The node: in front of their names says they're part of Node:

import fs from "node:fs"
import path from "node:path"

// write a file, replacing it if it exists
fs.writeFileSync("notes.txt", "Bed 3 needs compost.\n")

// add to the end of a file
fs.appendFileSync("notes.txt", "Twine is running low.\n")

// read a whole file as text
const text = fs.readFileSync("notes.txt", "utf8")
console.log(text)

// list what's in a folder
console.log(fs.readdirSync("."))

// build a path from parts; Windows gets \ and Mac gets /
console.log(path.join("garden-photos", "2027-06", "tomatoes.jpg"))

Run it with Node in an empty project folder, and look at the folder afterward: notes.txt is there. A few things to notice:

• "utf8" tells readFileSync to give back text. Without it, you get the file's raw bytes.
• "." means "the current folder." All these relative names, notes.txt included, are relative to the terminal's current working directory, from Lesson 32. Installing Node and Running Scripts, not to the script's location. Run the script from a different folder, and it reads and writes there.
• writeFileSync replaces a file without asking. There's no "are you sure?" and no undo.

34.2 Sorting the Garden Photos

Volunteers have been sending photos all season, and they're all in one folder, garden-photos, hundreds of them. Maya would like them sorted into a folder for each month. Here's the request, in a new chat with your learner profile from Lesson 33. Modules and Packages:

Read. The assistant flagged fs as new and explained each function as it used it:

• readdirSync lists the file names, and filter keeps the ones ending in .jpg, after toLowerCase(), so .JPG counts too.
• statSync looks up a file's details. Its mtime property is the modified time, a Date object.
• The folder name is built from the date, with a leading zero for months below 10, as in Lesson 14. Email, Calendar, and Dates.
• mkdirSync creates the month folder, where { recursive: true } means "and don't complain if it's already there," and renameSync moves the file. Renaming a file to a path in a different folder is how you move it.

Two parts of the reply show good judgment. It raised the question of which date: a photo's modified time is easy to get, but it's the date the file last changed, which may not be when the photo was taken. Photos downloaded from a chat app or a cloud service often get the download date. The true "date taken" is stored inside the photo, in its EXIF data, and reading it needs a package. For the club, trying the built-in approach first, on a copy, is sensible: if every photo lands in the month you downloaded them, you'll know you need the package.

And it made a dry run, without being asked. Your profile's dry-run rule mentions only email, calendars and Google Drive, but the assistant applied its spirit to moving files. With DRY_RUN = true, the script only prints what it would do.

34.2.1 One more check before running it

What if the month folder already has a file with the same name? Phones name photos with counters, such as IMG_0412.jpg, so two volunteers' photos can easily share a name. renameSync onto an existing file replaces it, silently, on Windows and Mac alike. One volunteer's photo would be gone.

The fix is to check first, with existsSync, and skip any photo that would overwrite another. Here's the script with that check, in the book's style:

import fs from "node:fs"
import path from "node:path"

const PHOTO_FOLDER = "garden-photos"
// change to false to move the files for real, after checking the output
const DRY_RUN = true

const photos = fs.readdirSync(PHOTO_FOLDER)
  .filter(name => name.toLowerCase().endsWith(".jpg"))

for (const fileName of photos) {
  const sourcePath = path.join(PHOTO_FOLDER, fileName)
  // the modified time, which may differ from when the photo was taken
  const modified = fs.statSync(sourcePath).mtime
  const month = String(modified.getMonth() + 1).padStart(2, "0")
  const monthFolder = path.join(PHOTO_FOLDER, `${modified.getFullYear()}-${month}`)
  const destinationPath = path.join(monthFolder, fileName)

  if (fs.existsSync(destinationPath)) {
    console.log(`Skipped ${fileName}: a photo with that name is already in ${monthFolder}`)
  } else if (DRY_RUN) {
    console.log(`Would move ${fileName} to ${monthFolder}`)
  } else {
    fs.mkdirSync(monthFolder, { recursive: true })
    fs.renameSync(sourcePath, destinationPath)
    console.log(`Moved ${fileName} to ${monthFolder}`)
  }
}

padStart(2, "0") is a string method that adds zeros to the front until the string is 2 characters long: "6" becomes "06", and "11" stays "11". It replaces the if for the leading zero.

Before running it for real, make a copy of the whole garden-photos folder, and run it on the copy first.

34.3 Reading the Garden Journal

In Lesson 31. Scripting Your Notes in Obsidian, you learned that an Obsidian vault is just a folder of text files. That means Node can read it, even with Obsidian closed. Here's a request for a harvest calendar made from the journal, in a new chat:

Read. The overall plan is clear: list the notes, read each one, pull out two values from its front matter, sort, and write the lines to a file. It imports just the functions it needs, import { readdirSync, readFileSync, writeFileSync } from "fs", another form of import you'll see often. The front matter is found by splitting the note into lines and finding the two --- lines. Each line between them is split at the colon into a key and a value, stored in an object.

That split uses syntax you haven't met: const [key, ...rest] = line.split(":"). It's array destructuring, like the object destructuring in Lesson 33. Modules and Packages, but by position: key gets the first item of the array, and ...rest, the rest syntax, gets all the remaining items as a new array. Then rest.join(":") puts them back together, so a value that contains a colon, like note: water at 6:00, isn't cut short. The assistant explained why, but not the syntax. Try it:

const parts = "note: water at 6:00".split(":")
console.log(parts)

const [key, ...rest] = parts
console.log(key)
console.log(rest)
console.log(rest.join(":").trim())

// the same three dots in an array literal spread an array's items out
const moreParts = [...rest, "extra"]
console.log(moreParts)

In an array literal, the same ... does the reverse, called spread: it spreads an array's items into the new array.

Three other details:

• trim() removes spaces from both ends of a string, and it also quietly handles a difference between computers: files saved on Windows end each line with two invisible characters instead of one, and the extra one is removed by trim.
• slice(start, end) returns part of an array, from start up to but not including end.
• The script expects to run from the vault folder, since it reads "Plantings", a relative path. The instructions say so, which is the current working directory lesson again.

The assistant pointed out what happens with a note that lacks a field: undefined in the calendar, rather than an error. That's worth deciding about. For a calendar, skipping those notes and printing a warning is probably best. Also, the sort converts each date text to a Date object and subtracts. It works, but as you saw in Lesson 31. Scripting Your Notes in Obsidian, dates written as YYYY-MM-DD sort correctly as text with localeCompare, which avoids converting at all.

34.4 Working Safely with Files

Everything in this lesson changes your real files, immediately. A few habits keep that from going wrong:

• Dry runs first, for any script that moves, renames, overwrites or deletes.
• Work on a copy of important folders until the script has proved itself.
• Check before overwriting, with existsSync, as the photo script now does.
• Deleting is permanent. fs.rmSync and fs.unlinkSync delete files without using the Recycle Bin or Trash. There's no getting them back.
• Watch the paths. A script run from the wrong folder does its work in the wrong folder. Printing process.cwd(), the current working directory, at the start of a script is a quick check.

34.5 Your Learner Profile

The dry-run rule now covers files on your own computer, and asks the assistant to check before overwriting, the mistake the photo script almost made.

34.6 Summary

Node's built-in fs module reads and writes files, lists folders, looks up file details, and creates, moves and deletes, and path.join builds paths that work on any system. Relative paths are relative to the terminal's current working directory. File operations take effect immediately and without undo: writeFileSync and renameSync replace existing files silently, and deleting skips the Recycle Bin. So work with dry runs, copies and checks such as existsSync. Reading a folder of Markdown notes shows that any data stored as text files is open to your code. Along the way, you met array destructuring with ...rest, spread, and several string methods for taking text apart. Next, you'll work with data files: CSV, JSON and Excel.