require-folder-tree.js

Utility to require multiple files in a folder tree with flexible options

Current status

API is stable and tests cover all options. No known issues.

Basic usage

requireFolderTree( path [, options] )

To require all the .js and .json files in a folder and any sub-folders:

var requireFolderTree = require('require-folder-tree');
var modules = requireFolderTree('/path/to/folder');

If the file structure is:

/
  a.js
  b.js
  c/
    d.js
    e.js

The returned value is:

{
  a: ...,
  b: ...,
  c: {
    d: ...,
    e: ...
  }
}

Advanced usage

Options can be passed to alter the behaviour.

recurse

When true, recurses through subfolders and sub-subfolders requiring an entire tree. Set to false to ignore subfolders. Defaults to true.

// Require only files in base folder
requireFolderTree('/path/to/folder', { recurse: false });
// returns { a: ..., b: ... }

filterFiles

A regular expression for what files to include. First matching group defines the key used in returned object. Defaults to /^(.+)\.js(on)?$/ (i.e. include all .js and .json files)

// Include all .js files except those starting with `_`
requireFolderTree('/path/to/folder', { filterFiles: /^([^_].*)\.js$/ });

filterFolders

A regular expression for what folders to iterate into. First matching group defines the key used in returned object. Defaults to /^([^\.].*)$/ (i.e. process all folders except those beginning with .)

// Process all folders except those starting with `.` or `_`
requireFolderTree('/path/to/folder', { filterFolders: /^([^\._].*)$/ });

fileNameTransform

Function for transforming object keys for files.

// Transform file names to lower case
requireFolderTree('/path/to/folder', {
	fileNameTransform: function(str) { return str.toLowerCase(); }
});

folderNameTransform

Like fileNameTransform, but for folder names.

By default, inherits value of options.fileNameTransform. If you want to define a fileNameTransform function but leave folder names unchanged, set options.folderNameTransform = null.

fileNameAttribute

When set, saves the file name (after fileNameTransform and flatten have been applied) as an attribute of each require-d file. If true, uses value 'name'. Defaults to undefined.

requireFolderTree('/path/to/folder', { fileNameAttribute: true, recurse: false });
// returns { a: { name: 'a', ... }, b: { name: 'b', ... } }

folderNameAttribute

Like fileNameAttribute, but for folder names.

By default, inherits value of options.fileNameAttribute. If you want to save file names only, set options.folderNameAttribute = null.

fileParentAttribute

When set, saves the parent folder as an attribute of each require-d file. If true, uses value 'parent'. Defaults to undefined.

requireFolderTree('/path/to/folder', { fileParentAttribute: true, recurse: false });
// returns { a: { parent: <reference to root object>, ... }, b: { parent: <reference to root object>, ... } }

folderParentAttribute

Like fileParentAttribute, but for folders.

By default, inherits value of options.fileParentAttribute. If you want to save file parents only, set options.folderParentAttribute = null.

flatten

Flattens the folder structure when true. Defaults to false.

requireFolderTree('/path/to/folder', { flatten: true });
// returns { a: ..., b: ..., d: ..., e: ... }

flattenPrefix

Controls how the object keys are created for files nested in folders when flattening. true concatenates the folder name and file name. Defaults to false

requireFolderTree('/path/to/folder', { flatten: true, flattenPrefix: true });
// returns { a: ..., b: ..., cd: ..., ce: ... }

flattenCamel

When true, camel-cases the keys when concatenating the folder name and file name. Defaults to false

requireFolderTree('/path/to/folder', { flatten: true, flattenCamel: true });
// returns { a: ..., b: ..., cD: ..., cE: ... }

flattenSeparator

Sets separator between folder name and file name when concatenating. Defaults to undefined.

requireFolderTree('/path/to/folder', { flatten: true, flattenSeparator: '_' });
// returns { a: ..., b: ..., c_d: ..., c_e: ... }

flattenCustom

Sets a custom function for combining folder name and file name when concatenating. Defaults to undefined.

requireFolderTree('/path/to/folder', {
	flatten: true,
	flattenCustom: function(a, b) { return a + 'x' + b; }
});
// returns { a: ..., b: ..., cxd: ..., cxe: ... }

indexFile

If set, looks for the named file in each folder, and if found uses it as a base for the returned object. Defaults to undefined.

// if index.js contains code `module.exports = { x: 1 }`:

requireFolderTree('/path/to/folder');
// returns { a: ..., b: ..., c: { d: ..., e: ... }, index: { x: 1 } }

requireFolderTree('/path/to/folder', { indexFile: 'index.js' });
// returns { x: 1, a: ..., b: ..., c: { d: ..., e: ... } }

foldersKey

If set, puts all retrieved sub-folders inside the key specified. Defaults to undefined.

requireFolderTree('/path/to/folder', { foldersKey: 'folders' });
// returns { a: ..., b: ..., folders: { c: { d: ..., e: ... } } }

filesKey

If set, puts all retrieved files inside the key specified. Defaults to undefined.

requireFolderTree('/path/to/folder', { filesKey: 'files' });
// returns { files: { a: ..., b: ... }, c: { files: { d: ..., e: ... } } }

Other usage notes

This module will never alter the contents of the require cache. i.e. if you require() any of the files again, they will not have been altered by e.g. using fileNameAttribute option.

Tests

Use npm test to run the tests. Use npm run cover to check coverage.

Changelog

See changelog.md

Issues

If you discover a bug, please raise an issue on Github. https://github.com/overlookmotel/require-folder-tree/issues

Contribution

Pull requests are very welcome. Please:

• ensure all tests pass before submitting PR
• add an entry to changelog
• add tests for new features
• document new functionality/API additions in README