# require-glob

> Require multiple modules using glob patterns. Supports exclusions.

Latest version **4.1.0** (published 2022-06-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install require-glob
pnpm add require-glob
yarn add require-glob
bun add require-glob
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.0 |
| Published | 2022-06-16 |
| First published | 2015-03-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 10 |
| Dependencies | 3 |
| Unpacked size | 18.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 21 |
| Author | Shannon Moeller |
| Maintainers | shannonmoeller |
| Keywords | dir, directory, directories, file, files, glob, globs, map, mapreduce, multi, multiple, reduce, require, tree |

## Links

- npm: https://www.npmjs.com/package/require-glob
- Repository: https://github.com/shannonmoeller/require-glob
- Issues: https://github.com/shannonmoeller/require-glob/issues
- npm.io page: https://npm.io/package/require-glob

## Dependencies (3)

- [globby](https://npm.io/package/globby.md) ^11.0.3
- [glob-parent](https://npm.io/package/glob-parent.md) ^6.0.0
- [parent-module](https://npm.io/package/parent-module.md) ^2.0.0

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 4.1.0 (latest) — 2022-06-16
- 4.0.0 — 2021-06-08
- 3.2.0 — 2016-09-26
- 3.1.1 — 2016-02-12
- 3.1.0 — 2016-02-07
- 3.0.2 — 2016-02-05
- 3.0.1 — 2016-02-05
- 3.0.0 — 2016-02-05
- 2.0.0 — 2016-02-05
- 1.3.2 — 2015-10-01
- 1.3.1 — 2015-05-06
- 1.3.0 — 2015-05-06
- 1.2.0 — 2015-04-18
- 1.1.1 — 2015-04-13
- 1.1.0 — 2015-04-13
- … 5 more at https://npm.io/package/require-glob/versions

## README

# `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

---
_Source: https://npm.io/package/require-glob · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._