npm package: @hugojosefson/env-config
Description: Reads env variables. Reads files from *_FILE variables. Parses any JSON values.
Latest version: 2.0.2

# @hugojosefson/env-config

Reads env variables into a config object.

[![Build Status](https://travis-ci.org/hugojosefson/env-config.svg?branch=master)](https://travis-ci.org/hugojosefson/env-config)
[![npm page](https://img.shields.io/npm/v/@hugojosefson/env-config)](https://npmjs.com/package/@hugojosefson/env-config)
[![License MIT](https://img.shields.io/npm/l/@hugojosefson/env-config)](https://tldrlegal.com/license/mit-license)
[![SemVer 2.0.0](https://img.shields.io/badge/SemVer-2.0.0-lightgrey)](https://semver.org/spec/v2.0.0.html)
[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen)](https://standardjs.com)

## Usage

### Default

Simplest case, using defaults for everything. Uses `process.env` as its
`source`.

```js
import envConfig from '@hugojosefson/env-config'

const { DB_PORT, DB_USERNAME, DB_PASSWORD } = envConfig()
```

### Using options, for example to CamelCase key names

```js
import envConfig from '@hugojosefson/env-config'
import ra from 'ramda-adjunct'

const transformer = ra.renameKeysWith(camelcase)
const { dbPort, dbUsername, dbPassword } = envConfig({ transformer })
```

For more options, see [API](#api) below.

## Installation

```bash
yarn add @hugojosefson/env-config

  # or

npm install --save @hugojosefson/env-config
```

### Node.js version

- Node.js `>=8.0.0` for using this package in your app.
- Node.js `>=13.7.0` for running the developer tools to make changes to this
  repository.

_Note: If you use Node.js `<8.5.0`, you probably need to
`const envConfig = require('@hugojosefson/env-config')` instead of `import`._

## Features

### Reads files from `_FILE` vars

If any environment variable is suffixed with `_FILE`, it reads its value as a
file path, and replaces it with the file's contents. Also removes the `_FILE`
suffix.

For example, with an environment like this:

```bash
DB_PORT="5432"
DB_USERNAME="my_app"
DB_PASSWORD_FILE="/run/secrets/MY_APP_DB_PASSWORD"
```

...and the file `/run/secrets/MY_APP_DB_PASSWORD` containing:

    mNntp6J76p6pkK2tTgw2bEvC

...you will get this JS object as output:

```js
{
  DB_PORT: 5432,
  DB_USERNAME: 'my_app',
  DB_PASSWORD: 'mNntp6J76p6pkK2tTgw2bEvC'
}
```

### Parses any JSON

If any environment variable _can_ be parsed as JSON, it is. If not, it's still a
string.

For example, number strings are converted to numbers, `"true"` and `"false"` are
converted to the boolean values `true` and `false`, respectively.

It also supports large JSON objects and JSON arrays.

For example, with this environment:

```bash
SERVER='{"http":{"enable":true,"port":3000},"tls":{"enable":false}}'
TEXTS='{"greetings":["Hi!","Hello.","Welcome!"],"goodbyes":["So long","farewell","auf Wiedersehen","good night"]}'
```

...you will get this resulting JS object as output:

```js
{
  SERVER: {
    http: {
      enable: true,
      port: 3000,
    },
    tls: {
      enable: false,
    },
  },
  TEXTS: {
    greetings: ['Hi!', 'Hello.', 'Welcome!'],
    goodbyes: ['So long', 'farewell', 'auf Wiedersehen', 'good night'],
  },
}
```

## Parses base64 and hex

If a string is prefixed with `base64:` or `hex:`, the rest of the string is
automatically parsed as such, into a new string. That string may in turn be
similarly encoded, or a JSON string.

## API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### envConfig

Parses the source into an object.

#### Parameters

- `source` Source object. _Optional. Default: `process.env`._
- `keys` Array of keys to use. _Optional. Default: All keys in `source`._
- `decoders` Array of decoder definitions to attempt to use for decoding each
  value. Each decoder definition is an object with a property `prefix` whose
  value is a string, or a property `test` whose value is a function to test
  whether to use this decoder to process the value. Additionally, each decoder
  definition has a property `decode` which is a function taking the original
  value, and returning the decoded value. Alternatively `decodeWithoutPrefix`
  can be defined, which is called with the original value, just having its
  prefix chopped off first. _Optional. Default: `defaultDecoders`._
- `transformers` Array of functions for making any changes to the configuration
  object afterwards. Will be run in order of appearance. _Optional._
- `transformer` Alternatively for convenience, a single function for making any
  change to the configuration object afterwards. _Takes the complete config
  object as argument, and must return the new/altered config object. Optional._
- `redactFileContents` Whether to redact contents from files. _Optional.
  Default: `false`._
- `readFile` Synchronous function to read contents from a file path. _Optional.
  Default: `'[redacted]'` if `redactFileContents === true`, otherwise
  `path => readFileSync(path, { encoding: 'utf8' })`._
- `failOnMissingFile` Whether to fail if a file can not be read. If `true`, will
  throw an error if the path to a `_FILE` can not be read, If `false`, will
  leave the `_FILE` key as it was. _Optional. Default: `false`._

Returns **any** An object where the values are parsed according to
<a href="#features">Features</a>.

### defaultDecoders

Default decoders, decoding strings prefixed with `base64:` and `hex:` into
strings, and `base64binary:` and `hexbinary` into `Buffer`s.