get-configuration-from-environment v1.0.1

get-configuration-from-environment

get-configuration-from-environment gets an application configuration from environment variables.

Status

Category	Status
Version
Dependencies
Dev dependencies
Build
License

Installation

$ npm install get-configuration-from-environment

Quick Start

First you need to integrate get-configuration-from-environment into your application:

const {
  fromEnvironmentVariables
} = require('get-configuration-from-environment');

If you use TypeScript, use the following code instead:

import {
  ConfigurationDefinition,
  fromEnvironmentVariables
} from 'get-configuration-from-environment';

To get your application's configuration from the environment, you first have to define an interface for your configuration, and write an appropriate ConfigurationDefinition:

interface Configuration {
  foo: string;
  bar: number;
}

const configurationDefinition: ConfigurationDefinition<Configuration> = {
  foo: {
    environmentVariable: 'FOO',
    defaultValue: 'foo-default',
    schema: { type: 'string' }
  },
  bar: {
    environmentVariable: 'BAR',
    defaultValue: 5,
    schema: { type: 'number' }
  }
};

Then you can use this configuration definition to retrieve the configuration from the environment:

const configuration =
  await fromEnvironmentVariables({ configurationDefinition });

// Either the value from the environment variable, or 'foo-default'.
console.log(configuration.foo);

The resulting configuration object will contain the JSON-parsed contents of the environment variables or the default values that are defined in the configuration definition.

Serializing a configuration

In some cases you want to set environment variables rather than get them. For these cases the toEnvironmentVariables function can be used to serialize a configuration object to environment-variable-compatible values:

import {
  toEnvironmentVariables
} from 'get-configuration-from-environment';

const environmentVariables =
  toEnvironmentVariables({ configuration, configurationDefinition });

The constant environmentVariables now contains a Record<string, string> with JSON-stringified values from your configuration. You can e.g. pass these to nodeenv or further stringify them to create a docker-compose manifest or something along these lines.

Censoring values in a configuration

If you want to log the loaded configuration in your application, but do not want to leak secrets into your log storage, you can mark fields in your ConfigurationDefinition as private and use censorConfiguration:

import {
  censorConfiguration,
  ConfigurationDefinition,
  fromEnvironmentVariables
} from 'get-configuration-from-environment';

interface Configuration {
  foo: string;
}

const configurationDefinition: ConfigurationDefinition<Configuration> = {
  foo: {
    environmentVariable: 'FOO',
    defaultValue: 'foo-default',
    schema: { type: 'string' },
    isPrivate: true
  }
};

const configuration = await fromEnvironmentVariables({ configurationDefinition });
const censoredConfiguration = censorConfiguration({ configuration, configurationDefinition });

console.log({ censoredConfiguration });

You'll notice that the value of censoredConfiguration.foo is no longer foo-default, but rather ****.

Retrieving only default values

If you want to build a configuration object solely from the configured defaults and ignore the actual environment, you can use getDefaultConfiguration:

import {
  ConfigurationDefinition,
  getDefaultConfiguration
} from 'get-configuration-from-environment';

interface Configuration {
  foo: string;
}

const configurationDefinition: ConfigurationDefinition<Configuration> = {
  foo: {
    environmentVariable: 'FOO',
    defaultValue: 'foo-default',
    schema: { type: 'string' },
    isPrivate: true
  }
};

const defaultConfiguration =
  await getDefaultConfiguration({ configurationDefinition });

The constant defaultConfiguration now contains a configuration object exclusively made from the default values defined before. The environment is never inspected.

Running quality assurance

To run quality assurance for this module use roboter:

$ npx roboter