dotenv-guards

guards functions for dotenv package

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
dotenv-guards
012.0.23 months ago4 months agoMinified + gzip package size for dotenv-guards in KB

Readme

dotenv guards
dotenv-guards
release status
tests status
guards functions for dotenv package

installation

npm i dotenv dotenv-guards

usage

import { numberGuard } from 'dotenv-guards';

const jobsAsNumber = numberGuard(process.env.jobs, 2); // return 2 if jobs is not a number

Available guards

  • numberGuard - parse a string to a number.
  • enumGuard - parse a string to an enum.
  • booleanGuard - parse a string to a boolean.
  • arrayGuard - parse a string to an array.
  • string - parse string and execute matchers.

API

numberGuard

numberGuard(value, fallbackValue, options)

Options:
  • throwOnFinite - Throws an error if incoming value parsed to Infinity
  • throwOnNaN - Throws an error if incoming value parsed to NaN
  • throwOnUndefined - If true throwing an error if incoming value is undefined
  • throwOnSafeInteger - Throws an error if incoming value is not safe integer

Example:
// process.env.jobs = '2'
numberGuard(process.env.jobs); // returns 2 as number

// process.env.jobs = 'not a number string'
numberGuard(process.env.jobs); // returns 0 as number

// process.env.jobs = 'not a number string'
numberGuard(process.env.jobs, 0, {throwOnSafeInteger: true}); //throws an error

boolean guard

booleanGuard(value, options)

Options:
  • fallback - fallback value if incoming value is not a boolean and cannot parse value to boolean.
  • trueSymbols - Array of possible values which will be converted as true.
  • throwOnUndefined Throw an error if incoming value is undefined, fallback value is not returned, since it returns an error.
  • throwOnFail - Throw an error if incoming value is not matching with trueSymbols option.

Example:
// process.env.isDebug = 'true'
booleanGuard(process.env.isDebug); // returns true

// process.env.acceptDownloading = 'yes'
booleanGuard(process.env.acceptDownloading, false, {trueSymbols: ['yes']}); // returns true since 'yes' is in the array

enum guard

enum(value, arrayOfPossibleValues, fallbackValue)

Example:
// process.env.NODE_ENV = 'test'
enumGuard(process.env.NODE_ENV, ['development', 'production'], 'development'); // returns 'development'

// or define more acceptable values
// process.env.NODE_ENV = 'test'
enumGuard(process.env.NODE_ENV, ['development', 'production', 'test'], 'development'); // returns 'test', since 'test' is in the array

array guard

array(value, arrayOfPossibleValues, options)

Options:
  • strict - If true throwing an error if at least one element is not matched.
  • separator - Separator for incoming value string. Default is ,.

Example:
// process.env.array = 'val1,val2,val3'
arrayGuard(process.env.array, ['val1', 'val2']); // split string by `,` symbol and returns ['val1', 'val2']

// custom separator
// process.env.array = 'val1;val2;val3'
arrayGuard(process.env.array, ['val1', 'val2', 'val3'], {separator: ';'}); // split string by `;` symbol and returns ['val1', 'val2', 'val3']

string guard

string(value, options)

Options:
  • fallback - fallback value if incoming value is not matched by regex or matcher function.
  • throwOnUndefined - Throw an error if incoming value is undefined, fallback value is not returned, since it returns an error.
  • regexp - Regexp for incoming value. Returns first match.
  • throwOnNullable - Throw an error if incoming value is null, undefined, empty string or empty array.
  • matcher - Matcher function for incoming value. Returns boolean(is matched incoming string or not).
  • throwOnMismatch - Throw an error if incoming value is not matched by regex or matcher function.

Example:
// process.env.token = 'hash123'
stringGuard(process.env.token); // returns hash123

// matcher function
// process.env.token = 'hash123'
arrayGuard(process.env.token, {
    matcher: (value) => value.startsWith('hash'),
}); // returns hash123

// miss matching
// process.env.token = 'hash123'
arrayGuard(process.env.token, {
    matcher: (value) => value.startsWith('random string'),
    fallback: 'qwerty'
}); // returns qwerty, since mismatch