fsMate A modular collection of file system utilities for Node.js
It simplifies working with files and directories by providing a higher-level, promise-based API for common file operations such as checking access permissions, creating files/directories, copying files, and mirroring directories.
Installation
npm install fsmate
Usage
Use this syntax when working in Node.js environments that follow the CommonJS module system.
CommonJS
const fsMate = require('fsmate');
Note: The deprecated constants fs.F_OK, fs.R_OK, fs.W_OK, & fs.X_OK are not exported on Node.js v24.0.0+; please use their fs.constants equivalents.
ESM
There is also an fsmate/esm import, that supports both default and named exports. However, note that fs methods are not included in fsmate/esm; you still need to import fs and/or fs/promises seperately:
import fsMate from 'fsmate/esm';
import {remove, copy, rename} = 'fsmate/esm';
but you probably want to just use regular fsmate instead of fsmate/esm for default exports:
import fsMate from 'fsmate';
Async vs Async/Await vs Sync
All async methods will return a promise
JavaScript handles file operations in three ways: Promises run tasks in the background with .then() / .catch(), async/await makes them look sequential, and synchronous methods pause execution until the task finishes—simple and straightforward.
Example:
const fsMate = require('fsmate');
// Async with Promises:
fsMate.mirror('/home/user/myDir', '/home/user/mirrorDir')
.then(() => console.log('success'))
.catch(err => console.log(err));
// With async/await:
async function mirror(originDir, targetDir) {
try {
await fsMate.mirror(originDir, targetDir);
console.log('success');
} catch(err) {
console.log(err);
}
}
mirror('/home/user/myDir', '/home/user/mirrorDir');
// Sync:
try {
fsMate.mirrorSync('/home/user/myDir', '/home/user/mirrorDir');
console.log('success');
} catch(err) {
console.log(err);
}
Learn for more Documentation see: more
Methods And Features
Async
| Method | Description |
|---|---|
| isExecutable | Check if a file/directory has execute permissions. |
| isFile | Check if the given path is a regular file. |
| isDir | Check if the given path is a directory. |
| isLink | Check if the given path is a symbolic link. |
| isReadable | Check if a file/directory has read permissions. |
| isWritable | Check if a file/directory has write permissions. |
| mkdir | Creates a directories recursively. |
| mkfile | Create an empty files (or overwrite if specified). |
| exists | Check if a file or directory exists. |
| touch | Create a file if it doesn’t exist or update its timestamp. |
| rename | Rename or move a file/directory. |
| scandir | List files and directories in a given folder. |
| remove | Safely remove files or directories (with rename trick). |
| rm | Remove files or directories using native fs.rm. |
| mirror | Recursively copy an entire directory tree. |
| copy | Copy a single file with overwrite control. |
| empty | Remove all contents inside a file or directory without deleting it. |
| prependFile | Add content at the beginning of a file. |
| readFile | Read a file’s content (optionally parse JSON). |
| readLine | Read a file line-by-line with range support. |
| writeFile | Write content to a file (overwrites existing). |
| appendFile | Append content to the end of a file. |
| dumpFile | Atomically write a file by first writing to a temp file. |
Sync
| Method | Description |
|---|---|
| isExecutableSync | Sync check for execute permissions. |
| isLinkSync | Sync check if path is a symbolic link. |
| isFileSync | Sync check if path is a regular file. |
| isDirSync | Sync check if path is a directory. |
| isReadableSync | Sync check for read permissions. |
| isWritableSync | Sync check for write permissions. |
| mkdirSync | Sync creates a directories recursively. |
| mkfileSync | Create an empty files (or overwrite if specified). |
| touchSync | Sync create/update file timestamp. |
| renameSync | Sync rename or move a file/directory. |
| scandirSync | Sync list directory contents. |
| removeSync | Sync safe remove (with rename trick). |
| appendFileSync | Sync append content to a file. |
| emptySync | Sync remove all contents inside a file/directory. |
| mirrorSync | Sync recursively copy a directory tree. |
| copySync | Sync copy a single file. |
| readFileSync | Read a file’s content (optionally parse JSON). |
| rmSync | Sync remove file/directory using native fs.rm. |
| readLineSync | Sync read file line-by-line. |
| writeFileSync | Sync write content to a file. |
| prependFileSync | Sync add content at file start. |
| dumpFileSync | Sync atomic file write. |
Other Methods
| Method | Description |
|---|---|
| multiStream | Merge multiple readable streams into one. |
| stringify | Convert different data types to a string safely. |
| tmpName | Generate a random temporary file/directory name. |
| tempNam | Generate a SHA1-hash-based temp file name. |
| createInputStream | Convert string, Buffer, or object into a readable stream. |
Contributing
Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.
License
Licensed Under MIT
Copyright (c) 2025 Indian Modassir