@herp-inc/environmen-ts

A composable environment variable decoder library

Configuration made easy

Configure your twelve-factor app via environment variables, using the simple, concise, and type-safe API.

• Composable: Decode your configuration painlessly. A complex decoder can be made up of a smaller ones, making it enjoyable to combine multiple variables.
• Batteries included: Don't reinvent the wheel anymore. Various kinds of ready-made decoders are available. Common strategies such as switching the implementation depending on the value of a specific variable can be easily achived.
• Made for production apps: Know what's happening on deployments. Increase the observability by logging everything.

Installation

Note that the following packages are peer dependencies of this library, which need to be installed separately.

Package	Version
fp-ts	^2.11.0

$ yarn add @herp-inc/environmen-ts

Example

import {
  defaultTo,
  Environment,
  EnvironmentError,
  hex,
  keyOf,
  optional,
  port,
  required,
} from '@herp-inc/environmen-ts';
import * as E from 'fp-ts/Either';
import { pipe } from 'fp-ts/function';
import * as RE from 'fp-ts/ReaderEither';

type LogLevel = 'debug' | 'info' | 'warn' | 'error';
type Config = {
  logLevel: LogLevel;
  port: number;
  secretKeyBase: Buffer;
};

const portD = required('PORT', port());

const logLevelD = pipe(
  optional(
    'LOG_LEVEL',
    keyOf({
      debug: null,
      info: null,
      warn: null,
      error: null,
    }),
  ),
  defaultTo<LogLevel>(() => 'info'),
);

const secretKeyBaseD = required('SECRET_KEY_BASE', hex({ length: 32 }), {
  // You can optionally mark a variable to be sensitive so that it will not be logged.
  sensitive: true,
});

const configD = pipe(
  RE.Do,
  RE.bind('port', () => portD),
  RE.bind('logLevel', () => logLevelD),
  RE.bind('secretKeyBase', () => secretKeyBaseD),
);

const env = new Environment(process.env);

const config: E.Either<EnvironmentError, Config> = configD(env);

// Check out what's found and what's missing.
for (const log of env.logs()) {
  logger.info(log);
}

Core concepts

Environment

The Environment class represents a set of environment variables.

const env = new Environment(process.env);

Its main use is to be an argument of a Decoder.

let configD: Decoder<Config>;
const config: Either<EnvironmentError, Config> = configD(env);

Each access to an environment variable is internally tracked, so that you can easily inspect it later on.

for (const log of env.logs()) {
  logger.info(log);
}

VariableDecoder

Every environment variable is a mere string, hence it must be decoded into some value in order to play with it. A VariableDecoder<A> is defined as ReaderEither<Variable, EnvironmentError, A>, that is, a function that takes a Variable and returns either of EnvironmentError of A. (Here you can think a Variable to be a key-value pair of an environment variable.)

For an instance, port is a variable decoder for a TCP/IP port number. See src/VariableDecoder/ for the full list of built-in variable decoders.

A variable decoder can be turned into an environment decoder by passing it to required/optional function.

const portD: Decoder<number> = required('PORT', port());

Decoder

The EnvironmentDecoder<A> (or simply Decoder<A>, for short) is defined as ReaderEither<Environment, EnvironmentError, A>, that is, a function that takes an Environment and returns either of EnvironmentError or A.

You can compose multiple environment decoders to build a more complex one.

Combining multiple variables with Do notation

const mysqlClientD: Decoder<MySQLClient> = pipe(
  RE.Do,
  RE.bind('host', () => required('MYSQL_HOST', string())),
  RE.bind('port', () => required('MYSQL_PORT', port())),
  RE.bind('user', () => required('MYSQL_USER', string())),
  RE.bind('password', () => required('MYSQL_PASSWORD', string(), { sensitive: true })),
  RE.map(({ host, port, user, password }) => new MySQLClient(host, port, user, password)),
);

Trying multiple strategies sequentially with choice

type Intercom = {
  appID: string;
  secretKey: string;
};

const intercomD: Decoder<Option<Intercom>> = choice([
  pipe(
    RE.Do,
    RE.bind('appID', () => required('INTERCOM_APP_ID', string())),
    RE.bind('secretKey', () => required('INTERCOM_SECRET_KEY', string(), { sensitive: true })),
    RE.map(O.some),
  ),
  RE.of(O.none),
]);

Switching the implementation depending on the value of a specific environment variable with cases

const impls = {
  fs: pipe(
    RE.Do,
    RE.bind('path', () => required('STORAGE_PATH', string())),
    RE.map(({ path }) => new FSStorage(path)),
  ),
  s3: pipe(
    RE.Do,
    RE.bind('region', () => required('AWS_S3_REGION', string())),
    RE.bind('bucket', () => required('AWS_S3_BUCKET', string())),
    RE.map(({ region, bucket }) => new S3Storage(region, bucket)),
  ),
};

const storageD: Decoder<Storage> = pipe(
  required('STORAGE_IMPL', keyOf(impls)), // must be either of 'fs' or 's3'
  RE.chain(cases(impls)),
);