require-glob/readme.md

Require multiple modules using glob patterns. Supports exclusions.

# `require-glob`

[![NPM version][npm-img]][npm-url] [![Downloads][downloads-img]][npm-url]

Requires multiple modules using glob patterns and combines them into a nested object.

## Install

    $ npm install --save require-glob

## Usage

```
┣━ unicorn.js
┣━ cake.js
┗━ rainbow/
   ┣━ red-orange.js
   ┣━ _yellow_green.js
   ┗━ BluePurple.js
```

```js
var requireGlob = require('require-glob');

requireGlob(['**/*.js', '!cake.js']).then(function (modules) {
    console.log(modules);
    // {
    //     unicorn: [object Object],
    //     rainbow: {
    //         redOrange: [object Object],
    //         _yellow_green: [object Object],
    //         BluePurple: [object Object]
    //     }
    // }
});
```

## API

### requireGlob(patterns [, options]): Promise

Returns a promise that resolves to an object containing the required contents of matching globbed files.

### requireGlob.sync(patterns [, options]): Object

Returns an object containing the required contents of matching globbed files.

#### patterns

Type: `{String|Array.<String>}`

One or more [`minimatch` glob patterns][minimatch] patterns. Supports negation.

[minimatch]: https://github.com/isaacs/minimatch#usage

#### options

Type: `{Object}` (optional)

This object is ultimately passed directly to [`node-glob`][glob] so check there for more options, in addition to those below.

[glob]: https://github.com/isaacs/node-glob#usage

##### cwd

Type: `{String}` (default: `__dirname`)

The current working directory in which to search. Defaults to the `__dirname` of the requiring module so relative paths work the same as Node.js's require.

##### base

Type: `{String}` (default: common non-glob parent)

Default is everything before the first glob starts in the first pattern (see [`glob-parent`][parent]).

_This option has no effect if you define your own `mapper` function._

[parent]: https://github.com/es128/glob-parent#usage

```js
requireGlob(['./src/**', './lib/**'], { cwd: '/home/jdoe/my-module' });
// base is: /home/jdoe/my-module/src

requireGlob('./{src,lib}/**', { cwd: '/home/jdoe/my-module' });
// base is: /home/jdoe/my-module
```

##### bustCache

Type: `{Boolean}` (default: `false`)

Whether to force the reload of modules by deleting them from the cache. Useful inside watch tasks.

_This option has no effect if you define your own `mapper` function._

##### mapper

Type: `{Function(options, filePath, i, filePaths) : Object}`

The [mapper][map] is reponsible for requiring the globbed modules. The default mapper returns an object containing path information and the result of requiring the module.

[map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map

```js
// file: /home/jdoe/my-module/index.js
requireGlob('./src/**/*.js');

// the resulting list of files
[
    './src/unicorn.js',
    './src/rainbow/red-orange.js',
    './src/rainbow/_yellow_green.js',
    './src/rainbow/BluePurple.js',
]

// will be mapped to
[
    {
        cwd: '/home/jdoe/my-module',
        base: '/home/jdoe/my-module/src',
        path: '/home/jdoe/my-module/src/unicorn.js',
        exports: require('./src/unicorn')
    },
    {
        cwd: '/home/jdoe/my-module',
        base: '/home/jdoe/my-module/src',
        path: '/home/jdoe/my-module/src/rainbow/red-orange.js',
        exports: require('./src/rainbow/red-orange')
    },
    {
        cwd: '/home/jdoe/my-module',
        base: '/home/jdoe/my-module/src',
        path: '/home/jdoe/my-module/src/rainbow/_yellow_green.js',
        exports: require('./src/rainbow/_yellow_green')
    },
    {
        cwd: '/home/jdoe/my-module',
        base: '/home/jdoe/my-module/src',
        path: '/home/jdoe/my-module/src/rainbow/BluePurple.js',
        exports: require('./src/rainbow/BluePurple')
    }
]
```

##### reducer

Type: `{Function(options, result, fileObject, i, fileObjects): Object}`

The [reducer][reduce] is responsible for generating the final object structure. The default reducer expects an array as produced by the default mapper and turns it into a nested object. Path separators determine object nesting. Directory names and file names are converted to `camelCase`. File extensions are ignored.

[reduce]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce

```js
// mapper example is reduced to

{
    unicorn: require('./src/unicorn.js'),
    rainbow: {
        redOrange: require('./src/rainbow/red-orange.js'),
        _yellow_green: require('./src/rainbow/_yellow_green.js'),
        BluePurple: require('./src/rainbow/BluePurple.js'),
    }
}
```

##### initialValue

Type: `{any}` (default: `{}`)

The initial value passed to the [reducer][reduce]. The default is an empty object, as expected by the default reducer.

[reduce]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce

```js
// file: /home/jdoe/my-module/index.js
const defaultDependencies = {
    clover: require('clover'),
    unicorn: require('unicorn'),
};

requireGlob('./src/**/*.js', {
    initialValue: defaultDependencies,
});

// reducer example is changed to
{
    clover: require('clover'),
    unicorn: require('./src/unicorn.js'),
    rainbow: {
        redOrange: require('./src/rainbow/red-orange.js'),
        _yellow_green: require('./src/rainbow/_yellow_green.js'),
        BluePurple: require('./src/rainbow/BluePurple.js'),
    }
}
```

##### keygen

Type: `{Function(options, fileObj): String|Array.<String>}`

The default reducer uses this function to generate a unique key path for every module. The default keygen converts hyphenated and dot-separated sections of directory names and the file name to `camelCase`. File extensions are ignored. Path separators determine object nesting.

_This option has no effect if you define your own `reducer` function._

```js
// given the mapped object
{
    cwd: '/home/jdoe/my-module',
    base: '/home/jdoe/my-module/src',
    path: '/home/jdoe/my-module/src/fooBar/bar-baz/_bat.qux.js',
    exports: require('./src/fooBar/bar-baz/_bat.qux.js')
}

// the keygen will produce
[
    'fooBar',
    'barBaz',
    '_batQux'
]

// which the reducer will use to construct
{
    fooBar: {
        barBaz: {
            _batQux: require('./src/fooBar/bar-baz/_bat.qux.js')
        }
    }
}
```

## Contribute

Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.

### Test

    $ npm test

----

MIT © [Shannon Moeller](http://shannonmoeller.com)

[downloads-img]: http://img.shields.io/npm/dm/require-glob.svg?style=flat-square
[npm-img]:       http://img.shields.io/npm/v/require-glob.svg?style=flat-square
[npm-url]:       https://npmjs.org/package/require-glob