API

When ModClean is installed locally to your project, you gain access to the programmatic API. Using the API allows for further customization of how ModClean works and allows you to integrate it into your build/CI process.

• Install
• Usage
  • Options
  • Module
  • ModClean Class
    • Public Methods
    • Internal Methods
    • Properties
    • Events
    • File Object
    • Error Object
  • Examples

Install

npm install modclean --save-dev

Usage

const modclean = require('modclean');

Options

The options below can be used to modify how ModClean works.

cwd

(String) Default: process.cwd()
The path in which ModClean should recursively search through to find files to remove. If the path does not end with options.modulesDir, it will be appended to the path, allowing this script to run in the parent directory.

patterns

(Array[string]) Default ["default:safe"]
Patterns plugins/rules to use. Each value is either the full plugin module name (ex. modclean-patterns-pluginname) or just the last section of the module name (ex. pluginname). Plugins will usually have different rules to use, you can specify the rule name by appending a colon ':' and the rule name (ex. pluginname:rule). If a rule name is not provided, it will load the first rule found on the plugin. If you want to use all rules, you can use an asterisk as the rule name (ex. pluginname:*). By default, modclean-patterns-default is included. If you want to create your own plugin, see Custom Patterns Plugins.

additionalPatterns

(Array[string]) Default null Additional custom glob patterns to include in the search. This will allow further customization without the need of creating your own patterns plugin.

ignorePatterns

(Array[string]) Default null Custom glob patterns to ignore during the search. Allows skipping matched items that would normally be removed, which is good for patterns that match existing module names you wish not to be removed. NEW: If any of the provided ignore patterns are in the standard matching patterns, they will now be removed from the matching patterns.

noDirs

(Boolean) Default: false
Set to true to skip directories from being deleted during the cleaning process.

ignoreCase

(Boolean) Default true
Whether glob should ignore the case of the file names when searching. If you need to do strict searching, set this to false.

dotFiles

(Boolean) Default true Set to false to skip dot files from being deleted during the cleaning process.

modulesDir

(String|Boolean) Default: "node_modules"
The modules directory name to use when looking for modules. This is only used when setting the correct options.cwd path. If you do not want the modules directory to be appended to options.cwd, set this option to false. If options.cwd already ends with the value of this option, it will not be appended to the path.

filter Since 3.0.0

(Function) Default: null
Optional filter function called for each file/folder matched. The function is called with a single parameter, file. You may return true from this function to mark the file/folder for deletion, return false to prevent the file/folder from being deleted, OR you may return a Promise that resolves with true or false in case you need to do any asynchronous tasks.

skipModules Since 3.0.0

(Boolean) Default: true
Enables skipping of directories that are considered a module which have been matched by the patterns. Since 3.0.0, ModClean will now determine if the matched directory is a module by checking if it contains a package.json and it's parent directory is named node_modules.

removeEmptyDirs

(Boolean) Default: true
Whether to remove empty directories after the cleanup process. This is usually a safe option to use.

emptyDirFilter

(Function) Default: function(file) { ... }
Optional filter function to use when checking if directories are empty. This function is used as an iterator, looping through each file found in a directory. Function is called with 1 parameter file which is a file name. If this function returns true, the file is considered a valid file that will not make the directory considered empty. If returns false, the file is considered invalid, thus being ignored. By default, this function filters out .DS_Store and Thumbs.db files.

globOptions Since 3.0.0

(Object) Default: {}
Custom options to pass into glob to further customize file searching. Will override existing options.

errorHalt

(Boolean) Default: false
Whether the script should exit with a filesystem error if one is encountered. This really only pertains to systems with complex permissions or Windows filesystems. The rimraf module will only throw an error if there is actually an issue deleting an existing file. If the file doesn't exist, it does not throw an error.

test

(Boolean) Default: false
Whether to run in test mode. If set to true everything will run (including all events), although the files will not actually be deleted from the filesystem. This is useful when you need to analyze the files to be deleted before actually deleting them.

followSymlink Since 2.1.1

(Boolean) Default: false
Force deletion to be done also in symlinked packages (when using npm link).

---

Module

These are the methods and properties exported when calling const modclean = require('modclean');.

modclean([options]) Function

Create a new ModClean instance; the same as calling new modclean.ModClean().

Argument	Type	Required?	Description	Default
options	Object	No	Optional options object to configure ModClean	{}

Returns: new ModClean() - Instance of ModClean

const modclean = require('modclean');

let mc = modclean({
    // options...
});

Static Properties

modclean.defaults

(Object) - The default options used in all created ModClean instances. You may change the defaults at anytime if you will be creating multiple instances that need to use the same options.

modclean.ModClean([options])

Access to the ModClean class constructor.

---

ModClean Class

The main class exported by this module. Extends EventEmitter.

You can gain direct access to the ModClean Class using the following example:

const ModClean = require('modclean').ModClean;

Public Methods

ModClean([options][,cb])

Constructor. Create instance of the ModClean class. Must be called with new.

Argument	Type	Required?	Description	Default
options	Object	No	Optional options object to configure ModClean	{}

Returns: this - The new instance of the class

const ModClean = require('modclean').ModClean;
    
// Create new instance
let mc = new ModClean({
    /* options */
});

// --- OR Shortcut --- //
const modclean = require('modclean')({
    /* options */
});

clean()

Runs the ModClean process. Must be called in order to start the cleaning process.

Returns: Promise - Returns a Promise that resolves with a results object containing: files (array of file objects that were matched), deleted (array of string file paths that were successfully, including empty directories is applicable), and empty (array of string file paths that were matched as empty directories, if applicable).

cleanEmptyDirs()

Finds all empty directories and deletes them from options.cwd. This is called by default as part of the clean() process if options.removeEmptyDirs is set to true. Useful for removing directories that have now become empty during the file cleanup process.

Returns: Promise - Returns a Promise that resolves with a results object containing: empty (array of string paths that were found) and deleted (array of string paths that were successfully removed).

on(event, fn)

Creates an event handler on the ModClean instance using EventEmitter.

Argument	Type	Required?	Description	Default
event	String	Yes	Event name to listen to (events are documented below)
fn	Function	Yes	Function to call once the specified event is emitted

See Events for the available event names and the data provided for each one.

Internal Methods

NOTE: These methods are used internally by ModClean. They are documented in case there are any needs to create custom functionality for ModClean to fit specific needs. Keep in mind that these methods may change at any time.

_find()

Internally used by ModClean to search for files and folders based on the loaded patterns/rules.

Returns: Promise - Returns a Promise that resolves with an array of file objects.

_buildFileObject(file)

Generates the file object for the given file.

Argument	Type	Required?	Description	Default
file	String	Yes	File path to generate the file object for.	--

Returns: Promise - Returns a Promise that resolves with the file object or null if there was an issue reading the file/folder.

_process(files)

Internally used by ModClean to process each of the files/folders for deletion. This iterates the files and calls _deleteFile() on each one in paralell.

Argument	Type	Required?	Description	Default
files	Array[File Object]	Yes	Array of file objects to be deleted.	--

Returns: Promise - Returns a Promise that resolves with a results object containing: files (array of file objects passed into the function) and deleted (array of string file paths that were successfully deleted).

_deleteFile(file)

Internally used by ModClean to delete a file by file object. This method determines if the file/folder should be deleted by running options.filter, checking if it is a module (if options.skipModules is enabled), and if the process is running in test mode. If the file/folder fails any of the tests, the file is skipped and not deleted.

Argument	Type	Required?	Description	Default
file	File Object	Yes	File object to be deleted.	--

Returns: Promise - Returns Promise that resolves with a boolean. Will return true if file was deleted without error (Note: Will also return true if test mode is enabled) or false if the file was skipped or there was an error. This Promise will not throw unless options.errorHalt is enabled.

_findEmptyDirs()

Internally used by ModClean to find all empty directories within options.cwd. This will only match directories that pass the options.emptyDirFilter function.

Returns: Promise - Returns a Promise that resolves with an array of paths to found empty directories.

_removeEmptyDirs(dirs)

Internally used by ModClean to delete all empty directories provided.

Argument	Type	Required?	Description	Default
dirs	Array[String]	Yes	Array of string paths to be removed.	--

Returns: Promise - Returns a Promise that resolves with an array of string paths that were successfully removed.

Properties

options

Type: Object
Compiled options object used by the ModClean instance. By default, the options are a copy of modclean.defaults overridden by any passed in options to the constructor. These options may be changed.

errors

Type: Array
Array of error objects that contains all errors encountered during the process.

version

Type: String
The current version of ModClean.

_patterns

Type: Object
Object containing loaded patterns with the properties: allow (array of strings) and ignore (array of strings).

Events

The following events are emitted from the ModClean instance. In version 3.0.0, events are now namespaced for more clarity and may return different results.

clean:start

Emitted at the beginning of clean().

Argument	Type	Description
inst	ModClean	Access to the instance of ModClean

file:find

Emitted before the file searching begins.

Argument	Type	Description
patterns	Array[String]	Compiled list of glob patterns that will be used to search.
globOpts	Object	The configuration object being passed into glob.

file:list

Emitted once a list of all found files has been compiled from the _find() method.

Argument	Type	Description
files	Array[File Object]	Array of file objects found.

process:start

Emitted at the start of the _process() function, prior to files being iterated for deletion.

Argument	Type	Description
files	Array[File Object]	Array of file objects found to be removed.

file:deleted

Emitted each time a file has been deleted from the file system by the _deleteFile() method. This even will additionally fire when options.test is enabled.

Argument	Type	Description
file	File Object	File Object that has been successfully deleted.

file:skipped

Emitted each time a file is skipped because of options.filter or if options.skipModules is true and the file is marked as a module.

Argument	Type	Description
file	File Object	File Object that has been skipped.

process:done

Emitted once processing and deletion of files has completed by the _process() method.

Argument	Type	Description
results	Array[String]	List of file paths that were successfully removed.

clean:complete

Emitted once clean() has completed before resolving the Promise.

Argument	Type	Description
results	Object	Results object that is returned from clean().

error

Emitted if there was an error thrown during the whole process.

Argument	Type	Description
err	Error	Error Object

emptydir:start

Emitted before finding/removing empty directories.

emptydir:done

Emitted after finding/removing empty directories before the Promise is resolved for cleanEmptyDirs().

Argument	Type	Description
results	Object	Results object that is returned from cleanEmptyDirs().

emptydir:list

Emitted after a list of empty directories is found.

Argument	Type	Description
results	Array[String]	Array of paths that were found.

emptydir:deleted

Emitted after an empty directory is deleted successfully.

Argument	Type	Description
dir	String	The directory path that was deleted.

File Object Since 3.0.0

In ModClean 3.0.0, each found file/folder (except any found by cleanEmptyDirs()) is compiled into a file object containing various information about it. This gives additional abilities to ModClean.

Lets say we have a file at the path: /home/user/projects/my-app/node_modules/module/README.md

Each file object contains the following properties:

path String

The relative path to the file/folder as returned by glob. In some circumstances, this may be the absolute path the file/folder.
Example: ./my-app/node_modules/module/README.md

fullPath String

The absolute path the file/folder.
Example: /home/user/projects/my-app/node_modules/module/README.md

dir String

Absolute path to the parent directory containing this file/folder.
Example: /home/user/projects/my-app/node_modules/module/

name String

The file name and extention (for files) or directory name (for directories) without any path.
Example: README.md

isModule Boolean

True if is a directory and is deemed to be module. This is determined by checking if this directory contains a package.json file and the parent directory is options.modulesDir or node_modules.
Example: false

isDirectory Boolean

True if this is a directory, false if it is a file.
Example: false

stat fs.Stats

The stat of the file/folder.

Error Object

Errors are stored in modclean.errors for tracking purposes. Since filesystems can act differently, this allows us to track errors without causing the process to fail. Each error that is tracked is an Error with additional custom properties. Additionally, each error tracked is emitted through the error event.

All properties of a standard Error are available with the addition of the following properties added by ModClean:

method String

The method name in which the error originated from in ModClean.

payload Mixed

Additional data provided at the time of the error.

---

Examples

The folllowing examples will help you get started using the API. If you want to see a real-world example, see the source of the CLI.

Using Shortcut (async/await)

const modclean = require('modclean')(/* options */);

async function cleanup() {
    try {
        let result = modclean.clean();
        console.log(`Successfully removed ${result.deleted.length} files/folders from the project`);
        
        return true;
    catch(error) {
        console.error(error);
        return false;
    }
}

cleanup();

Using Shortcut (Promises)

const modclean = require('modclean')(/* options */);

modclean.clean()
    .then(result => {
        console.log(`Successfully removed ${result.deleted.length} files/folders from the project`);
    })
    .catch(error => {
        console.error(error);
    });

Using ModClean Class

const ModClean = require('modclean').ModClean;

let options = {
    // set the patterns to use
    patterns: ["default:safe", "default:caution"],
    
    // example filter function, for ignoring files, you can use `ignorePatterns` option instead
    filter: file => {
        // Skip .gitignore files (keeping them)
        if(file.name.match(/\.gitignore/i)) return false;
        return true;
    }
};

// Create new instance of ModClean
let mc = new ModClean(options);

// Log errors
mc.on('error', err => {
    console.error(`Error in ${err.method}!`);
    console.error(err);
});

mc.on('file:list', files => {
    console.log(`Found ${files.length} files to delete...`);
});

// Start the clean process
modclean.clean()
    .then(result => {
        console.log(`Successfully removed ${result.deleted.length} files/folders from the project`);
    })
    .catch(error => {
        console.error(error);
    });

Advanced Usage

const path = require('path');
const ModClean = require('modclean').ModClean;
    
let mc = new ModClean({
    // Define a custom path
    cwd: path.join(process.cwd(), 'myApp/node/node_modules'),
    // Add additional patterns
    additionalPatterns: ['*.html', '*.png'],
    // Run in test mode so no files are deleted
    test: true
});

mc.on('file:deleted', file => {
    // For every file deleted, log it
    console.log((mc.options.test? 'TEST' : ''), file.path, 'deleted from filesystem');
});

async function cleanup() {
    // Run the cleanup process without using the 'clean' function
    try {
        let files = await mc._find();
        let results = await mc._process(files);
        
        console.log('Deleted Files Total:', results.deleted.length);
    } catch(error) {
        console.error(error);
    }
    
    console.log(`${mc.errors.length} total errors occurred`);
}

cleanup();