env-to-object

Environment Variables

Maps environment variables to a configuration object.

Installation

$ npm install env-to-object

Usage

var env = require( 'env-to-object' );

env( map[, options] )

Maps environment variables to a configuration object.

var map = {
    'NODE_ENV': {
        'keypath': 'env',
        'type': 'string'
    },
    'PORT': {
        'keypath': 'server.port',
        'type': 'number'
    },
    'SSL': {
        'keypath': 'server.ssl',
        'type': 'boolean'
    },
    'LOGLEVEL': {
        'keypath': 'logger.level',
        'type': 'string'
    }
};
 
var out = env( map );
/*
    {
        'env': <string>,
        'server': {
            'port': <number>,
            'ssl': <boolean>
        },
        'logger': {
            'level': <string>
        }
    }
*/

An environment variable mapping must include a keypath, which is a dot-delimited object path. By default, this module parses an environment variable value as a string. The following types are supported:

• string
• number
• integer
• boolean
• object
• date
• regexp

The function accepts the following options:

• parsers: an object containing environment variable parsers. Each key should correspond to a defined type, and each value should be a function which accepts an environment variable value and any associated options.

  var map = {
      'CUSTOM_TYPE': {
          'keypath': 'custom',
          'type': 'custom',
          ... // => options
      }
  };
   
  var parsers = {
      'custom': custom
  };
   
  function custom( str, opts ) {
      var v = parseInt( str, 10 );
      if ( v !== v ) {
          return new TypeError( 'invalid value. Value must be an integer. Value: `' + str + '`.' );
      }
      return v * 6;
  }
   
  process.env[ 'CUSTOM_TYPE' ] = '5';
   
  var out = env( map, parsers );
  /*
      {
          'custom': 30
      }
  */

---

Types

string

(default) Coerce an environment variable value to a string.

var map = {
    'STR': {
        'keypath': 'str',
        'type': 'string'
    }
};
 
process.env[ 'STR' ] = 'beep';
var out = env( map );
/*
    {
        'str': 'beep'
    }
*/
 
process.env[ 'STR' ] = '1234';
var out = env( map );
/*
    {
        'str': '1234'
    }
*/

===

number

Coerce an environment variable value to a number.

var map = {
    'NUM': {
        'keypath': 'num',
        'type': 'number'
    }
};
 
process.env[ 'NUM' ] = '3.14';
var out = env( map );
/*
    {
        'num': 3.14
    }
*/
 
process.env[ 'NUM' ] = 'bop';
var out = env( map );
// => throws

===

integer

Coerce an environment variable value to an integer.

var map = {
    'INT': {
        'keypath': 'int',
        'type': 'integer'
    }
};
 
process.env[ 'INT' ] = '2';
var out = env( map );
/*
    {
        'int': 2
    }
*/
 
process.env[ 'INT' ] = 'beep';
var out = env( map );
// => throws

The integer type has the following options:

• radix: an integer on the interval [2,36].

  var map = {
      'INT': {
          'keypath': 'int',
          'type': 'integer',
          'radix': 2
      }
  };
   
  process.env[ 'INT' ] = '1';
  var out = env( map );
  /*
      {
          'int': 1
      }
  */
   
  process.env[ 'INT' ] = '2';
  var out = env( map );
  // => throws

===

boolean

Coerce an environment variable value to a boolean. The boolean type supports the following options:

• strict: boolean indicating whether to accept only 'true' and 'false' as acceptable boolean strings. Default: false.

In non-strict mode, the following values are supported:

• TRUE, True, true, T, t
• FALSE, False, false, F, f

var map = {
    'BOOL': {
        'keypath': 'bool',
        'type': 'boolean'
    }
};
 
process.env[ 'BOOL' ] = 'TRUE';
var out = env( map );
/*
    {
        'bool': true
    }
*/
 
process.env[ 'BOOL' ] = 'beep';
var out = env( map );
// => throws

To restrict the set of allowed values, set the strict option to true.

var map = {
    'BOOL': {
        'keypath': 'bool',
        'type': 'boolean',
        'strict': true
    }
};
 
process.env[ 'BOOL' ] = 'false';
var out = env( map );
/*
    {
        'bool': false
    }
*/
 
process.env[ 'BOOL' ] = 'TRUE';
var out = env( map );
// => throws

===

object

Parse an environment variable value as a JSON object. Note that a value must be valid JSON.

var map = {
    'OBJ': {
        'keypath': 'obj',
        'type': 'object'
    }
};
 
process.env[ 'OBJ' ] = '{"beep":"boop"}';
var out = env( map );
/*
    {
        'obj': {
            'beep': 'boop'
        }
    }
*/
 
process.env[ 'OBJ' ] = '[1,2,3,"4",null]';
var out = env( map );
/*
    {
        'obj': [ 1, 2, 3, '4', null ]
    }
*/
 
process.env[ 'OBJ' ] = '{"beep:"boop"}';
var out = env( map );
// => throws

===

date

Coerce an environment variable to a Date object.

var map = {
    'DATE': {
        'keypath': 'date',
        'type': 'date'
    }
};
 
process.env[ 'DATE' ] = '2015-10-17';
var out = env( map );
/*
    {
        'date': <Date>
    }
*/
 
process.env[ 'DATE' ] = 'beep';
var out = env( map );
// => throws

===

regexp

Parse an environment variable as a RegExp.

var map = {
    'REGEXP': {
        'keypath': 're',
        'type': 'regexp'
    }
};
 
process.env[ 'RE' ] = '/\\w+/';
var out = env( map );
/*
    {
        're': /\w+/
    }
*/
 
process.env[ 'RE' ] = 'beep';
var out = env( map );
// => throws

---

Notes

• If an environment variable does not exist, the corresponding configuration keypath will not exist in the output object.

  var map = {
      'UNSET_ENV_VAR': {
          'keypath': 'a.b.c'
      }
  };
   
  var out = env( map );
  // returns {}

---

Examples

var env = require( 'env-to-object' );
 
var map = {
    'DEFAULT': {
        'keypath': 'default'
    },
    'STR': {
        'keypath': 'str',
        'type': 'string'
    },
    'NUM': {
        'keypath': 'num',
        'type': 'number'
    },
    'BOOL': {
        'keypath': 'bool',
        'type': 'boolean',
        'strict': true
    },
    'ARR': {
        'keypath': 'arr',
        'type': 'object'
    },
    'NESTED': {
        'keypath': 'a.b.c.d',
        'type': 'object'
    },
    "DATE": {
        "keypath": "date",
        "type": "date"
    },
    "REGEX": {
        "keypath": "re",
        "type": "regexp"
    },
    "INT": {
        "keypath": "int",
        "type": "integer"
    }
};
 
process.env[ 'DEFAULT' ] = 'beep';
process.env[ 'STR' ] = 'boop';
process.env[ 'NUM' ] = '1234.5';
process.env[ 'BOOL' ] = 'true';
process.env[ 'ARR' ] = '[1,2,3,4]';
process.env[ 'NESTED' ] = '{"hello":"world"}';
process.env[ 'DATE' ] = '2015-10-18T07:00:01.000Z';
process.env[ 'REGEX'] = '/\\w+/';
process.env[ 'INT' ] = '1234';
 
var out = env( map );
/*
    {
        'default': 'beep',
        'str': 'boop',
        'num': 1234.5,
        'bool': true,
        'arr': [1,2,3,4],
        'a': {
            'b': {
                'c': {
                    'd': {
                        'hello': 'world'
                    }
                }
            }
        },
        'date': <date>,
        're': /\w+/,
        'int': 1234
    }
*/

To run the example code from the top-level application directory,

$ node ./examples/index.js

or, alternatively,

$ DEFAULT=boop STR=beep NUM='5432.1' BOOL='false' ARR='[4,3,2,1]' NESTED='{"world":"hello"}' DATE='2015-10-19T06:59:59.000Z' REGEX='/\\.+/' node ./examples/index.js

---

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

---

License

MIT license.

Copyright

Copyright © 2015. Athan Reines.