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.
npm install modclean --save-devconst modclean = require('modclean');The options below can be used to modify how ModClean works.
(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.
(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.
(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.
(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.
(Boolean) Default: false
Set to true to skip directories from being deleted during the cleaning process.
(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.
(Boolean) Default true
Set to false to skip dot files from being deleted during the cleaning process.
(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.
(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.
(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.
(Boolean) Default: true
Whether to remove empty directories after the cleanup process. This is usually a safe option to use.
(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.
(Object) Default: {}
Custom options to pass into glob to further customize file searching. Will override existing options.
(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.
(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.
(Boolean) Default: false
Force deletion to be done also in symlinked packages (when using npm link).
These are the methods and properties exported when calling const modclean = require('modclean');.
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...
});(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.
Access to the ModClean class constructor.
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;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 */
});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).
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).
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.
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.
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.
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.
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).
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.
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.
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.
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.
Type: Array
Array of error objects that contains all errors encountered during the process.
Type: String
The current version of ModClean.
Type: Object
Object containing loaded patterns with the properties: allow (array of strings) and ignore (array of strings).
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.
Emitted at the beginning of clean().
| Argument | Type | Description |
|---|---|---|
inst |
ModClean | Access to the instance of ModClean |
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. |
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. |
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. |
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. |
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. |
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. |
Emitted once clean() has completed before resolving the Promise.
| Argument | Type | Description |
|---|---|---|
results |
Object | Results object that is returned from clean(). |
Emitted if there was an error thrown during the whole process.
| Argument | Type | Description |
|---|---|---|
err |
Error | Error Object |
Emitted before finding/removing empty directories.
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(). |
Emitted after a list of empty directories is found.
| Argument | Type | Description |
|---|---|---|
results |
Array[String] | Array of paths that were found. |
Emitted after an empty directory is deleted successfully.
| Argument | Type | Description |
|---|---|---|
dir |
String | The directory path that was deleted. |
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:
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
The absolute path the file/folder.
Example: /home/user/projects/my-app/node_modules/module/README.md
Absolute path to the parent directory containing this file/folder.
Example: /home/user/projects/my-app/node_modules/module/
The file name and extention (for files) or directory name (for directories) without any path.
Example: README.md
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
True if this is a directory, false if it is a file.
Example: false
stat fs.Stats
The stat of the file/folder.
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:
The method name in which the error originated from in ModClean.
Additional data provided at the time of the error.
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.
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();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);
});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);
});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();Information:
Wiki Home
Migrating to 3.x
Migrating to 2.x
Benchmarks
Custom Pattern Plugins
Documentation (v3):
CLI Documentation
API Documentation
Documentation (v2):
CLI Documentation
API Documentation