envariability

Highly configurable environment based configuration library for Node.js

Features

• in-memory environment variable based configuration - all configuration values are loaded from the environment variables
• nested - the configuration keys/values are organized in a tree structure
• hierarchy driven - the config schema tree defines how the environment variables should look like
• schema driven - a lightweight config schema defines how a value must be processed
• validation - the configuration is validated for key presence checking
• documentation - can generate markdown documentation for your schema
• minimal dependencies, configurable, extensive and testable

How it works

The configuration definition needs to have elements which match this schema as leaves. Each configuration element will be flattened to an environment variable name by concatenating a pre-configured prefix with all the names of the configuration nodes from the root descending to the leaf in that order.

For example the following configuration:

const configDefinition = {
  "app": {
    "hostname": {},
    "port": {},
    "external": {
      "endpoint": {
        "host": {},
        "port": {}
      },
      "timeout": {}
    }
  }
}

with the MICRO_SERVICE prefix, will be flattened to the following environment variables:

MICRO_SERVICE_APP_HOSTNAME
MICRO_SERVICE_APP_PORT
MICRO_SERVICE_APP_EXTERNAL
MICRO_SERVICE_APP_EXTERNAL_ENDPOINT_HOST
MICRO_SERVICE_APP_EXTERNAL_ENDPOINT_PORT
MICRO_SERVICE_APP_EXTERNAL_TIMEOUT

then read and processed.

If the environment variable is defined, it will override the default specified in the configuration definition.

How to use

const environmentConfiguration = require('envariability');
const config = environmentConfiguration(
  // Application configuration definition
  {
      "app": {
        "endpoint": {
          "host": {
            "doc": "The hostname",
            "type": "string",
            "required": true
          },
          "port": {
            "doc": "The port",
            "type": "integer",
            "required": true
          },
          "protocol": {
            "doc": "The protocol",
            "type": "string",
            "default": "https",
            "required": true
          }
        }
      }
  },
  // Environment configuration options
  {
    "environmentVariablePrefix": "MY"
  });

// MY_APP_ENDPOINT_HOST=localhost
// MY_APP_ENDPOINT_PORT=443
// If the above environment variables are set,

assert.deepEqual(
  config,
  {
  "app": {
    "endpoint": {
      "host": "localhost",
      "port": 443,
      "protocol": "https"
    }
  }
});

assert.ok(Object.isFrozen(config))

Supported types and their default transformations

Depending on the type specified in the configuration node, the value from the environment variable is processed as following:

| Type | Transformation | |---------|---------------------------------------------------------------| | boolean | Transformed to uppercase and compared against "TRUE" | | integer | Parsed as an integer | | array | Split by the environmentVariableValueArraySeparator option | | string | none | | other | Must be provided by the user |

Custom transformations

If for example a configuration element needs some basic processing prior to being added to the actual configuration, a custom value transformation can be supplied in the config schema.

Let's say there's a config url which may or may not have the protocol. To go around that, the following configuration element processes the value directly from the environment variable:

const definition = { 
  "url": {
    "doc": "The url where requests go",
    "type": "other",
    "default": "http://some.url:8080",
    "required": true,
    "transform": (value) => value.match(/^http[s]?:\/\//) ? value : `http://${value}`
  }
}

this will ensure that the final config will have the right values.

Additionally, the transformation is always called with a reference to envariability's configuration as a parameter. So you can also do something like this:

const config = environmentConfiguration(
  // Application configuration definition
  {
    "app": {
      "endpoint": {
        "url": {
          "doc": "The url where requests go",
          "type": "other",
          "default": "http://some.url:8080",
          "required": true,
          "transform": (value, configOptions) => value.match(/^http[s]?:\/\//) ? value : `${configOptions.protocolForUrls}://${value}`
          }
        }
      }
  },
  // Environment configuration options
  {
    "environmentVariablePrefix": "MY",
    "protocolForUrls": "https"
  });

and reuse the same configuration definition across configuration instances.

Documenting your configuration automatically

envariability also supports generating documentation for the configuration definition in the form of a markdown table:

const envariabilityDoc = require('envariability').doc;

const documentation = envariabilityDoc({
    "app": {
      "endpoint": {
        "url": {
          "doc": "The url where requests go",
          "type": "other",
          "default": "http://some.url:8080",
          "required": true,
          "transform": (value, configOptions) => value.match(/^http[s]?:\/\//) ? value : `${configOptions.protocolForUrls}://${value}`
        },
        "count": {
          "doc": "How many requests should be made",
          "type": "integer",
          "default": 100,
          "required": true
        }
      }
    }
  },
  {
    'environmentVariablePrefix': 'MY',
    'environmentVariables': {},
  });

will produce the markup for the following table:

| env | doc | type | default | required | transform | | --- | --- | --- | --- | --- | --- | | MY_APP_ENDPOINT_URL | The url where requests go | other | http://some.url:8080 | true | (value, configOptions) => value.match(/^http[s]?:///) ? value : ${configOptions.protocolForUrls}://${value} | | MY_APP_ENDPOINT_COUNT | How many requests should be made | integer | 100 | true | --- |

The generator supports custom columns via the docColumnMapping property of the main envariability config object. The property is an array of arrays representing a mapping between the property names in the config element schema and a custom name. The order of the column definitions will be reflected in the resulting table.

For example:

const envariabilityDoc = require('envariability').doc;

const documentation = envariabilityDoc({
    "app": {
      "endpoint": {
        "url": {
          "doc": "The url where requests go",
          "type": "other",
          "default": "http://some.url:8080",
          "required": true,
          "transform": (value, configOptions) => value.match(/^http[s]?:\/\//) ? value : `${configOptions.protocolForUrls}://${value}`
        },
        "count": {
          "doc": "How many requests should be made",
          "type": "integer",
          "default": 100,
          "required": true
        }
      }
    }
  },
  {
    'environmentVariablePrefix': 'MY',
    'environmentVariables': {},
    'docColumnMapping': [
      ['doc', 'What'],
      ['required', 'Must be specified?'],
      ['type', 'Kind'],
      ['env', 'Environment variable'],
    ],
  });

will produce the markup for the following table:

| What | Must be specified? | Kind | Environment variable | | --- | --- | --- | --- | | The url where requests go | true | other | MY_APP_ENDPOINT_URL | | How many requests should be made | true | integer | MY_APP_ENDPOINT_COUNT |

Supported options

| Option | Default | Description | |--------------------------------------------|-------------------------------------|-------------------------| | environmentVariablePrefix | "" | The prefix for the environment variable names to build and read, usually an abbreviation of the service name. For example if set to MYSERVICE, environment variable names would be MYSERVICE_LOGDIR, MYSERVICE_PIDFILE, etc.. | | environmentVariableWordSeparator | "_" | The separator for the environment variable names to build and read. When the environment variable names are flattened based on the config hierarchy, this is the separator used to concatenate the config names along the way.| | environmentVariableTransform | (word) => word.toUpperCase() | A function to be used for processing the configuration name to convert to the environment variable name. By default it will be turned to all uppercase. For example app : { config : { port }} turns to APP_CONFIG_PORT | environmentVariableValueArraySeparator | "%" | For the array configuration element type, this is the separator used to split the string value contained in the environment variable | | immutable | true | True to return a deep immutable object as the resulting configuration, false otherwise. | | environmentVariables | process.env | The environment variable object read in order to populate the configuration. This is mainly to be able to inject the dependency on process.env while writing unit tests | | docColumnMapping | - | An 2D array representing the custom column names to be used for generating the markdown documentation for the configuration schema |