brewstand v1.0.6

Brewstand - Configuration overridden with Environment Variables

Installation

$ yarn add brewstand
-- or --
$ npm install brewstand

Usage

Create a Configuration object to load your configuration JSON file into your configuration interface. By default, it loads config.json in the current working directory.

class Configuration<ConfigurationObjectType>(path: string);

Then call Configuration#getConfig() to obtain your configuration object.

Example

Loading a simple configuration

// in index.ts
interface Config {
    host: string;
    port: number;
}

const config = new Configuration<Config>("./config.json").getConfig();

console.log(config.host);
console.log(config.port);

/* in config.json */
{
    "host": "localhost",
    "port": 1234
}

The type of configuration entries are converted when loading the JSON file and reading environment variables. See Type Conversion for further details.

Configuration could be overridden by environment variables. This is particularly useful when your deployment configuration differs with your testing configuration.

$ node index.js
localhost
1234
$ HOST="app" PORT="50002" node index.js
app
50002

Loading a nested configuration

It can handle nested configuration as well:

interface PlainTextCredential {
    username: string;
    password: string;
}

interface RedisConfig {
    host: string;
    port: number;
}

interface SqlConfig {
    host: string;
    port: number;
    cred: PlainTextCredential;
    database: string;
}

interface Config {
    redis: RedisConfig;
    sql: SqlConfig;
}

const config = new Configuration<Config>().getConfig();

console.log(config.sql.cred.username);

Use underscores (_) or dots (.) to address sub-keys:

$ SQL.CRED.USERNAME="testUser" node index.js
testUser
$ SQL_CRED_USERNAME="productionUser" node index.js
productionUser

Type Conversion

Number

If the key is a number, the value will be converted to a number.

If the value could not be converted to a number, the key will not be overridden.

Boolean

If the key is a boolean, the value will be converted to a boolean following the rules below:

• Empty values are ignored
• Anything other than true is regarded as false. yes, 1 and other "should be true" values are all regarded as false.

Object / Array

If the key is an object or an array, the value will be parsed as a JSON string.

If the parsing failed, the key will not be overridden.

Caveats

Use UPPER CASE LETTERS for environment variable name

Lower case variables will be ignored.

Must provide a configuration file with correct type

The override part requires the variable to be set and correctly typed. Setting an undefined value will raise an error. This is due to the limitation of JavaScript (cannot preserve type information). Further version may implement specifying the type of an absent key.