@hugojosefson/env-config

Reads env variables into a config object.

Usage

Default

Simplest case, using defaults for everything. Uses process.env as its source.

import envConfig from '@hugojosefson/env-config'

const { DB_PORT, DB_USERNAME, DB_PASSWORD } = envConfig()

Using options, for example to CamelCase key names

import envConfig from '@hugojosefson/env-config'
import ra from 'ramda-adjunct'

const transformer = ra.renameKeysWith(camelcase)
const { dbPort, dbUsername, dbPassword } = envConfig({ transformer })

For more options, see API below.

Installation

yarn add @hugojosefson/env-config

  # or

npm install --save @hugojosefson/env-config

Node.js version

• Node.js >=8.0.0 for using this package in your app.
• Node.js >=13.7.0 for running the developer tools to make changes to this repository.

Note: If you use Node.js <8.5.0, you probably need to const envConfig = require('@hugojosefson/env-config') instead of import.

Features

Reads files from _FILE vars

If any environment variable is suffixed with _FILE, it reads its value as a file path, and replaces it with the file's contents. Also removes the _FILE suffix.

For example, with an environment like this:

DB_PORT="5432"
DB_USERNAME="my_app"
DB_PASSWORD_FILE="/run/secrets/MY_APP_DB_PASSWORD"

...and the file /run/secrets/MY_APP_DB_PASSWORD containing:

mNntp6J76p6pkK2tTgw2bEvC

...you will get this JS object as output:

{
  DB_PORT: 5432,
  DB_USERNAME: 'my_app',
  DB_PASSWORD: 'mNntp6J76p6pkK2tTgw2bEvC'
}

Parses any JSON

If any environment variable can be parsed as JSON, it is. If not, it's still a string.

For example, number strings are converted to numbers, "true" and "false" are converted to the boolean values true and false, respectively.

It also supports large JSON objects and JSON arrays.

For example, with this environment:

SERVER='{"http":{"enable":true,"port":3000},"tls":{"enable":false}}'
TEXTS='{"greetings":["Hi!","Hello.","Welcome!"],"goodbyes":["So long","farewell","auf Wiedersehen","good night"]}'

...you will get this resulting JS object as output:

{
  SERVER: {
    http: {
      enable: true,
      port: 3000,
    },
    tls: {
      enable: false,
    },
  },
  TEXTS: {
    greetings: ['Hi!', 'Hello.', 'Welcome!'],
    goodbyes: ['So long', 'farewell', 'auf Wiedersehen', 'good night'],
  },
}

Parses base64 and hex

If a string is prefixed with base64: or hex:, the rest of the string is automatically parsed as such, into a new string. That string may in turn be similarly encoded, or a JSON string.

API

envConfig

Parses the source into an object.

Parameters

• source Source object. Optional. Default: process.env.
• keys Array of keys to use. Optional. Default: All keys in source.
• decoders Array of decoder definitions to attempt to use for decoding each value. Each decoder definition is an object with a property prefix whose value is a string, or a property test whose value is a function to test whether to use this decoder to process the value. Additionally, each decoder definition has a property decode which is a function taking the original value, and returning the decoded value. Alternatively decodeWithoutPrefix can be defined, which is called with the original value, just having its prefix chopped off first. Optional. Default: defaultDecoders.
• transformers Array of functions for making any changes to the configuration object afterwards. Will be run in order of appearance. Optional.
• transformer Alternatively for convenience, a single function for making any change to the configuration object afterwards. Takes the complete config object as argument, and must return the new/altered config object. Optional.
• redactFileContents Whether to redact contents from files. Optional. Default: false.
• readFile Synchronous function to read contents from a file path. Optional. Default: '[redacted]' if redactFileContents === true, otherwise path => readFileSync(path, { encoding: 'utf8' }).
• failOnMissingFile Whether to fail if a file can not be read. If true, will throw an error if the path to a _FILE can not be read, If false, will leave the _FILE key as it was. Optional. Default: false.

Returns any An object where the values are parsed according to Features.

defaultDecoders

Default decoders, decoding strings prefixed with base64: and hex: into strings, and base64binary: and hexbinary into Buffers.