@arriva/environment

Overview

Node Library for fetching environment variables from:

• Local environment.
• AWS SSM Parameter store.
• local .env file.

Configuration

Configuration is made throught a configuration object as parameter or as envc.json configuration file. If no configuration parameter is provided and no config file is found, it will be handled as with errors.

All string values, except for strings in import section, can have environment variables set in format ${VARIABLE_NAME}. It is not possible to escape this format. If variable does not exists, it is ignored or throws an error depending on error handling settings, see section Error Handling.

The parameters is resolved with local environment before string variables is replaced. String variables can contain any variable that exists in local environment.

Configuration object format

Parameter	Type	Usage
aws	Object	Optional. Fetch AWS parameter store data
→ path	String	Hierarchy path. Must be preceded by a / character if hierarchy is used. Example, /path/to/parameter/root. If value is empty string, then hierarchy parameters will not be used and then any imported parameter must be specified in import list. String can contain environment variable replace parameters ( ${PARAM_NAME} ).
→ region	String	Optional. AWS region parameter. Is needed if not set by aws context needs to be overridden.
import	object	Maps imported parameters to object names. Format is "mappedParameterName":"awsParameterName". See Parameter mapping section for details.
rejectOnErrors	Boolean	Reject with error data when fail to load configuration. Default false

Parameter mapping

If we want to map AWS parameter database_endpoint to result object member endpoint, then use "endpoint":"database_endpoint".

Example:

{
    "aws": {
        "path": "/${SOME}/${SSM_PATH}/to/environment/data",
        "region": "eu-north-1"
    },
    "import": {
        "propertyName":"ENVIRONMENT_PARAMETER_1",
        "property.name":"ENVIRONMENT_PARAMETER_2",
    }
}

Punctuation mark can be used for dividing result object into hierarcical mapping. Example:

{
    "import": {
        "reader.endpoint": "reader_endpoint",
        "reader.username": "reader_username",
        "writer.endpoint": "writer_endpoint",
        "writer.username": "writer_username",
    }
}

will end up in result object:

    {
        "reader": {
            "endpoint": "somevalue 1",
            "username": "somevalue 2"
        },
        "reader": {
            "endpoint": "somevalue 3",
            "username": "somevalue 4"
        }
    }

Configuration file envc.json

Program search for a envc.json file in program root directory. Structure are basically the same as for configuration object.

Multiple configuration sources

Configuration object is resolved in following order and stops when found one:

• Configuration object on init() method
• Configuration file

Configuration data is combined and overwritten in following order, top to bottom:

• Environment variables
• Parameter store object
• .env file

If a parameter exists in both parameter store and in local environment, the value in local environment will be used.

Error handling

If parameter rejectOnErrors is set to true, all errors will be thrown. If set to false, then errors will be ignored.

Examples

Javascript ES6

import Environment from '@arriva/environment'

const environment = new Environment()

const options = {
    aws: {
        path: '/${SOME}/parameterstore/${PATH}',
        region: '${AWS_REGION}',
    },
    map: {
        variablename1: 'ENVIRONMENT_VARIABLE_NAME_1',
        variablename2: 'ENVIRONMENT_VARIABLE_NAME_2',
        'variable.name.3': 'ENVIRONMENT_VARIABLE_NAME_3'
        'variable.name.4': 'ENVIRONMENT_VARIABLE_NAME_4'
    },
}

// Promises
environment
    .init(options)
    .then((env) => {
        console.log(env)
    })
    .catch((err: any) => {
        console.error(err)
    })

// Inside async function
let env = await environment.init(options)

Changelog

Version	Date	Changes
1.0.0	2019-11-21	Initial release
1.0.1	2019-11-21	Add readme.md instructions
1.0.2	2019-11-24	New error handling. New structure for AWS parameters. Handle string replacement escaping. Handle errors.

Licensing

This script is free for use for everyone. Content and functionality can be changed without notice. Breaking changes should indicate by bump major version. This script is published to encourage free software development. Please visit development page for more info.