README.md

read-env

Convert environment variables into JSON object with parsed values.

Install

npm install --save read-env

Basic Example

Let's say you have some environment variables starting with prefix "EXAMPLE_" like below:

EXAMPLE_OBJECT_KEY= '{"prop": "value"}',
EXAMPLE_ARRAY_KEY= '[1,2,3, "string", {"prop": "value"}, 5.2]',
EXAMPLE_TRUE_KEY= 'true',
EXAMPLE_FALSE_KEY= 'false',
EXAMPLE_INT_KEY= '5',
EXAMPLE_FLOAT_KEY= '5.2',
EXAMPLE_STRING_KEY= 'example',

your-app.js

import readEnv from 'read-env';

const options = readEnv('EXAMPLE');
console.log(options);

Output:

{ 
  arrayKey: [ 1, 2, 3, 'string', { prop: 'value' }, 5.2 ],
  falseKey: false,
  floatKey: 5.2,
  intKey: 5,
  objectKey: { prop: 'value' },
  stringKey: 'example',
  trueKey: true 
}

Usage

readEnv(prefix = null, transformKey = 'camelcase')

You can pass a string prefix as first paremeter like below:

const options = readEnv('EXAMPLE');
// Output:
/**
{ 
  arrayKey: [ 1, 2, 3, 'string', { prop: 'value' }, 5.2 ],
  falseKey: false,
  floatKey: 5.2,
  intKey: 5,
  objectKey: { prop: 'value' },
  stringKey: 'example',
  trueKey: true 
}
*/

const optionsLower = readEnv('EXAMPLE', 'lowercase');
// Output:
/**
{ 
  array_key: [ 1, 2, 3, 'string', { prop: 'value' }, 5.2 ],
  false_key: false,
  float_key: 5.2,
  int_key: 5,
  object_key: { prop: 'value' },
  string_key: 'example',
  true_key: true 
}
*/

function ucfirst(string) {
    return string.charAt(0).toUpperCase() + string.slice(1).toLowerCase();
}
const optionsUcfirst = readEnv('EXAMPLE', ucfirst);
// Output:
/**
{ 
  Array_key: [ 1, 2, 3, 'string', { prop: 'value' }, 5.2 ],
  False_key: false,
  Float_key: 5.2,
  Int_key: 5,
  Object_key: { prop: 'value' },
  String_key: 'example',
  True_key: true 
}
*/

readEnv(config)

You can pass whole config object:

function ucfirst(string) {
    return string.charAt(0).toUpperCase() + string.slice(1).toLowerCase();
}

const options = readEnv({
  prefix: 'EXAMPLE',
  includePrefix: false,
  transformKey: ucfirst,
  parse: {
    array: false, //not gonna parse arrays
  }, //still gonna parse object, int, float and boolean
});

Config

Available Config Options:

• prefix (type: string, default: null): filters environment variables by prefix
• includePrefix (type: bool, default: false): set true if you want to keep prefix in property names.
• transformKey (type: null|string|function, default: 'camelcase'): transform environment variable name.
  1. null, doesn't transform the environment variable name.
  2. camelcase, transforms variable name to camelCase.
  3. lowercase, transforms variable name to lowercase.
  4. uppercase, transforms variable name to UPPERCASE.
  5. fn(varName), you can write your own transformer function (varName will be provided with prefix, if includePrefix is true)
• parse (type: bool|object, default: object):
  1. false: returns raw environment variable value
  2. {}: allows you to define which value types are going to be parsed.
     • object (type: bool, default: true): parse stringified object (value must be valid JSON input, see: JSON.parse).
     • array (type: bool, default: true): parse stringified array (value must be valid JSON input, see: JSON.parse).
     • int (type: bool, default: true): parse numbers into integer (value must be consist of only digits).
     • float (type: bool, default: true): parse numbers into float (value must be consist of only digits with decimal point).
     • bool (type: bool, default: true): parse if value into bolean if it equals to 'true' or 'false' .
• ignoreInvalidJSON (type: bool, default: true): if set to false, throws exception when value is not a valid JSON input (parse.object or parse.array options must be set to true).
• filter (type: null|function, default: null): filters environment variables (overrides prefix rule).
  1. null, don't filter varaibles.
  2. fn(envVarName, index), custom filter function (envVarName will be provided without any transformation).

Use Case Example

Recently, I used Nightmare for acceptance testing and had several environments which have different configurations.

Instead of writing a code like below:

import Nightmare from 'nightmare';

const nightmare = Nightmare({
  show: process.env.X_NIGHTMARE_SHOW || false,
  width:  process.env.X_NIGHTMARE_WIDTH || 1280,
  height:  process.env.X_NIGHTMARE_HEIGHT || 720,
  typeInterval:  process.env.X_NIGHTMARE_TYPE_INTERVAL || 50,
  //... other properties go forever
});

I wrote this, and nightmare is fully configurable with environment variables :)

import Nightmare from 'nightmare';
import readEnv from 'read-env';

const nightmareConfig = readEnv('X_NIGHTMARE');
const nightmare = Nightmare(nightmareConfig);

LICENCE

MIT (c) 2017 Mehmet Yatkı