Transform environment variables into JSON object with sanitized values.

See docs for previous version v1.3.x.

Main purpose of this library is to allow developers to configure their applications with environment variables. See: a use case example.

• Migrated to Typescript, Yay! 🎉
• Simplified API
• With new separator option,nested object constructions are possible.
• New source option allows you to use other objects, other than process.env

• default export is deprecated. Please use named export readEnv as below:

const { readEnv } = require('read-env');
// Or
import { readEnv } from 'read-env';
// Or in browser
window.readEnv('EXAMPLE');

• parse option was renamed as sanitize.
• transformKey option was renamed as format.
• Deprecated options: ignoreInvalidJSON, prefix, filter,

npm install --save read-env

or

yarn add read-env

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

EXAMPLE_OBJECT='{"prop": "value"}'
EXAMPLE_ARRAY='[1,2,3, "string", {"prop": "value"}, 5.2]'
EXAMPLE_INVALID_OBJECT='{"prop": }"value"}'
EXAMPLE_INVALID_ARRAY='[1,2,3, "string", ]{"prop": "value"}, 5.2]'
EXAMPLE_TRUE='true'
EXAMPLE_FALSE='false'
EXAMPLE_INT='5'
EXAMPLE_NEGATIVE_INT='-11'
EXAMPLE_FLOAT='5.2456'
EXAMPLE_NEGATIVE_FLOAT='-2.4567'
EXAMPLE_INT_ZERO='0'
EXAMPLE_FLOAT_ZERO='0.00'
EXAMPLE_NEGATIVE_INT_ZERO='-0'
EXAMPLE_NEGATIVE_FLOAT_ZERO='-0.00'
EXAMPLE_STRING='example'
EXAMPLE_DEEP__OBJECT__PROPERTY='value'

app.js

import { readEnv } from 'read-env';

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

Result:

{
  "object": { "prop": "value" },
  "array": [1, 2, 3, "string", { "prop": "value" }, 5.2],
  "invalidObject": "{\"prop\": }\"value\"}",
  "invalidArray": "[1,2,3, \"string\", ]{\"prop\": \"value\"}, 5.2]",
  "true": true,
  "false": false,
  "int": 5,
  "negativeInt": -11,
  "float": 5.2456,
  "negativeFloat": -2.4567,
  "intZero": 0,
  "floatZero": 0,
  "negativeIntZero": -0,
  "negativeFloatZero": -0,
  "string": "example",
  "deep": {
    "object": {
      "property": "value"
    }
  }
}

Input:

• prefix (type: string, default: undefined): filters environment variables by prefix
• options (type: ReadEnvOptions, default: {}): options object to change function's behaviour

Returns: object (type: Record<string,any>), returns the instance, so add methods are chainable.

Default Options:

{
  "source": process.env,
  "format": "camelcase",
  "separator": "__",
  "sanitize": {
    "object": true,
    "array": true,
    "bool": true,
    "int": true,
    "float": true
  },
  "includePrefix": false
}

• options.source
• options.format
• options.separator
• options.sanitize
• options.includePrefix

• Type: object
• Default: process.env

The source object that will be filtered, sanitized and formatted.

Type Signature:

interface Source {
  [key: string]: string | undefined;
}

• Type: boolean | string | function
• Default: camelcase

Format environment variable name.

It's value can be:

• a boolean, if set to false, formatting is disabled
• a string, one of which camelcase, pascalcase, lowercase, uppercase
• a function, with (rawVarName: string) => string type signature

• Type: boolean | string
• Default: __

Allows you construct nested objects from environment variable name.

• If set to false, constructing nested objects is disabled

Example:

const { readEnv } = require('read-env');

const testInput = {
  EXAMPLE_DEEP__OBJECT_PROPERTY1: 'value1',
  EXAMPLE_DEEP__OBJECT_PROPERTY2: 'value2',
};

const result = readEnv('EXAMPLE', {
  source: testInput,
  separator: '_',
});
console.log(result);

Result:

{
  "deep": {
    "object": {
      "property1": "value1",
      "property2": "value2"
    }
  }
}

• Type: boolean | object,
• Default: {}

Sanitize object consists of following properties which is used to

• object (type: bool, default: true): sanitize stringified object

  value must be valid JSON input, see: JSON.parse.

• array (type: bool, default: true): sanitize stringified array

  value must be valid JSON input, see: JSON.parse.

• int (type: bool, default: true): sanitize numbers into integer

  value must be consist of only digits.

• float (type: bool, default: true): sanitize numbers into float

  value must be consist of only digits with decimal point.

• bool (type: bool, default: true): sanitize value into boolean

  value must have case insensitive match with "true" or "false".

• Type: boolean
• Default: false

If set to true, keeps the given prefix in property names.

In past, I used Nightmare for acceptance testing and tests had different configurations based on the environment they were running on.

So, I simply used read-env, and nightmare is fully configurable with environment variables :)

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

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

Instead of writing code like below:

import Nightmare from 'nightmare';

const nightmare = Nightmare({
  show: process.env.MY_NIGHTMARE_SHOW || false,
  width: process.env.MY_NIGHTMARE_WIDTH || 1280,
  height: process.env.MY_NIGHTMARE_HEIGHT || 720,
  typeInterval: process.env.MY_NIGHTMARE_TYPE_INTERVAL || 50,
  //... other properties go forever
});

As always, I'm open to any contribution and would like to hear your feedback.

If you are planning to contribute to any open source project, before starting development, please always open an issue and make a proposal first. This will save you from working on features that are eventually going to be rejected for some reason.

MIT (c) 2020 Mehmet Yatkı