# nconfigurator

> Modular Configuration Library

Latest version **0.5.0** (published 2016-03-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install nconfigurator
pnpm add nconfigurator
yarn add nconfigurator
bun add nconfigurator
```

## Health

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

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2016-03-08 |
| First published | 2016-02-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=4.0.0 |
| Dependencies | 4 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Ryan McVeety |
| Maintainers | rpm0618 |

## Links

- npm: https://www.npmjs.com/package/nconfigurator
- Repository: https://github.com/rpm0618/nconfigurator
- Homepage: https://github.com/rpm0618/nconfigurator#readme
- Issues: https://github.com/rpm0618/nconfigurator/issues
- npm.io page: https://npm.io/package/nconfigurator

## Dependencies (4)

- [co](https://npm.io/package/co.md) ^4.6.0
- [mz](https://npm.io/package/mz.md) ^2.3.1
- [yargs](https://npm.io/package/yargs.md) ^4.1.0
- [lodash](https://npm.io/package/lodash.md) ^4.5.0

## Recent versions

- 0.5.0 (latest) — 2016-03-08
- 0.4.0 — 2016-02-25
- 0.3.0 — 2016-02-23
- 0.2.0 — 2016-02-20
- 0.1.0 — 2016-02-20

## README

# nconfigurator

A modern, modular node.js configuration library. Basically what would happen if
`nconf` and `express` had a baby, with some promises thrown in for good measure.

### Example

```javascript
const Configurator = require('nconfigurator');

Configurator.use('literal', {numberOfMonsters: 10});
Configurator.use('cli');

Configurator.build()
    .then(dungeonConfig => {
        //dungeonConfig is just a plain JS object. No fancy getters or setters.
        console.log("Number of Monsters: " + dungeonConfig.numberOfMonsters});
        generateDungeon(dungeonConfig);
    }).catch(err => {
        console.error("Error configuring dungeon: " + err.stack);
    });
```

This snippet will read a `--numberOfMonsters` command line option, and use a
default of `10`.

### Better Example

Now you might say

> Wouldn't it better to use an option parser like `yargs` for some thing like
> this?

And you would be right. (In fact, `nconfigurator` uses `yargs` internally). The
power of `nconfigurator` comes in when you want to, say, also take configuration
from an environment variable, or a file:

```javascript
Configurator.use('literal', {numberOfMonsters: 10});
Configurator.use('file', {file: 'config.json', skipMissing: true});
Configurator.use('env', {whitelist: ['numberOfMonsters', 'monsterStrength']});
Configurator.use('cli');
```

Boom. Command line arguments taking precedence over environment variables taking
precedence over a config file (which might not be there), taking precedence over
default values. In four lines of code.

### Best Example

That's nice and all, but where `nconfigurator` really shines (and the main
reason I wrote it) is extensibility. Say you want to package your dungeon
generator as a micro-service (because your DM wants to integrate it into his/her
RPG engine), and you would like to take your configuration from a central
server. This is simple with `nconfigurator`. First you define a provider:

```javascript
class DungeonProvider {

    constructor(server) {
        this.serverUrl = server;
    }

    // build takes in the current configuration, and returns a promise that
    // fulfills to the new one. This allows you to do what's shown below, where
    // we take a previously set config value and use it in this step. This also
    // means that you have merge the two config objects yourself. nconfigurator
    // provides an implementation based on lodash's merge that does sane things,
    // but it's entirely up to you.
    build(config) {
        return getConfigFromServer(config.serverUrl || this.serverUrl)
            .then(serverConfig => {
                return Configurator.utils.merge(config, serverConfig);
            });
    }
}
```

Next, register your provider with `nconfigurator`, and use it:

```javascript
Configurator.register('dungeon', DungeonProvider);
Configurator.use('dungeon', 'http://dungeon.com/get/config');
```

Alternatively, you can just use the provider directly:

```javascript
Configurator.use(new DungeonProvider('http://dungeon.com/get/config'));
```
# Documentation

`nconfigurator` comes with four built in providers:

### LiteralProvider

Registered under `literal`, this provider simply merges a JS object with the
current config:

```javascript
Configurator.use('literal', {numberOfMonsters: 10});
```

### FileProvider

Registered under `file`, this provider parses a JSON file and merges it with
the current config. If the file it's given is a direcotry, it will read all of
the files in that directory and merge them together. It either takes a path to
the file, or an options object that can have the following properties:

- `file`: The path to the file/directory to read
- `fromConfig`: Get the file path from this value of the already built config.
If both `file` and `fromConfig` are given, `fromConfig` is used
- `skipErrors`: Silently ignore any errors that occur parsing the JSON file.
- `skipMissing`: Silently ignore any missing files or config values.

```javascript
Configurator.use('file', {file: 'config.json', skipMissing: true});
```

### EnvProvider

Registered under `env`, this provider takes in environment variables, and adds
them to the current config. Custom name filtering and mapping is comming soon!

- `whitelist`: Only bring in environment variables that have these names
- `lowerCase`: If set to true, lowercase all of the environment variable names
- `regex`: Filter the allowed environment variables by matching their name to a
regular expression.

```javascript
Configurator.use('env', {whitelist: ['numberOfMonsters', 'monsterStrength']});
```

### CliProvider

Registered under `cli`, this provider parses the command line using `yargs`, and
merges the resulting object into the config. Any customizations can be made to
`yargs`, and the resulting object passed to the provider as a parameter (for
generating help strings, for instance

```javascript
Configurator.use('cli', require('yargs').usage('$0 --numberOfMonsters <num>'));
```
**Note:** The `yargs` object doesn't technically have to be passed as a parameter.
Changes made on the module will persist across files. However, passing it along
declares intent, so I encourage you to do so.

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