npm package: @lafferty-lounge/config
Description: A simple configuration provider
Author: Craig Lafferty craigplafferty@gmail.com
Latest version: 0.1.0

# @lafferty-lounge/config

The lafferty-lounge config package is a simple configuration management package.
It handles reading from a file, reading from stdin, environment variables, and
command line arguments. It parses everything as yaml so you can use JSON if that's
your style.

# Usage

__test.js__

```js
const Config = require('@lafferty-lounge/config');
const config = new Config('NODE_CONFIG', [
  ['option-flag,o', 'default-value'], // list the arguments that you want to parse
  ['other-arg']
]);
config.fetch()
  .then(parsedConfig=>{
    console.log(parsedConfig); // { verbosity: null }
  });
```
__config.yaml__

```yaml
option-flag: bar
```

__CLI__

```bash
echo '{"option-flag": "foo"}' | node test.js -c -         # {'option-flag': 'foo', ...} read from stdin
echo '{"option-flag": "foo"}' | node test.js --config=-

node test.js -c config.yaml                               # {'option-flag': 'bar', ...} read from file
node test.js --config=config.yaml

node test.js -c '{"option-flag": "inline"}'               # {'option-flag': 'inline', ...} read from argv
node test.js --config='{"option-flag": "inline"}'
```

## Reserved flags

  * `--config`
  * `-c`

Both `-c` and `--config` are used to tell config where to load a yaml "file" from. (stdin, inline, file)

## Type of input

The config module takes several type of inputs for configuration options.

When you create a config instance you'll pass it a prefix to use for environment
variables as well as an array of arguments to look for and parse.

```js
const Config = require('@lafferty-lounge/config');
const config = new Config('NODE_CONFIG', [
  ['option-flag,o', 'default-value'], // list the arguments that you want to parse
  ['other-arg']
]);
config.fetch()
  .then(parsedConfig=>{
    console.log(parsedConfig); // { 'option-flag': null }
  });
```


In the previous `test.js` file you'll notice `'option-flag,o'`. That is the option
that the config module will attempt to find in your various configurations.

The `option-flag` key is what config will search for. The `c` after the comma is
the shorthand flag to look for on the command line.

The second item in the `option-flag` array is the default value to use if no options
are found.

`NODE_CONFIG` will be prefixed to environment variables when parsing options.
I.e. for `option-flag` we'll look for the environment variable `NODE_CONFIG_CLI_ARG`.

### Command Line Arguments

Command line arguments are will be referenced by the same name (dashes included)
that you use in your options array. I.e. we'll look for `node test.js --option-flag`
in the following:

```js
const config = new Config('NODE_CONFIG', [
  ['option-flag,o', 'default-value']
]);
```

### Shorthand Command Line Arguments

Shorthand command line arguments are optional and are paired with a long hand
flag. I.e. we'll end up with  `{ 'option-flag': 'bar' }` when we run  `node test.js -o bar`

__test.js__

```js
const config = new Config('NODE_CONFIG', [
  ['option-flag,o', 'default-value']
]);
```

### Environment Variables

When you create a config instance you will pass it a prefix as the first
argument. This prefix will be prepended to your options when searching for
environment variables.

I.e. We'll look for `NODE_CONFIG_OPTION_FLAG` using the folling configuration:

__test.js__

```js
const config = new Config('NODE_CONFIG', [
  ['option-flag,o', 'default-value']
]);
```

### Config Files `(--config, -c)`

Config will parse config files as yaml so you can pass yaml or JSON.
Pass the `-c` or `--config` arguments when running your application to tell
config that you want to load a file.

#### available `--config` options

  * `-`
  * `/filepath`
  * `{"inline": "json"}`

### Default Values

You can define default values for config options if none of the available places
to search have a value defined for them.

We'll end up with `{ 'option-flag': 'default-value' }` if we don't provide any
configuration options to the application.

__test.js__

```js
const config = new Config('NODE_CONFIG', [
  ['option-flag,o', 'default-value']
]);
```


## Precedence

Values take priority from top to bottom in the following order:

  1. command line arguments
  1. command line shorthand
  1. environment variables
  1. config file
  1. defaults

Example:

__test.js__

```js
const Config = require('@lafferty-lounge/config');
const config = new Config('CONFIG', [
  ['test-key']
]);
config.fetch()
  .then(parsedConfig=>{
    console.log(parsedConfig);
  });
```

```bash
export CONFIG_TEST_KEY=foo
node test.js                  # { 'test-key': 'foo' }
node test.js --test-key bar   # { 'test-key': 'bar' } command line argument takes precedence here
```