dotenv-utils

Covert env var strings to booleans, numbers, arrays, and objects.

Context: Environment variables are a great way to separate config from code. Tools like dotenv make this almost perfect but...

The problem: Environment variables are always strings. If you set a variable MINIFY=false and try to check it using if (process.env.MINIFY) { ...some logic }, then "...some logic" will actually be executed as non-empty strings are truthy.

The quick solution is to write process.env.MINIFY === "true" instead, but as you get more vars and more var "types", these ad-hoc solutions become tedious, unclear, and error-prone.

The solution: dotenv-utils provides several helpers to make sure you never have to worry about this again.

• boolean, number, array, object convert vars one at a time.
• conform creates a new config object with the correct types based on a schema.

Conversion functions always return the right type. That way, you can safely call methods without worrying about getting that Uncaught Type Error: undefined is not a function fun.

Install

# Using `npm`
npm install --save dotenv-utils

# ...or using `yarn`
yarn add dotenv-utils

Tested on Node.js v6.9.2, likely runs on earlier versions too.

API

boolean

Converts a string representation (case-insensitive) of a boolean to an actual boolean.

const {boolean} = require("dotenv-utils")

boolean("true") // true
boolean("TRUE") // true
boolean("false") // false
boolean("foo") // false
boolean("") // false
boolean(undefined) // false

number

Converts a string representation of a number to an actual number. Basically like Number(x), but will return a 0 instead of NaN when string cannot be converted to a number.

const {number} = require("dotenv-utils")

number("123") // 123
number("  123   ") // 123
number("foo") // 0
number(undefined) // 0

string

Trims the supplied string. If provided a falsy value, returns "". This is mainly useful when used in conjunction with the conform helper.

const {string} = require("dotenv-utils")

string("foo") // foo
string("  foo   ") // "foo"
string("") // ""
string(undefined) // ""

array

Converts a string of comma-separated values ("foo, bar, baz") to an array. Any extra whitespace will be trimmed and empty strings discarded.

const {array} = require("dotenv-utils")

array("foo, bar, baz") // ["foo", "bar", "baz"]
array("foo,   bar,    baz") // ["foo", "bar", "baz"]
array(",,,") // []
array("") // []
array(undefined) // []

object

Converts a string of comma-separated tuples ("foo: bar, baz: quux") to an object. Any extra whitespace from either key or value will be discarded, as are tuples with falsy keys.

const {object} = require("dotenv-utils")

object("foo: bar, baz: quux") // {foo: "bar", baz: "quux"}
object("foo:    bar   ,baz:quux") // {foo: "bar", baz: "quux"}
object(":,foo:") // {foo: ""}
object("::,") // {}
object("") // {}
object(undefined) // {}

conform

Provided a schema, conform picks keys from an env object and converts them using the supplied functions.

Keys which are present in the schema, but not in the supplied env object will be present in the final object, having a value/type based on calling the conversion function with undefined.

Given these env vars:

DEFAULT_LOCALE=en-GB
SUPPORTED_LOCALES=en-GB,cs-CZ,pl-PL

You can do this:

// Make sure you have loaded the env vars somehow,
// either inline or using `dotenv`...

const {conform, boolean, array, string} = require("dotenv-utils")

// Specify a schema using the conversion functions
const schema = {
  MINIFY: boolean,
  DEFAULT_LOCALE: string,
  SUPPORTED_LOCALES: array,
}

// Drop `process.env` into `conform`
const config = conform(process.env, schema)

// `config` is now:
// {
//   MINIFY: false,
//   DEFAULT_LOCALE: "en-GB",
//   SUPPORTED_LOCALES: ["en-GB", "cs-CZ", "pl-PL"],
// }

module.exports = config

Other Tools

• https://www.npmjs.com/package/getenv — Slightly different concept, very good solution.
• https://github.com/niftylettuce/dotenv-parse-variables — Very similar, mutates process.env.

License

MIT