env

Library to make it easier to work with process.env

requirements

• Node v18.16.0+

usage

npm i @xplora-uk/env

const { EnvService, IProcessEnv } = require('@xplora-uk/env');

interface MyEnvSettings extends IProcessEnv {
  HTTP_PORT  ?: string;
  MAIN_DB_URL?: string;
  API_KEY    ?: string;


}

const env = new EnvService<MyEnvSettings>(process.env, { ignoreEmptyStrings: true });
//const env = new EnvService(process.env, { ignoreEmptyStrings: true, keyPrefix: 'MY_APP_' });

const httpPort = env.int('HTTP_PORT', 8080);

const envDb = env.newEnv('MAIN_DB_');
const dbUrl = envDb.url('URL', 'mysql://localhost/test_db'); // URL or null
if (dbUrl.hostname === 'localhost') {
  // do something
}

const envProxy = env.proxy;
if (envProxy.HTTP_PORT) { // editor should recognise properties as you use proxy object
  // always returned as string like env.str('HTTP_PORT')
}

interface

export interface IEnvService<TPenv extends IProcessEnv = IProcessEnv, TKey = keyof TPenv> {
  penv: TPenv;
  options: IEnvServiceOptions;

  str  (key: TKey, defaultValue: string): string;
  int  (key: TKey, defaultValue: number): number;
  float(key: TKey, defaultValue: number): number;
  bool (key: TKey, defaultValue: boolean): boolean;
  url  (key: TKey, defaultValue: string): URL | null; // after v1.3 does not throw error
  json (key: TKey, defaultValue: JsonType): JsonType | null; // version 1.2
  json5(key: TKey, defaultValue: JsonType): JsonType | null; // version 1.2
  csv  (key: TKey, defaultValue: string): string[]; // version 1.2

  newEnv(keyPrefix: string): IEnvService;
  filterEnv(penv: IProcessEnv, keyPrefix: string): IProcessEnv;

  // version 1.1
  loopForEnv<T = any>(
    counterKey: TKey,
    indexKeyPrefix: string,
    envHandler: (env: IEnvService, index: number, keyPrefix: string) => T,
    indexKeyGlue?: string, // defaults to '_'
  ): T[];

  // version 1.1
  loopGetEnvSettings(
    counterKey: TKey,
    indexKeyPrefix: string,
    indexKeyGlue?: string, // defaults to '_'
  ): Array<IObjectWithStrings>;
}

export type IProcessEnv = typeof process.env; // Record<string, string | undefined>

export interface IEnvServiceOptions {
  /**
   * For creating a namespaced environment service.
   * @example 'MYAPP_' to use only keys that start with 'MYAPP_'.
   */
  keyPrefix?: string;

  /**
   * If true, then empty strings are ignored and default value parameter is used.
   */
  ignoreEmptyStrings?: boolean;
}

maintenance

installation

npm i

code

src/
  __tests__/
    unit/
      env.test.ts  unit tests for EnvService
  env-service.ts   implementation
  index.ts         main file that exports features of this library
  types.ts         TypeScript types
  utils.ts         Utility functions

build

npm run build

tests

You can run tests with/without coverage info.

npm run test:unit
npm run test:unit:coverage

Current coverage:

----------------|---------|----------|---------|---------|-------------------
File            | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------------|---------|----------|---------|---------|-------------------
All files       |     100 |      100 |     100 |     100 |                   
 env-service.ts |     100 |      100 |     100 |     100 |                   
 utils.ts       |     100 |      100 |     100 |     100 |                   
----------------|---------|----------|---------|---------|-------------------

publish

It is important to increment version number using semantic versioning in package.json and re-create package-lock.json

# https://docs.npmjs.com/cli/v9/commands/npm-login
# using a member in xplora-uk
npm login

# https://docs.npmjs.com/cli/v9/commands/npm-publish
npm publish --access public