Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hugojosefson/env-config

Reads env variables. Reads files from _FILE variables. Parses any JSON values.
https://github.com/hugojosefson/env-config

config env environment environment-variables hacktoberfest json nodejs

Last synced: 29 days ago
JSON representation

Reads env variables. Reads files from _FILE variables. Parses any JSON values.

Awesome Lists containing this project

README

        

# @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

### 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
Features.

### defaultDecoders

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