populate-env

populate-env

Populate a given object from process.env with default value and types.

Usage Example

// using named import
import { populateEnv } from 'populate-env'

// or using default import
// import populateEnv from 'populate-env'

// with auto inferred type
export let env = {
  JWT_SECRET: '', // mandatory string variable
  HOST: '0.0.0.0', // optional string variable
  VERSION: 0, // mandatory numeric variable
  PORT: 8100, // optional numeric variable
  SOME_MORE_VAR: '',
}

populateEnv(env) // will throw error if missed

populateEnv(env, 'halt') // halt with clear error message
// print to stderr: "Missing JWT_SECRET, SOME_MORE_VAR in env"
// then auto halt with process.exit(1)

Typescript Signature

export default populateEnv

export function populateEnv(
  env: Record<string, string | number>,
  options?: PopulateEnvOptions,
): void

export type PopulateEnvOptions = {
  mode?: 'halt' | 'error' // default is 'error'
  source?: typeof process.env // default is process.env
  auto_load?: boolean // if true, will resolve the env file using getEnvFile(), and load it into source
}

export class EnvError extends Error {
  missingNames: string[]
}

/**
 * @throws {TypeError} if value is not a valid boolean and defaultValue is not provided
 */
export function toBoolean(value: string, defaultValue?: boolean): boolean

/**
 * @description you can add custom mapping here.
 * @default on/off, true/false, yes/no, enable/disable, enabled/disabled
 */
export let boolean_values: Record<string, boolean>

/** save mentioned (subset of) env variables to file */
export function appendEnv<
  T extends object,
  K extends keyof T & string,
>(options: {
  env: T
  /** @default '.env' */
  file?: string
  key: K | K[]
}): void

/** save entire env to file */
export function saveEnv(options: {
  env: object
  /** @default '.env' */
  file?: string
}): void

/**
 * Resolve env file from `process.env.ENV_FILE` if set.
 * Otherwise return the first existing file among `.env.{mode}`, `.{mode}.env`, `{mode}.env`
 * for the mode (use `process.env.NODE_ENV` if set, or `development` then `dev` then `local` when unset).
 * Finally return `.env` if it exists.
 * If no file is found, return null.
 */
export function getEnvFile(): string | null

License

This project is licensed with BSD-2-Clause

This is free, libre, and open-source software. It comes down to four essential freedoms [ref]:

• The freedom to run the program as you wish, for any purpose
• The freedom to study how the program works, and change it so it does your computing as you wish
• The freedom to redistribute copies so you can help others
• The freedom to distribute copies of your modified versions to others