npm package: @poppinss/env
Description: Environment variable manager for Node.js
Author: virk,poppinss
Latest version: 1.0.6
Deprecated: Use @adonisjs/env instead

<div align="center">
  <img src="https://res.cloudinary.com/adonisjs/image/upload/q_100/v1557762307/poppinss_iftxlt.jpg" width="600px">
</div>

# Env
[![circleci-image]][circleci-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url]

Environment variables parser and reader for Node.js. This module parses the raw string in dotfile format and set `process.env` variables from it. Also, you can make use of bash like syntax for [variable interpolation](#variable-interpolation).

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
## Table of contents

- [Usage](#usage)
- [Casting values](#casting-values)
- [Variable interpolation](#variable-interpolation)
  - [Following will fail](#following-will-fail)
  - [Do this instead](#do-this-instead)
  - [Escape characters](#escape-characters)
- [API](#api)
- [Maintainers](#maintainers)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Usage
Install the package from npm as follows:

```sh
npm i @poppinss/env

# yarn
yarn add @poppinss/env
```

and then use it as follows

```ts
import { env } from '@poppinss/env'

env.process(`
  PORT=3333
  HOST=127.0.0.1
`)
```

and then read the values as follows

```ts
env.get('PORT')

// or
process.env.PORT
```

The `Env.process` method **will not overwrite** the existing environment variables (that is how it should be). However, if you want to overwrite existing values, maybe inside testing environment, then you can call the `process` method as follows:

```ts
env.process('PORT=3333', true)
```

## Casting values
The values saved as environment variables are always string. However, this module does the values casting for you, when you read them using `Env.get`.

```ts
env.process(`
  CACHE_VIEWS=false
`)

process.env.CACHE_VIEWS // string
env.get('CACHE_VIEWS') // boolean
```

Following values are casted

| .env Value | Casted value |
|------------|--------------|
| `'null'` | `null` |
| `'true'` | `true` |
| `'1'` | `true` |
| `'false'` | `false` |
| `'0'` | `false` |

## Variable interpolation
You can also reference environment variables by using bash like interpolation syntax.

```ts
env.process(`
  HOST=localhost
  PORT=3333
  URL=$HOST:$PORT
`)
```

All `letter`, `numbers` and `_` after the dollar sign will be considered as a variable reference. Any other characters apart from the above mentioned aren't allowed. However, you can wrap your variable substitution inside curly braces `{}` when using characters other than the whitelisted one's.

### Following will fail
The following reference to `$REDIS-USER` will fail, since the parser will stop at `-` and consider `USER` as a static string.

```ts
env.process(`
  REDIS-USER=foo
  REDIS-URL=localhost@$REDIS-USER
`)
```

### Do this instead
The usage of curly braces `{}` tells the parser to parse until the closing brace.

```ts
env.process(`
  REDIS-USER=foo
  REDIS-URL=localhost@${REDIS-USER}
`)
```

### Escape characters
Quite often, you will have strings where you want the `$` dollar character to be considered as a literal value. In that case you can escape the character as follows.

```ts
env.process(`
  PASSWORD=pa\\$\\$word
`)

process.env.PASSWORD // pa$$word
```

> **DO NOTE**: The usage of double escape `\\` is required when you are typing the string directly in Javascript, since the first escape is swallowed by JS. However, if you are writing the enviornment variables inside the `.env` file, then a single escape `\` is required.

## API
Following are the autogenerated files via Typedoc

* [API](docs/README.md)

## Maintainers
[Harminder virk](https://github.com/thetutlage)

[circleci-image]: https://img.shields.io/circleci/project/github/poppinss/env/master.svg?style=for-the-badge&logo=circleci
[circleci-url]: https://circleci.com/gh/poppinss/env "circleci"

[npm-image]: https://img.shields.io/npm/v/@poppinss/env.svg?style=for-the-badge&logo=npm
[npm-url]: https://npmjs.org/package/@poppinss/env "npm"

[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript

[license-url]: LICENSE.md
[license-image]: https://img.shields.io/aur/license/pac.svg?style=for-the-badge