Ever since NodeJS' inception, we've been able to execute JavaScript code outside of the browser. But NodeJS did a lot more than just that, it opened up a way to write server side code with JavaScript itself and along with it came the ability to manipulate host system's file system.
Photo by Maksym Kaharlytskyi on Unsplash
NodeJs introduced the fs module that allows you to do synchronous or asynchronous I/O operations and it's available out of the box.
Getting Started
Make sure you've the node installed in your system, if not you can head over to Node's official site and download it from there. Now with that installed we're up and ready to do some file based operations.
To use the fs, we can use the code below. If you're using commonjs use this line of code.
const fs = require('fs')
If you're using ES, you can import it like this.
import fs from 'fs'
Now each of the operations we'll be learning have both synchronous and asynchronous methods. All the synchronous methods have Sync as a suffix. All the asynchronous methods takes a callback as it's last argument which gives us an error as first argument and data as second argument containing the result that some of the operation's return. With that being said and done, let's do some operations.
CRUD operations
Using the fs module, we can implement following operations -
- Create
- Read
- Update
- Rename
- Delete
Create File
In order to create a new file, we can use fs.writeFile or fs.writeFileSync.
Synchronous Method
This method takes three arguments:
- file - path of the file, where it would be stored
- data - content to store inside the file, can be
stringorbuffer. - options - an object containing key-values for configuration for ex.
encoding
The return value for this method is undefined.
fs.writeFileSync('./example.txt', 'exampel content')
By default the encoding for data of string type would be utf8 and if different encoding is required, pass it using the third argument named options.
Asynchronous Method
This method takes all the arguments same as the synchronous method except it let's you pass a callback.
fs.writeFile('./example.txt', 'exampel content', (error) => {
if(error) console.log(error);
console.log('The file has been saved!')
})
Read File
Now if we want to read the content of the file example.txt that we just created. We can use either fs.readFile or fs.readFileSync.
Synchronous Method
This method takes just one argument i.e path of the file where it's stored and returns the contents stored in that file. The content could be either of type string or buffer. With buffer type, simply convert it to string using toString() method.
const data = fs.readFileSync('./example.txt')
// data - "exampel content"
Asynchronous Method
fs.readFile('./example.txt', (error, data) => {
if(error) console.log(error);
console.log(data)
})
// data - "exampel content"
Update File
Now that we have access to the content of the file and we want to update it because there's a typo you made or maybe I did which is perfectly normal, you can use the method's fs.writeFile or fs.writeFileSync again to overwrite your data.
Synchronous Method
This method just returns undefined, because incase you're file doesn't exist it'll create a new one using the path itself and store the content in that file.
fs.writeFileSync('./example.txt', 'example content')
Asynchronous Method
fs.writeFile('./example.txt', 'example content', (error) => {
if(error) console.log(error);
console.log('The file has been updated!')
})
Rename File
This method can be used for two purposes i.e for renaming a file/folder or moving a file/folder from one folder to another. The most likely error that it will throw is if the new name that was provided is a folder but incase if it's a file it will be overwritten. It will also throw an error if the folder you're moving the file to does not exist.
Synchronous Method
This method just takes two arguements: oldPath and newPath. Return undefined if the operation was successfull. Throws error if newPath doesn't exist or newPath is a folder.
fs.renameSync('./example.txt', './example1.txt')
Asynchronous Method
This method has similar signature as the synchronous one with an extra callback, giving us an error object that can be logged.
fs.rename('./example.txt', './example1.txt', (error) => {
if(error) console.log(error);
console.log('The file has been renamed!')
})
Delete File
The methods we have for deleting a file are fs.unlink and fs.unlinkSync. The most likely error it could throw is if the file you're trying to delete doesn't exist.
Synchronous Method
This version just takes a path of type string or buffer or a URL. Returns undefined if there are no errors.
fs.unlinkSync('./example1.txt')
Asynchronous Method
This version takes a path and callback as arguments. Callback gets just the error argument that can be used to log the error.
fs.unlink('./example1.txt', (error) => {
if(error) console.log(error);
console.log('The file has been deleted!')
})
Validation
These methods can get the job done but they're not enough because any error thrown in production, if not catched will stop the server. For ex. when you update a file, you would not want to update a wrong file because you passed tire instead of tier considering they both exist for some reason. So what do we do, we bring in validation. Simple checks before performing any operations to validate if a file exists or not.
There's a method that fs module provides for checking if a file/folder exists or not, named existsSync. The asynchronous method for this has been deprecated.
const fileExists = fs.existsSync('./example1.txt')
// fileExists - false
Now we can write our validation for file based operations.
Create File
Let's start by creating a function named create and we'll pass both the filePath and content to it. We'll use try catch to catch all the errors that could possibly be thrown.
const create = (filePath, content) => {
try {
const fileExists = fs.existsSync(filePath);
if (fileExists) {
throw {
success: false,
message: "The file already exist!"
};
} else {
fs.writeFileSync(filePath, content);
return {
success: true,
message: "The file has been created!"
};
}
} catch (error) {
return error;
}
};
create("./example.txt", "Example Content")
Read File
Similarly for reading a file, we can write function called read and pass our filePath to it. Before returning the content
const read = filePath => {
try {
const fileExists = fs.existsSync(filePath);
if (fileExists) {
const content = fs.readFileSync(filePath, 'utf8');
return {
success: true,
data: content
};
} else {
throw {
success: false,
message: "The file doesn't exist!"
};
}
} catch (error) {
return error;
}
};
const content = read("./example.txt")
Update File
Before updating a file, we'll check if it exists or not and throw an error if it does not.
const update = (filePath, content) => {
try {
const fileExists = fs.existsSync(filePath);
if (fileExists) {
fs.writeFileSync(filePath, content);
return {
success: true,
message: "The file has been updated!"
};
} else {
throw {
success: false,
message: "The file doesn't exist!"
};
}
} catch (error) {
return error;
}
};
update('./example.txt', "New Example Content")
Rename File
With renaming a file, we'll have to make sure that both the path's i.e oldPath and newPath exists. In case you're trying to move a file, make sure the folder you're moving the file into also exists.
const rename = (oldPath, newPath) => {
try {
const oldFileExists = fs.existsSync(oldPath);
const newFileExists = fs.existsSync(newPath);
if (newFileExists) {
throw {
success: false,
message: "The file you're trying to rename to already exist!"
};
}
if (oldFileExists) {
fs.renameSync(oldPath, newPath);
return {
success: true,
message: "The file has been renamed!"
};
} else {
throw {
success: false,
message: "The file you're trying to rename doesn't exist!"
};
}
} catch (error) {
return error;
}
};
rename("./example.txt", "./example1.txt")
Delete File
Similarly for deleting a file, check if it exists and if it does then delete it or throw an error.
const unlink = filePath => {
try {
const fileExists = fs.existsSync(filePath);
if (fileExists) {
fs.unlinkSync(filePath);
return {
success: true,
message: "The file has been deleted!"
};
} else {
throw {
success: false,
message: "The file doesn't exist!"
};
}
} catch (error) {
return error;
}
};
unlink("./example1.txt")
Conclusion
These are basic operations you might need when you want manipulate file system. The fs module contains a plethora of functions like these that you can make use of.
Here's the link for the documentation for fs module on NodeJs website for reference.
Need to ask a quick question?
Ask away on my twitter @prvnbist
originally posted on my blog
Top comments (2)
The fs.promises approach makes file operations much more easier as everything is a promise, and promises are cool.
Read file examples (also with promises) => youtu.be/6sNisr1FLRY