npm package: @strata-js/util-env-config
Description: A simple configuration manager that supports environment based overrides.
Author: Christopher S. Case
Latest version: 1.0.0

# Environment Config

EnvConfig is a configuration manager with support for many scenarios of configuration. It was designed with the idea 
of being able to be used for development (or with file-based configuration) very easily, while also supporting more 
advanced configuration management at the same time.

This project is under the Strata.js family, because this type of configuration is most commonly needed by services, 
and it is included as a part of `@stratajs/strata`. However, sometimes, there are projects that don't use Strata, 
but might need configuration to be handled in the same way. (A good example of this is [Strata Service Tools][sst].) 
It's for these projects that this exists.

[sst]: https://gitlab.com/stratajs/strata-service-tools

## Installation

This middleware package is published via GitLab's npm repository. It is not (currently) available on the public npm 
repo. It is, however, hosted in the same way as Strata.js itself, and since Strata.js is a prerequisite for this 
package, you should already be good to go. (If not, please see the 
[Installation](https://gitlab.com/stratajs/strata#installation) section here.)

Simply do:
```bash
// npm
$ npm add @stratajs/env-config

// yarn
$ yarn add @stratajs/env-config

```

## Usage

### Loading configuration

There are two methods for loading a configuration into the configuration manager: `setConfig` and `parseConfig`. 
While the names may be similar, they do two very different things. Both are exposed to cover all possible use cases.

####  `setConfig(config : Record<string, unknown>) : void`

The `setConfig` function is as simple as it gets. It takes a configuration, and it sets it. There is nothing special 
about the configuration, except that it conform to the type `Record<string, unknown>`.

####  `parseConfig(config : Record<string, unknown>) : void`

The `parseConfig` function is where the magic happens. This function supports several very handy shortcuts, which 
require we parse the configuration file in order to build the correct configuration. Once that config is built, we 
call `setConfig` ourselves.

##### Environment-based configurations

The first thing `parseConfig` looks for, is a configuration object that has an `environments` key. (This is not 
required, but it is one of the two major reasons to use `parseConfig`.) What it then does is to look for the 
`ENVIRONMENT` or `NODE_ENVIRONMENT` variable, and then apply any configuration found under `environments[ENVIRONMENT]`.

Let's look at an example. Given the following configuration:

```typescript
// config.ts
export default {
    http: {
        secure: false,
        port: 12345
    },
    
    environments: {
        test: {
            http: {
                secure: true
            }
        },
        production: {
            http: {
                secure: true,
                port: 443
            }
        }
    }
}
```

Then the following will be true:

```typescript
import config from './config.ts';
import configMan from '@stratajs/env-config'

//---------------------------------------

// Set our environment to 'local'
process.env.ENVIRONMENT = 'local';
configMan.parseConfig(config);

// { secure: false, port: 12345 }
console.log(configMan.get('http'));

//---------------------------------------

// Set our environment to 'test'
process.env.ENVIRONMENT = 'test';
configMan.parseConfig(config);

// { secure: true, port: 12345 }
console.log(configMan.get('http'));

//---------------------------------------

// Set our environment to 'production'
process.env.ENVIRONMENT = 'production';
configMan.parseConfig(config);

// { secure: true, port: 443 }
console.log(configMan.get('http'));
```

This allows one configuration file to contain the details about multiple environments, while reusing most of the 
default configuration. If an environment isn't specified, the default configuration is used.

##### Environment Variable config overriding

The other feature of `parseConfig` is support for overriding sections of config with environment variables. It looks 
for any environment variables that start with `CONFIG.`, and then replaces the values of the config at that location 
with the value of the environment variable. In order to handle conversions from the traditional UPPERCASE of 
environment variables, we are passing this to lodash's [camelCase][] function. This should be sufficient for most 
use cases.

**WARNING: Due to the nature of environment variables, the type for any overridden property is `string`.**

Let's look at an example. Give the configuration: 

```typescript
// config.ts
export default {
    http: {
        secure: false,
        port: 12345
    },
    
    environments: {
        test: {
            http: {
                secure: true
            }
        },
        production: {
            http: {
                secure: true,
                port: 443
            }
        }
    }
}
```

Then the following will be true:

```typescript
import config from './config.ts';
import configMan from '@stratajs/env-config'

//---------------------------------------

// Override our default config
process.env.CONFIG.HTTP.PORT = '4545';
configMan.parseConfig(config);

// { secure: false, port: 4545 }
console.log(configMan.get('http'));

//---------------------------------------

// We support mixing both types of configuration
process.env.ENVIRONMENT = 'test';
process.env.CONFIG.HTTP.PORT = '4545';
configMan.parseConfig(config);

// { secure: true, port: 4545 }
console.log(configMan.get('http'));

//---------------------------------------

// The environment variables take precedence over the environment configurations.
process.env.ENVIRONMENT = 'production';
process.env.CONFIG.HTTP.PORT = '4545';
configMan.parseConfig(config);

// { secure: true, port: 4545 }
console.log(configMan.get('http'));
```

#### Loading from an external source

Because of how the configuration manager is written, it's trivial to load the configuration from an external source. 
Here are a few examples:

```typescript
import axios from 'axios';
import configUtil from '@stratajs/env-config'

//---------------------------------------

// Local config file
configUtil.parseConfig(await import('./config.ts'));

// HTTP call
const { data } = await $http.get('https://example.com/config/production.json');
configUtil.setConfig(JSON.parse(data));

```

[camelCase]: https://lodash.com/docs/#camelCase