Reading files

As discussed in the previous series parts, NodeJS provides a powerful built-in module called `fs` (short for file system) for interacting with the file system. This module allows us to perform various file-related operations, including reading from and writing to files.

The main focus of this part is to explore the basics of reading from and writing to files in nodeJS.

Quick Overview:

• ➢Asynchronous I/O: Node is designed around asynchronous I/O operations, which means that file operations such as reading and writing are non-blocking.
  This allows Node.js to handle multiple file operations concurrently without waiting for each operation to complete before moving on to the next one.
  
• ➢Event-Driven Architecture: Node uses an event-driven architecture, where file I/O operations trigger events that can be handled asynchronously.
  This allows for efficient and scalable handling of file operations, especially in scenarios with high concurrency and large numbers of file requests.
• ➢Buffers and Streams: Node uses buffers and streams to efficiently read and write data from and to files.
  Buffers are temporary storage areas used to hold data during file operations, while streams provide a continuous flow of data between a source and a destination, allowing for efficient handling of large files.
  

Reading Files:

Reading files is a common task in Node.js applications, whether it's loading configuration files, parsing data from external sources, or serving content to clients.
Node.js offers several methods for reading files, each with its own strengths and use cases.

Methods for reading files and their usecases.

There are many ways to read files in node, but here we'll discuss only a basic and most widely used ones.

1. readFile(): readFile(path[, options], callback)

Reads the contents of a file asynchronously, providing the file contents in a callback function.

Use Cases: Ideal for reading small to medium-sized files where asynchronous operation is preferred, such as loading configuration files or processing user input.

// index.js
const fs = require('fs');

const file = './file.txt'; // place the target file in the same directory for simplicity

fs.readFile(file, 'utf8', (err, data) => {
  if (err) {
    console.error('Error reading file:', err);
    return;
  }
  console.log('File Contents (fs.readFile()):', data);
});

- path: the path to the target file file.txt

- Options:

• ➢encoding: Specifies the encoding of the file contents (default is `utf8`).
• ➢flag: Specifies the file system flag used when opening the file (default is `r`).

If you're interested in reading about the various file system flags, then have a look at the official doc.

2. readFileSync(): readFileSync(path[, options])

Synchronously reads the contents of a file, blocking the event loop until file contents are read.

Use Cases: Suitable for reading small files where synchronous operation is acceptable, such as during initialization or setup tasks.

// index.js
const fs = require('fs');


const file = './file.txt'; // place the target file in the same directory for simplicity
try {
    const fileContent = fs.readFileSync(file, 'utf8');
    console.log('File Contents (fs.readFileSync()):', fileContent);
} catch (err) {
    console.error('Error reading file synchronously:', err);
}

3. promises.readFile():

As with most async APIs in node, since v10, we have promiss.readFile method too.

It Returns a promise that resolves with the file contents, allowing cleaner asynchronous syntax with async/await.

Use Cases: Preferred for modern Node.js applications where promise-based syntax is preferred, enabling better error handling and code readability.

// index.js 

const fs = require('fs');

const file = './file.txt'; // place the target file in the same directory for simplicity
fs.promises.readFile(file, 'utf8')
.then(data => {
console.log('File Contents (fs.promises.readFile()):', data);
})
.catch(err => {
console.error('Error reading file with promises:', err);
});

4. createReadStream(): createReadStream([options])

This method creates a readable stream for reading large files incrementally, emitting data events as chunks are read.

Use Cases: Ideal for handling large files efficiently, such as log files or media files, where reading the entire file into memory at once is not practical.

// index.js

const fs = require('fs');

const file = './file.txt'; // place the target file in the same directory for simplicity
const readStream = fs.createReadStream(file, { encoding: 'utf8' });
readStream.on('data', chunk => {
  console.log('Chunk Read (fs.createReadStream()):', chunk);
});
readStream.on('error', err => {
  console.error('Error reading file with stream:', err);
});

Writing files

Writing Files

Writing files is essential for generating reports, storing user-generated content, and persisting data to disk.

Node provides various methods for writing data to files, each with its own advantages and considerations.

Let's start with the simpliest way to write to a file.

1.writeFile(): writeFile(data, options)

This method is used to writes data to a file asynchronously, overwriting existing content if the file already exists.

Use Cases: Suitable for writing small to medium-sized files where asynchronous operation is preferred, such as saving user preferences or logging application events.

// index.js

const fs = require('fs');

const file = './file.txt'; // place the target file in the same directory for simplicity
const contentToWrite = 'This is a sample text out to be written to file.txt!';

fs.writeFile(file, contentToWrite, 'utf8', err => {
  if (err) {
    console.error('Error writing file:', err);
    return;
  }
  console.log('File written successfully (fs.writeFile())');
});

- Options: Here are some options to use

• ➢encoding: Specifies the encoding of the data to be written (default is `utf8`).
• ➢mode: Specifies the file mode (permissions) of the file (default is 0o666).
• ➢flag: Specifies the file system flag used when opening the file (default is `'w'`). Again you may find the complete list here.

Run the above code and check the newly created file.txt. Then update contentToWrite and run the code again. This confirms that, the write operation, overwrite the existing files content.

2. writeFileSync(): writeFileSync(file, data[, options])

This method synchronously writes data to a file, and just like it's readFileSync counterpart, it blocks the event loop until data is written to the file.

Use Cases: Suitable for writing small files where synchronous operation is acceptable, such as during initialization or setup tasks.

// index.js

const fs = require('fs');

const file = './play.txt'; // place the target file in the same directory for simplicity
const contentToWriteSync = 'This is a sample text out to be written to file.txt synchronously!';

try {
    fs.writeFileSync(file, contentToWriteSync, 'utf8');
    console.log('File written successfully synchronously (fs.writeFileSync())');
} catch (err) {
console.error('Error writing file synchronously:', err);
}

NB: You can also use the promise-based fsPromises.writeFile() method offered by the fs/promises module:

// index.js



const file = './play.txt'; // place the target file in the same directory for simplicity
const contentToWrite = 'This is a sample text out to be written to file.txt asynchronously with promise pattern!';

fs.promises.writeFile(file, contentToWrite, 'utf8') 
.then(() => {
    console.log('File written successfully (fs.promises.writeFile())');
})
.catch(err => {
    console.error('Error writing file:', err);
    return;
});

NB: For all write operations, using the either of these flags (`w+`, `a`, `a+`) will create a new file, if it doesn't already exist. However, using `r+` will throw an exception if the file doesn't exists.

3. createWriteStream(): createWriteStream(path[, options])

This method creates a writable stream for writing data to a file incrementally, allowing for efficient handling of large files.

Use Cases: Ideal for writing large files efficiently, such as log files or media files, where writing the entire file at once is not practical.

// index.js

const fs = require('fs');

const file = './file.txt'; // place the target file in the same directory for simplicity
const dataToWrite = 'Data writen to file.txt using stream\n'

const writeStream = fs.createWriteStream(file, { encoding: 'utf8' });
writeStream.on('finish', () => {
    console.log('Writing to file.txt completed!')
})
writeStream.write(dataToWrite);
writeStream.end();

Appending content to a file

Sometimes, we really don't want to overwrite the existing content, but rather add to it. Let's see what should be done in such cases.

appendFile(): appendFile(path, data[, options], callback)

This method appends data to a file asynchronously, creating the file if it doesn't exist.

Use Cases: Ideal for scenarios where data needs to be appended to an existing file, such as logging application events or writing to a shared log file.

// index.js

const fs = require('fs');


const file = './file.txt'; // place the target file in the same directory for simplicity

const contentToAppend = '\nAppending some extra content to what we already have in file.txt!';
fs.appendFile(file, contentToAppend, 'utf8', err => {
  if (err) {
    console.error('Error appending to file:', err);
    return;
  }
  console.log('Data appended successfully (fs.appendFile())');
});

We also have a synchrounous version for the above which synchronously appends data to a file, blocking the event loop until data is appended to the file.

// index.js

const fs = require('fs');


const file = './file.txt'; // place the target file in the same directory for simplicity

const contentToAppendSync = '\nAppending some extra content to what we already have in file.txt synchronously!';
try {
    fs.appendFileSync(file, contentToAppendSync, 'utf8');
    console.log('Data appended successfully synchronously (fs.appendFileSync())');
} catch (err) {
    console.error('Error appending to file synchronously:', err);
}

Conclusion

we've covered the basics of reading and writing files in NodeJS. Understanding how file I/O works in Node and the various methods available for reading from and writing to files is essential for building robust and efficient applications.

In the next part, we'll conclude this chapter with working with directories in node.