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