The filesystem

Reading and writing files on the filesystem (the hard drive) is a common asynchronous operation. Node.js provides both synchronous and asynchronous functions to read and write files. You can see this in the documentation for readFile (the async version) and readFileSync (the synchronous version). As you can see from the documentation for the fs module, it provides a lot of functionality.

Filesystem access is part of a broader type of operations called IO, which stands for Input/Output. IO also includes accessing databases and communicating on a network. We're spending most of our time using the HTTP protocol when communicating over networks, but IO includes all protocols and data formats, and databases. All IO operations should be performed asynchronously because they often take much longer than performing the in-memory tasks most of our application is written to do.

Most of our web development work will not include operating on files. Most of it will involve databases and network communication. However, filesystem operations provide a great precursor into the asynchronous programming practices we'll apply with databases and networking, without having to understand the surrounding technology. The added benefit is understanding how to work with files, which is very handy when programming local scripts.

Reading a text file

To read a text file, we need the path to the file we want to read. In the example below, we're using the path.join function to create the path to the students.json file.

// Include modules provided by Node.js
const fs = require('node:fs')
const path = require('node:path')

function readAsync () {
  const studentsFile = path.join(__dirname, 'students.json')
  fs.readFile(studentsFile, 'utf-8')
    .then((contents) => {
      console.log(contents)
    })
    .catch((err) => {
      console.log(err.message)
    })
}

The contents of the file, contents, will be passed into our then block if the file was successfully read. If an error occurred we will instead log the error message.

Writing a text file

To write a text file, we need the path we want to create and the contents we want for the file.

// Include modules provided by Node.js
const fs = require('node:fs')
const path = require('node:path')

function writeAsync () {
  const teacherFile = path.join(__dirname, 'teacher.json')
  const teacherJson = JSON.stringify({ name: 'Don' })

  fs.writeFile(teacherFile, teacherJson)
    .then(() => console.log('File has been written to'))
    .catch((err) => console.log('Oh no!', err.message))
}

The writeFile function will accepts a string, which is returned from JSON.stringify.