@hexlabs/env-vars-ts

Typesafe control over environment variables in Typescript.

Get Started

Define the required environment variable names that you want by calling create():

const builder = EnvironmentBuilder.create('a', 'b');

Define the optional environment variable names that you want:

const builder = EnvironmentBuilder
  .create('a', 'b')
  .optionals('c', 'd');

Provide defaults optionally:

const builder = EnvironmentBuilder
  .create('a', 'b')
  .optionals('c', 'd')
  .defaults({ a: 'default for a' });

Get environment variables from process.env by default or provide your own

// The type of environment is { a: string; b: string; c?: string; d?: string }
const environment = EnvironmentBuilder
  .create('a', 'b')
  .optionals('c', 'd')
  .defaults({ a: 'default for a' })
  .environment(); // <- Provide your own envs here

Provide custom transforms for selected envs

// The type of environment is 
// {
//   selected: boolean;
//   count: number;
//   optionallySelected?: boolean;
//   standardEnv?: string;
// }
const environment = EnvironmentBuilder
  .create('selected', 'count')
  .optionals('optionallySelected', 'standardEnv')
  .transform(s => s === 'true', 'selected', 'optionallySelected')
  .transform(s => Number.parseInt(s), 'count')
  .defaults({ count: 25 }) // defaults will take into account your transforms notice this is a number and not a string.
  .environment();

Lazily retrieve the type of environment before running

const environmentBuilder = EnvironmentBuilder.create('a', 'b');

// Use Type alias for the environment defintion 
// We use this in HexLabs to define expected lambda environment variables when creating CloudFormation stacks
// where we do not want to check at build time as the stack is generated form TypeScript.
type EnvVars = ReturnType<typeof environmentBuilder.environment>;

//Get actual environment variables somewhere else
const environment = environmentBuilder.environment();