# @xpresser/env

> Env Parser with Validation and Required Keys

Latest version **2.1.1** (published 2023-05-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install @xpresser/env
pnpm add @xpresser/env
yarn add @xpresser/env
bun add @xpresser/env
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.1 |
| Published | 2023-05-28 |
| First published | 2020-06-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 21.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | xpresserjs |
| Maintainers | trapcode |
| Keywords | xpresser, env, validation, env-validation |

## Links

- npm: https://www.npmjs.com/package/@xpresser/env
- Repository: https://github.com/xpresserjs/env
- Homepage: https://github.com/xpresserjs/env#readme
- Issues: https://github.com/xpresserjs/env/issues
- npm.io page: https://npm.io/package/@xpresser/env

## Dependencies (2)

- [dotenv](https://npm.io/package/dotenv.md) ^16.0.3
- [dotenv-expand](https://npm.io/package/dotenv-expand.md) ^10.0.0

## Alternatives

- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads

## Recent versions

- 2.1.1 (latest) — 2023-05-28
- 1.1.3 (old) — 2021-11-23
- 2.1.0 — 2023-05-28
- 2.0.10 — 2022-08-24
- 2.0.8 — 2022-05-16
- 2.0.7 — 2022-05-04
- 2.0.6 — 2022-05-04
- 2.0.5 — 2022-05-04
- 2.0.4 — 2022-05-04
- 2.0.3 — 2022-05-04
- 2.0.2 — 2022-03-16
- 2.0.1 — 2022-03-16
- 2.0.0 — 2022-03-16
- 1.1.2 — 2021-11-23
- 1.1.1 — 2021-11-23
- … 5 more at https://npm.io/package/@xpresser/env/versions

## README

# Xpresser/Env
##### This package can be used in any NodeJs related project.

- Loads your env file.
- Interpolates environment variables.
- Cast strings to boolean.
- Checks for required env variables.
- Validate env variables.


## Installation
```shell
npm i @xpresser/env
# OR
yarn add @xpresser/env
```

## Functions
Two functions are exported by the package.

- `LoadEnv` - Loads your env file with option for required keys (without validation).
- `Env` - Loads and validates your environment variables with a simple schema. (Typescript Friendly)

## Example File
Using this example **local.env** file

```dotenv
APP_DOMAIN=localhost
APP_FOLDER="/blog"
APP_PORT=3000
APP_URL="${AppDomain}:${AppPort}${AppFolder}"

CONNECT_TO_API=true
#API_KEY="somekey"
```

### LoadEnv
The `LoadEnv` function accepts the `path` to the env file as first argument and `options` object as the second argument.
The options object can have the following properties:

| Key           | Type      | Default | Description                                                                                                                                    |
|---------------|-----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `castBoolean` | `Boolean` | `true`  | if enabled, all string "true" or "false" will be converted to booleans.                                                                        |
| `required`    | `Array`   | `[]`    | The env loader will check if all the keys defined in this array exists in your specified env file else it stops the process and logs an error. |
| `endProcess`  | `Boolean` | `true`  | By default `process.exit()` is called when required keys are **missing**. to throw Error instead, set this to false.                           |


```javascript
const {LoadEnv} = require('@xpresser/env');
const env = LoadEnv('path/to/local.env', {
    castBoolean: true,
    required: ['API_KEY']
});

console.log(env);
```
##### Result:
```sh
The following ENV variables are REQUIRED but not found.
[ 'API_KEY' ]
```
If you uncomment the `API_KEY` line in your env file, your result will be
```
{
  APP_DOMAIN: 'localhost',
  APP_FOLDER: '/blog',
  APP_PORT: '3000',
  APP_URL: 'localhost:3000/blog',
  CONNECT_TO_API: true,
  API_KEY: 'somekey'
}
```

### Env
The `Env` function accepts the
  - `path` to the env file as first argument, 
  - `schema` object as the second argument 
  - `options` object as the third argument.

The options object can have the following properties:

| Key           | Type      | Default | Description                                                                                                                                    |
|---------------|-----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------|
| `required`    | `Array`   | `[]`    | The env loader will check if all the keys defined in this array exists in your specified env file else it stops the process and logs an error. |
| `endProcess`  | `Boolean` | `true`  | By default `process.exit()` is called when required keys are **missing**. to throw Error instead, set this to false.                           |


Note: The `options` object does not include the `castBoolean` property like the `LoadEnv` function.
This is because the `Env` schema requires and sets `castBoolean` to be **true**


```javascript
const {Env}  = require('@xpresser/env');

const env = Env('path/to/local.env', {
    APP_DOMAIN: Env.is.string('Localhost'), // can have defaults
    APP_FOLDER: Env.is.string(),
    APP_PORT: Env.is.number(3000),
    APP_URL: Env.is.string(),
    CONNECT_TO_API: Env.is.boolean(),
    // optional envs
    API_KEY: Env.optional.string()
});

// `env` will be typed and validated.
```

### Required Conditions
The required array also accepts functions to evaluate conditions.
For example, we want to require `API_KEY` only when: `CONNECT_TO_API===true`

```javascript
const {LoadEnv, Env} = require('@xpresser/env');

const required = [
     'CONNECT_TO_API',
     (envs) => {
         if (envs['CONNECT_TO_API'] === true) {
             return 'API_KEY';
         }
     }   
 ]

const env = envLoader('path/to/local.env', {required});
// OR
const env = Env('path/to/local.env', {
  // declare env variables schema
}, {required})

console.log(env);
```
This will check if `API_KEY` exists only if `CONNECT_TO_API` is true.
You can add as many functions as you want. The loader will run all of them and add returned values to the `required` array.

**Note:** The function can also return an array of strings. the loader will concatenate the strings with the required array.

---
_Source: https://npm.io/package/@xpresser/env · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._