@b2wads/env-o-loader

@b2wads/env-o-loader

This is a helper to make easier loading enviroment-oriented settings.

Genesis

This code was born inside B2WADS code base, and it made sense to release this as open source.

Install

npm install @b2wads/env-o-loader

Use

Simply import the module and call it as a function:

const loader = require("@b2wads/env-o-loader")
const settings = loader(require("config/my-app"))

The configuration object must have a defaults key at least, and should have a key for each environment you intent to work with.

Environments as primitive values

Let’s take the following JSON settings file:

{
  "defaults": "some default value",
  "test": "test environment",
  "production": "env:MY_VAR"
}

@b2wads/env-o-loader will select the environment according to the NODE_ENV envvar content, defaults to development.

• If NODE_ENV is test, @b2wads/env-o-loader returns "test environment";
• If NODE_ENV is production, @b2wads/env-o-loader returns the content of the MY_VAR envvar;
• If NODE_ENV is something else, @b2wads/env-o-loader returns "some default value".

You also can supply the environment you want as second parameter:

loader(require("./config"), "sandbox")

Environments as object

The object environment advantage is that the defaults value fullfills the undefined keys.

For example:

{
  "defaults": {
    "x": 3,
    "y": 4
  },
  "development": {
    "z": 5
  }
}

Under development environment, @b2wads/env-o-loader returns the following object:

{ x: 3, y: 4, z: 5 }

Nested keys

You can use nested keys. For example, the sample above can be written as:

{
  "defaults": {
    "x": 3,
    "y": 4
  },
  "development.z": 5
}

With the same result.

Nested keys can be multilevel:

{
  "defaults": {},
  "development": {
    "foo.bar.a": true,
    "foo.bar.b": false,
    "foo.baaz": null
  }
}

Leading to:

{
  foo: {
    bar: { a: true, b: false },
    baaz: null,
  },
}

And can be compound with unnested one:

{
  "defaults": {},
  "development": {
    "foo": { "baaz": null },
    "foo.bar": { "a": true },
    "foo.bar.b": false
  }
}

Data from envvar

Using the env: prefix, @b2wads/env-o-loader loads the content from an envvar.

To load objects from envvar, use querystring format:

{
  "defaults": {},
  "production": "env:SETTINGS"
}

env SETTINGS="x=3&y=4&foo[]=bar&foo[]=baaz"

Nested objects can be got like:

env SETTINGS="v[x]=3&v[y]=4"

Other types

If you must load settings from JSON or envvar, @b2wads/env-o-loader supports more types than those formats, serialised as string.

• Date: use ISO 8601: 2010-10-10 for October 10, 2010.
• Time: use ISO 8601: 2010-10-10T12:30:00Z for October 10, 2010, 12:30 UTC.
• Duration: use ISO 8601: P3Y6M4DT12H30M5S for 3 year, 6 months, four days, 12 hours, 30 minutes, and 5 seconds.
• Regular expressions: write the regex inside a string. For example: "/\\w(cde)?/i" means /\w(cde)?/i.

Extras only in querystring:

• null string resolves to null
• true string resolves to true
• false string resolves to false
• anything parseable to number resolves to number

To force string, you must prefix the value with raw::

• raw:null resolves to "null"
• raw:2010-10-10 resolves to "2010-10-10"
• raw:PT12H resolves to "PT12H"
• raw:42 resolves to "42"
• raw:env:HOME resolves to "env:HOME"
• raw:raw: resolves to "raw:"

Loading files

@b2wads/env-o-loader can load files by its names. The supported types are JSON and YAML.

The JSON file string must ends with .json, and the YAML file string must ends with .yaml or .yml.

Examples:

• loader("./config/data.json")
• loader("../../settings.yaml")

License

This code is licensed under the 3-Clause BSD License.