🔧 Transform environment variables into JSON object with sanitized values.
MIT License
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.
separator
option,nested object constructions are possible.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
.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"
}
}
}
readEnv(prefix?: string, options: ReadEnvOptions = {})
Input:
prefix
(type: string
, default: undefined
): filters environment variables by prefixoptions
(type: ReadEnvOptions
, default: {}
): options object to change function's behaviourReturns: 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
object
process.env
The source object that will be filtered, sanitized and formatted.
Type Signature:
interface Source {
[key: string]: string | undefined;
}
options.format
boolean | string | function
camelcase
Format environment variable name.
It's value can be:
boolean
, if set to false
, formatting is disabledstring
, one of which camelcase
, pascalcase
, lowercase
, uppercase
function
, with (rawVarName: string) => string
type signatureoptions.separator
boolean | string
__
Allows you construct nested objects from environment variable name.
false
, constructing nested objects is disabledExample:
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"
}
}
}
options.sanitize
boolean | object
,{}
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".
options.includePrefix
boolean
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ı