fsMate

fsMate A modular collection of file system utilities for Node.js

This package accesses the local file system to perform its core functionality. It does not transmit file contents to any remote server.

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.

See Latest Update

• Added @see references in JSDoc comments for better documentation and navigation.
• Added dirOnly option in scandir() and scandirSync() to list only directories.
• Added fileOnly option in scandir() and scandirSync() to list only files.
• Added Third filter argument in scandir() and scandirSync() to allow custom filtering (supports array or function).
• Improved scandir() documentation with @see reference to official docs.

See Release Notes: 👉 CHANGELOG

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

Asynchronous methods with short describe and complete documentation.

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.
move	Asyncronously moves a file or 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.
truncate	Clears file content without deleting it (creates if missing).
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.
filesize	Gets file size in bytes.
fseek	Seeks on a file pointer.
ftell	Returns the current position of the file read/write pointer.
fgets	Gets line from file pointer.
fpassthru	Output all remaining data on a file pointer.
fread	Binary-safe file read.
fwrite	Binary-safe file write.
rewind	Rewind the position of a file pointer.

Sync

Synchronous methods with short describe and complete documentation.

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.
moveSync	Sync moves a file or 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.
truncateSync	Sync Empties a file but keeps it (creates if missing).
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.
filesizeSync	Sync Gets file size in bytes.
fseekSync	Sync Seeks on a file pointer.
ftellSync	Sync Returns the current position of the file read/write pointer.
fgetsSync	Sync Gets line from file pointer.
fpassthruSync	Sync Output all remaining data on a file pointer.
freadSync	Sync Binary-safe file read.
fwriteSync	Sync Binary-safe file write.
rewindSync	Sync Rewind the position of a file pointer.

Other Methods

Here listed other methods with short describe and complete documentation.

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