FS-EXTENDER

Extender module for node filesystem

Description

The intention of this module is to provide many functions that don't yet exist in node fs module, like copy, move, list, find..., and also normalize their functioning between node versions.

This module don't make any changes to node fs module, except patching close and closeSync, and it can be turned off.

At its core this module works like graceful-fs but instead of cloning the fs module it makes an augmentation of the fs module or any other fs model type like. Environment Variables

This module can be used like a fs replacement module.

Usage

Install the package

npm install --save fs-extender

import * as fs from "fs-extender";

fs.copy(dir, someOtherDir, (err) => {
    if (!err) {
        console.log("Directory copied with sucess.");
    }
});

or

const fs = require("fs-extender");

fs.copy(dir, someOtherDir, (err) => {
    if (!err) {
        console.log("Directory copied with sucess.");
    }
});

Runing tests

• npm run lint: runs the linter
• npm run unit: run unit tests
• npm test: run both lint and unit tests
• npm testUlimit: run tests defining ulimit to 50
• npm testMemoryLeak: run tests to check for memoery leakage
• npm testExternalFs: run tests based on provided fs module
• npm testExternalMockedFs: run tests based on provided fs module that act like a mock
• npm test-all: run all the above tests

Contribute

If you find a problem with the package you can

• Submit a Bug
  • If you provide a test case it will make the issue resolution faster

or even make a

• Pull request

Add something new

If you wan't to add something new, following this steps would be much apreciated:

• Develop the new helper, with clean and readable code
• Develop tests for the new helper
• Include in the comments a description of what the helper does, the input arguments and what it returns

Documentation

Besides the node file system documentation for all the node fs related functions the new methods provided can be found below.

• Environment Variables - Environment variables documentation

  • FS_EXTENDER_FS_OVERRIDE
  • FS_EXTENDER_IGNORE_PATCH_CLOSE
  • FS_EXTENDER_IGNORE_PATCH
  • FS_EXTENDER_TIMEOUT
  • FS_EXTENDER_TIMEOUT_SYNC
  • FS_EXTENDER_WIN32_TIMEOUT
  • FS_EXTENDER_WIN32_TIMEOUT_SYNC

• Patched

• New Methods

  • isEmpty => Check if given item is empty
  • isEmptySync => Check if given item is empty
  • statsIsDirectory => check if item is a directory
  • statIsDirectorySync => check if item is a directory
  • statIsFile => check if item is a file
  • statIsFileSync => check if item is a file
  • statIsSymbolicLink => check if item is a SymLink
  • statIsSymbolicLinkSync => check if item is a SymLink
  • Promises API
    • fsPromises.isEmpty => Check if given item is empty
    • fsPromises.statIsDirectory => check if item is a directory
    • fsPromises.statIsFile => check if item is a file
    • fsPromises.statIsSymbolicLink => check if item is a SymLink

• Compare => Compare files or directories

  • dirByte => Compare two directories in a byte-to-byte file comparison
  • dirHash => Compare two directories with a hash file comparison
  • dirByteSync => Compare two directories in a byte-to-byte file comparison
  • dirHashSync => Compare two directories with a hash file comparison
  • filesByte => Compare two files in a byte-to-byte comparison
  • filesHash => Compare two files in a hash comparison
  • filesByteSync => Compare two files in a byte-to-byte comparison
  • filesHashSync => Compare two files in a hash comparison
  • Promises API
    • fsPromises.dirByte => Compare two directories in a byte-to-byte file comparison
    • fsPromises.dirHash => Compare two directories with a hash file comparison
    • fsPromises.filesByte => Compare two files in a byte-to-byte comparison
    • fsPromises.filesHash => Compare two files in a hash comparison

• Copy => Copy Files

  • copy => async copy
  • copySync => sync copy
  • Promises API
    • copy => promise copy

• Ensure => Ensure the existence of various items in file system

  • ensureDir => Ensures directory exostence in file system
  • ensureFile => Ensures file existence in file system
  • ensureLink => Ensures link existence in file system
  • ensureSymlink => Ensures symlink existence in file system
  • ensureDirSync => Ensures directory exostence in file system
  • ensureFileSync => Ensures file existence in file system
  • ensureLinkSync => Ensures link existence in file system
  • ensureSymlinkSync => Ensures symlink existence in file system
  • Promises API
    • ensureDir => Ensures directory exostence in file system
    • ensureFile => Ensures file existence in file system
    • ensureLink => Ensures link existence in file system
    • ensureSymlink => Ensures symlink existence in file system

• Find => Find items in the file system

  • find => async find
  • findSync => sync find
  • Promise API
    • promises.find => promise find

• Json => Multiple json related tools to work with files

  • ensureJsonFile => write object to json file ensuring file existence
  • readJsonFile => read object from json file
  • readJsonLines => read json file line by line
  • writeJsonFile => write object to json file
  • ensureJsonFileSync => write object to json file ensuring file existence
  • readJsonFileSync => read object from json file
  • writeJsonFileSync => write object to json file
  • Promise API
    • promises.ensureJsonFile => write object to json file ensuring file existence
    • promises.readJsonFile => read object from json file
    • promises.readJsonLines => read json file line by line
    • promises.writeJsonFile => write object to json file

• List => List items in file system

  • list => async list
  • listSync => sync list
  • Promise API
    • promises.list => promise list

• Mkdirp => Recursive creation of directories

  • mkdirp => async mkdirp
  • mkdirpSync => sync mkdirp
  • Promise API
    • promises.mkdirp => promise mkdirp

• Move => Move items in the file system

  • move => async move
  • moveSync => sync move
  • Promise API
    • promises.move => promise move

• Rm => Remove items from the file system

  • rm => async rm
  • rmSync => sync rm
  • Promise API
    • promises.rm => promise rm

• EmptyDir => Clean items from directory

  • emptyDir => async emptyDir
  • emptyDirSync => sync emptyDir
  • Promise API
    • promises.emptyDir => promise emptyDir

• Size => Check the size of an item in the file system

  • size => async size
  • sizeSync => sync size
  • Promise API
    • promises.size => promise size

• Walk => Walk through directories

  • walk => async walk
  • walkSync => sync walk
  • Promise API
    • promises.walk => promise walk

Examples

For more examples just check the tests folder

Why this module

First things first,

Why not use something like the graceful-fs module?

When this module was started graceful-fs changed the fs module directly, that was a no go, if some of the node base modules must change it's way of functioning it must be done very carefully and in very rare occasions, just like the patch that this module implements in close file functions, just like graceful-fs now does, and because there's no way to don't use the graceful-fs when it is loaded in another module in the chain (see why not using jest for tests).

Why not use something like the fs-extra module?

Fisrt, because when this module was started the fs-extra didn't exist or was in their infancy, there where some tools like ncp (abandoned copy module) and other's but it was a pain to use all that separated tools.

Second because fs-extra is a fantastic module but in the background it operates (or used to) on top of graceful-fs (see first awnser) and it doens't have all the tools and options that I needed.

Why not use Jest for tests?

Because jest uses fs-extra as one of the dependencies and as we saw fs-extra uses graceful-fs and that makes impossible to test this module with jest and there's no way to remove graceful-fs from the chain, with this module you can bypass it if you wan't (see Environment Variables), even if it come from another module.

The modules that originated this module where using jest for tests until jest started using fs-extra and then the number of perfectly valid tests failling was impressive, then mocha to the rescue.

Credits

• ncp - One of the modules that originated all this module (forget about the name of some others)
• graceful-fs - A very good module for patching the fs module but with some flaws mainly the lack of an option to bypass the module
• fs-extra - A very good module but that don't have all the tools needed for the job (or options for the tools)
• mocha - Very good testing framework.

License

MIT License

Copyright (c) 2011 - 2021 Joao Parreira [email protected]