envariability v1.0.0

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:

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:

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:

Supported options