@matguig/environment NPM

@matguig/environment

This package allows you to easily and safely access your environment variables.

Installation

yarn add @matguig/environment
# -- or
npm install @matguig/environment

Usage

Start a new project with it

import Environment from '@matguig/environment';

// Optionally, you can set default environment values globally.
// They will be used if they are not defined in your environment variables.
Environment.setDefaults({
  PORT: '3000',
  API_URL: 'https://api.matguig.dev/'
});

Check your current environment

Often it can be useful to check if your application is working in production or not. In a NodeJS application by convention we use the environment variable NODE_ENV.

This library allows you to simply check if your script is running in a production context.

import Environment from '@matguig/environment';

if (Environment.isProduction()) {
  console.log(`This application is running in a production environment.`);
} else {
  console.log(`This application is not run in a production environment.`);
  console.log(`Your current environment is ${Environment.getEnvName()}`);
}

Introduction: Using environment variables

Let's say you want to check for the existence of an environment variable.

import Environment from '@matguig/environment';

if (Environment.has('APPDATA')) {
  console.log('It seems you are using a Microsoft operating system...');
}

Now let's say you just want to retrieve the raw value of an environment variable.

import Environment from '@matguig/environment';

const apiHostname = Environment.get('API_HOSTNAME');
const applicationPort = Environment.get('PORT');

However, if the variable in question does not exist, the library will throw an UndefinedEnvironmentVariableError error. To avoid this you can use a default value which will be returned.

import Environment from '@matguig/environment';

const apiHostname = Environment.get('API_HOSTNAME', 'localhost');
const applicationPort = Environment.get('PORT', '3000');

Okay, but in the following example your application port must be an integer. To avoid any problems you can use the parsing feature.

import Environment from '@matguig/environment';

const apiHostname = Environment.get('API_HOSTNAME', 'localhost');
const applicationPort = Environment.getInt('PORT', 3000);

Warning, if the environment variable cannot be parsed correctly, then the library will throw an EnvironmentVariableParseError.

Parsing numbers (integer or float)

To parse numbers two methods are available, getInt and getFloat.

// Application loaded with following environment variables:
//  - RANDOM_FLOAT_NUMBER = '42.21'
//  - RANDOM_INTEGER_NUMBER = '42'
//  - INVALID_NUMBER = 'lorem ipsum'
import Environment from '@matguig/environment';

// Classic
Environment.getInt('RANDOM_FLOAT_NUMBER'); // 42
Environment.getInt('RANDOM_INTEGER_NUMBER'); // 42
Environment.getFloat('RANDOM_FLOAT_NUMBER'); // 42.21
Environment.getFloat('RANDOM_INTEGER_NUMBER'); // 42

// Fallbacks
Environment.getInt('DOES_NOT_EXIST', 24.42); // 24
Environment.getFloat('DOES_NOT_EXIST', 24.42); // 24.42

// Errors
Environment.getInt('DOES_NOT_EXIST'); // throw UndefinedEnvironmentVariableError
Environment.getFloat('DOES_NOT_EXIST'); // throw UndefinedEnvironmentVariableError
Environment.getInt('INVALID_NUMBER'); // throw EnvironmentVariableParseError
Environment.getFloat('INVALID_NUMBER'); // throw EnvironmentVariableParseError

Parsing booleans

The environment variable is considered a boolean if it is equal to "true", "false", "1" or "0". It is important to note that for this particular case the library will be case insensitive and will perform a trim.

// Application loaded with following environment variables:
//  - TRUE_STRING = 'true'
//  - FALSE_STRING = 'False'
//  - TRUE_INT = '1'
//  - FALSE_INT = '0'
//  - INVALID_BOOL = 'Falsy'
import Environment from '@matguig/environment';

// Classic
Environment.getBool('TRUE_STRING'); // true
Environment.getBool('FALSE_STRING'); // false
Environment.getBool('TRUE_INT'); // true
Environment.getBool('FALSE_INT'); // false

// Fallbacks
Environment.getBool('DOES_NOT_EXIST', true); // true
Environment.getBool('DOES_NOT_EXIST', false); // false

// Errors
Environment.getBool('DOES_NOT_EXIST'); // throw UndefinedEnvironmentVariableError
Environment.getBool('INVALID_BOOL'); // throw EnvironmentVariableParseError

Parsing JSON

here the library will parse the environment variable as JSON.

// Application loaded with following environment variables:
//  - FLOAT_NUMBER = '42.21'
//  - BOOL_STRING = 'true'
//  - JSON_OBJECT = '{"FOO": "BAR"}'
//  - JSON_ARRAY = '[1, 2, 3]'
//  - INVALID_JSON = '{...]'
import Environment from '@matguig/environment';

type MySillyObject {
  FOO: 'BAR' | 'BAZ'
}

// Classic
Environment.getJSON<MySillyObject>('JSON_OBJECT'); // {"FOO": "BAR"}
Environment.getJSON<number[]>('JSON_ARRAY'); // [1, 2, 3]
Environment.getJSON('BOOL_STRING'); // true
Environment.getJSON('FLOAT_NUMBER'); // 42.21

// Fallback
Environment.getJSON('DOES_NOT_EXIST', {"hello": "world"}); // {"hello": "world"}

// Errors
Environment.getBool('DOES_NOT_EXIST'); // throw UndefinedEnvironmentVariableError
Environment.getBool('INVALID_JSON'); // throw EnvironmentVariableParseError

Parsing File / File Path

Sometimes an environment variable contains a file path, it may be useful to check if the file exists.

// Application loaded with following environment variables:
//  - VALID_FILE_PATH = '/TOTO.TXT'
//  - NONE_EXISTING_PATH = '/FOO/BAR'
import Environment from '@matguig/environment';

// Classic
Environment.getFilePath('VALID_FILE_PATH'); // /TOTO.TXT

// Fallback
Environment.getFilePath('NONE_EXISTING_PATH', '/TOTO.TXT'); // /TOTO.TXT

// Errors
Environment.getFilePath('NONE_EXISTING_PATH'); // throw Error // File does not exist
Environment.getFilePath('NONE_EXISTING_VAR'); // throw UndefinedEnvironmentVariableError
Environment.getFilePath('NONE_EXISTING_VAR', '/FOO/BAR'); // throw Error // File does not exist

You can also get a readable stream or directly the content

// Application loaded with following environment variables:
//  - VALID_FILE_PATH = '/TOTO.TXT'
//  - NONE_EXISTING_PATH = '/FOO/BAR'
import Environment from '@matguig/environment';

// Classic
Environment.getFile('VALID_FILE_PATH'); // Promise<ReadStream>
Environment.getFileContent('VALID_FILE_PATH'); // Buffer

// options
Environment.getFile('VALID_FILE_PATH', {encoding: 'utf-8'}); // Promise<ReadStream>
Environment.getFileContent('VALID_FILE_PATH', 'utf-8'); // string