Envirator

Ensure environment variable availability during program initialization.

Install

npm:
npm install @status/envirator

yarn:
yarn add @status/envirator

Usage

Use Envirator to provide and manipulate environment variables.

import { Envirator } from '@status/envirator';

const env = new Envirator();

const port = env.provide('PORT');

If PORT exists it will be of type string. Otherwise, a message will print to the console and immediately exit.

Envirator may also be imported by its alias: Env.

Initialization

Upon initialization you may specify several options:

import { Envirator, EnvInitOptions } from '@status/envirator';

import * as winston from 'winston';

const envOpts: EnvInitOptions = {
  warnOnly: true,
  logger: winston,
  camelcase: true,
  noDefaultEnv: true,
  suppressWarnings: true,
  allowEmptyString: false,
  defaultEnv: 'production',
  productionDefaults: true,
  doNotWarnIn: ['production'],
  nodeEnv: 'NODE_ENVIRONMENT',
};

const env = new Envirator(envOpts);

You may override the default environment strings on initialization or provide custom environments:

const env = new Env({
  environments: {
    test: 'testing',
    staging: 'staged',
    production: 'prod',
    development: 'develop',
    custom: 'custom_env',
  },
});

Be aware that values will be lower-cased.

Initialization Options

| Option | Type | Default Value | Description | | ------------------ | --------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | nodeEnv | string | NODE_ENV | Change where to locate the Node environment. | | logger | EnvLogger | console | Prints warning and error messages to the terminal. | | environments | Environments | { [key: string]: string } | An object that allows overriding of production, development, test and staging strings | | defaultEnv | string | development | Designate the default environment. This should be a key from the environments option. | | noDefaultEnv | boolean | false | Specify if you do not want to provide a default environment if one is not set. | | allowEmptyString | boolean | true | Specify if an empty string is an acceptable environment variable value. | | productionDefaults | boolean | false | Specifies if supplied default values should be allowed in a production environment. | | warnOnly | boolean | false | Warn of missing environment variables rather than exit. Does nothing in production environment. | | suppressWarnings | boolean | string[] | (key: string, env: Envirator) => boolean | false | Specify if warning output should be suppressed. | | camelcase | boolean | false | If true, when calling provideMany, the requested environment variable key will be transformed to camelcase. | | doNotWarnIn | string[] | [production] | An array of Environment strings in which warnOnly is ignored and missing environment variables will force program exit. |

Configs

Load a config by specifying a path or based on the current environment.

import { Envirator } from '@status/envirator';

const env = new Envirator();

// environment based config loading
env.load();

// or

env.load('./path/to/config');

Environment based loading expects a file named .env.environment in the root of your project. For example, a development based environment would attempt to load .env.development.
If the file does not exist Envirator will exit the program.

Environment Variables

Providing environment variables is what Envirator does best! There are a few options you may pass to alter behavior.

import { Envirator, EnvOptions } from '@status/envirator';
import * as winston from 'winston';

const env = new Envirator();

const envOpts: EnvOptions = {
  warnOnly: true,
  logger: winston,
  defaultValue: 4800,
  mutators: parseInt,
  allowEmptyString: false,
  productionDefaults: true,
};

const port = env.provide<number>('PORT', envOpts);

In addition to options previously discussed (warnOnly, logger, productionDefaults, allowEmptyString), you may provide a default value for use in the event an environment variable does not exist.
A single function or an array of functions may be passed to modify the extracted value (mutators).

You may have different default values based on the current environment. Overridden environments may be used.

const envOpts: EnvOptions = {
  defaultsFor: {
    testable: 7623,
    staging: 9999,
    dev: 6543,
  },
  warnOnly: true,
  productionDefaults: false,
};

Providing a default with environment based defaults will utilize the more specific environment, if preset.

const envOpts: EnvOptions = {
  defaultValue: 1234,
  defaultsFor: {
    testable: 7623,
    staging: 9999,
    dev: 6543,
  },
  warnOnly: true,
};

Often you may need many environment variables.

import { EnvManyOptions } from '@status/envirator';

const envVar: EnvManyOptions = {
  key: 'SOME_VAR',
  warnOnly: true,
  camelcase: true,
  defaultValue: 3400,
  defaultsFor: { ... },
  mutators: parseInt,
  productionDefaults: false,
};

const { NODE_ENV, someVar, CONTENT: content } = env.provideMany([
  'NODE_ENV',
  envVar,
  { key: 'CONTENT' },
]);

Additionally you may wish to change the property or the entire shape of the returned object.

const env = new Env({ camelcase: true });

interface JwtOptions {
  secret: string;
  signOptions: {
    issuer: string;
    algorithm: string;
  };
}

function toJwtOptions({
  secret,
  issuer,
  algorithm,
}: EnvManyResult): JwtOptions {
  return {
    secret,
    signOptions: {
      algorithm,
      issuer,
    },
  };
}

const jwtOptions: JwtOptions = env.provideMany(
  [
    { key: 'JWT_SECRET', keyTo: [() => 'secret'], defaultValue: 'token' },
    {
      key: 'JWT_ALGORITHM',
      keyTo: (key) => 'algorithm',
      defaultValue: 'RSA',
    },
    {
      key: 'JWT_ISSUER',
      keyTo: 'issuer',
      defaultValue: 'something',
    },
  ],
  toJwtOptions
);

Set Values

You may set environment variables by passing an object or a single key value pair.

import { Envirator } from '@status/envirator';

const env = new Envirator();

env.setEnv('NODE_ENV', 'development');

const envVars = {
  PORT: 5200,
  SESSION: 'session-key',
  COOKIE: 'cookie-monster',
};

env.set(envVars);

All values are set as strings. No checks are made to ensure the key currently does not exist.

Properties

Envirator has several handy properties that indicate if the current environment is either production, development, staging or test.

if (env.isProduction) {
  // do stuff
}
if (env.isDevelopment) {
  // do stuff
}
if (env.isStaging) {
  // do stuff
}
if (env.isTest) {
  // do stuff
}

Envirator can be extended if you want to use custom environment helpers:

class CustomEnv extends Envirator {
  constructor({ environments = {}, ...options }: EnvInitOptions = {}) {
    super({
      ...options,
      defaultEnv: 'custom',
      environments: { custom: 'my_custom_env', ...environments },
    });
  }

  get isCustom() {
    return this.currentEnv === this.options.environments.custom;
  }
}

You can retrieve or set the current environment:

env.currentEnv;
// => development or whatever the current environment may be (always lowercase)

env.currentEnv = 'test';
// equivalent to 'envirator.setEnv('NODE_ENV', 'test');' NODE_ENV is whatever was set at initialization

Examples

Perhaps in your local development environment you don't have a database user/password.

import { Env } from '@status/envirator';

const env = new Env({ camelcase: true });

const { dbUser, dbPassword } = env.provideMany([
  { key: 'DB_USER', warnOnly: true },
  { key: 'DB_PASSWORD', warnOnly: true },
]);

A warning is issued to the console rather than immediately exiting, unless the environment is production.

---

Or setting a pool size

const mongoPool = env.provide<number>('MONGO_POOL', {
  defaultValue: 15,
  mutators: parseInt,
  productionDefaults: true,
});

---

Create a config that includes envirator to provide in other files.

export const config = {
  port: env.provide<number>('PORT', { mutators: parseInt }),
  environment: env.currentEnv,
  env,
};

// elsewhere
import { config } from './config';

const { env } = config;

const dbPass = env.provide('DB_PASSWORD', { warnOnly: true });

Modify the built-in environments and disallow warnings.

const env = new Envirator({
  environments: {
    production: 'prod',
    development: 'develop',
  },
  warnOnly: true,
  doNotWarnIn: ['prod', 'staging'],
});