env-var - npm Package Compare versions

Comparing version 3.5.0 to 4.0.0

CHANGELOG.md

@@ -0,1 +1,6 @@
+## 4.0.0 (09/04/19)
+* Rename `.env.mock()` to `env.from()`
+* Change module internals per issue #39
+* Update docs related to `env.mock`
+
 ## 3.5.0 (02/29/19)
@@ -2,0 +7,0 @@ * Update `required()` to support boolean paramter to bypass the check

env-var.d.ts

@@ -219,6 +219,6 @@
   /**
-   * Returns a mock env-var instance, where the given object is used for the environment variable mapping.
-   * Use this when writing unit tests.
+   * Returns a new env-var instance, where the given object is used for the environment variable mapping.
+   * Use this when writing unit tests or in environments outside node.js.
    */
-  mock(mockVars: {[varName: string]: string}): IEnv;
+  from(values: {[varName: string]: string}): IEnv;
 
@@ -225,0 +225,0 @@ /**

env-var.js

 'use strict'
 
-const process = require('process')
 const variable = require('./lib/variable')
 
-function generateVariableAccessor (container, variableName, defaultValue) {
-  if (!variableName) {
-    return container
-  }
-
-  return variable(container, variableName, defaultValue)
-}
-
 /**
- * Returns a variable instance with helper functions, or process.env
- * @param  {String} variableName Name of the environment variable requested
- * @param  {String} defaultValue Optional default to use as the value
- * @return {Object}
+ * Returns an "env-var" instance that reads from the given container of values.
+ * By default, we export an instance that reads from process.env
+ * @param  {Object} container target container to read values from
+ * @return {Object} a new module instance
  */
-exports.get = function (variableName, defaultValue) {
-  return generateVariableAccessor(process.env, variableName, defaultValue)
-}
+const from = (container) => {
+  return {
+    from: from,
 
-/**
- * This is the Error class used to generate exceptions. Can be used to identify
- * exceptions adn handle them appropriatly.
- */
-exports.EnvVarError = require('./lib/env-error')
+    /**
+     * This is the Error class used to generate exceptions. Can be used to identify
+     * exceptions adn handle them appropriatly.
+     */
+    EnvVarError: require('./lib/env-error'),
 
-/**
- * Returns a function that acts like env, except instead of looking at
- * process.env, it instead uses the mock values given to it.Useful during
- * testing of your modules.
- * @param  {Object} mockValues mock values to override process.env values
- * @return {Object} This returns a new module instance indistinguishable from the regular one
- */
-const mock = exports.mock = (mockValues) => {
-  return {
-    mock: mock,
+    /**
+     * Returns a variable instance with helper functions, or process.env
+     * @param  {String} variableName Name of the environment variable requested
+     * @param  {String} defaultValue Optional default to use as the value
+     * @return {Object}
+     */
     get: (variableName, defaultValue) => {
-      return generateVariableAccessor(mockValues, variableName, defaultValue)
+      if (!variableName) {
+        return container
+      }
+
+      return variable(container, variableName, defaultValue)
     }
   }
 }
+
+module.exports = from(process.env)

package.json

 {
   "name": "env-var",
-  "version": "3.5.0",
+  "version": "4.0.0",
   "description": "Verification, sanatization, and type coercion for environment variables in Node.js",
@@ -50,3 +50,3 @@ "main": "env-var.js",
   "devDependencies": {
-    "@types/node": "~11.9.0",
+    "@types/node": "~11.13.0",
     "bluebird": "~3.5.1",
@@ -66,4 +66,4 @@ "chai": "~4.2.0",
   "engines": {
-    "node": ">=4.0"
+    "node": ">=6.0"
   }
 }

README.md

@@ -10,3 +10,4 @@ # env-var
 
-Verification, sanatization, and type coercion for environment variables in Node.js
+Verification, sanatization, and type coercion for environment variables in
+Node.js. This is particularly useful in TypeScript environments.
 
@@ -32,5 +33,8 @@ ## Install
   .asString();
+
+// Read in a port or use a default value of 5432
+const PORT = env.get('PORT', 5432).asIntPositive()
 ```
 
-## TypeScript / ES6
+## TypeScript
 
@@ -40,9 +44,9 @@ ```ts
 
-// Read a PORT environment variable and verify it's a positive integer.
-// If port is not set then we throw an error
-const PORT = env.get('PORT').required().asIntPositive();
+// Read a PORT environment variable and ensure it's a positive number
+// An EnvVarError will be thrown if the variable is not set, or is not a number
+const PORT: number = env.get('PORT').required().asIntPositive();
 ```
 
-## Why use this?
-Because this:
+## Benefits
+Fail fast if your environment is misconfigured. Also, this code:
 
@@ -52,6 +56,6 @@ ```js
 
-const MAX_BATCH_SIZE = env.get('MAX_BATCH_SIZE').required().asInt();
+const MAX_BATCH_SIZE = env.get('MAX_BATCH_SIZE').required().asIntPositive();
 ```
 
-Is cleaner than this:
+Is cleaner than this code:
 
@@ -71,3 +75,3 @@ ```js
 
-// Check the var is a valid number, if not throw
+// Verify we have a valid number, if not throw
 assert(
@@ -77,2 +81,8 @@ typeof MAX_BATCH_SIZE === 'number' && !isNaN(MAX_BATCH_SIZE),
 );
+
+// Verify the number is positive
+assert(
+  MAX_BATCH_SIZE > 0,
+  'MAX_BATCH_SIZE must be a positive number'
+);
 ```
@@ -94,27 +104,18 @@
 
-// #3 - Return the environment object (process.env)
+// #3 - Return the environment object (process.env by default - see env.from() docs for more)
 const allvars = env.get()
 ```
 
+### from(values)
+This function is useful if you're not in a typical Node.js environment, or for
+testing. It allows you to generate an env-var instance that reads from the
+given `values` instead of the default `process.env`.
 
-### env.EnvVarError
-This is the error class used to represent errors raised by this module. Sample
-usage:
-
 ```js
-const env = require('env-var')
+const env = require('env-var').from({
+  API_BASE_URL: 'https://my.api.com/'
+})
 
-try {
-  // will throw if you have not set this variable
-  env.get('MISSING_VARIABLE').required().asString()
-
-  // if catch error is set, we'll end up throwing here instead
-  throw new Error('some other error')
-} catch (e) {
-  if (e instanceof env.EnvVarError) {
-    console.log('we got an env-var error', e)
-  } else {
-    console.log('we got some error that wasn\'t an env-var error', e)
-  }
-}
+// apiUrl will be 'https://my.api.com/'
+const apiUrl = mockedEnv.get('API_BASE_URL').asUrlString()
 ```
@@ -231,14 +232,23 @@
 
-#### mock(valuesMap)
-Can be used during testing for mocking of environment variables.
 
+### env.EnvVarError
+This is the error class used to represent errors raised by this module. Sample
+usage:
+
 ```js
 const env = require('env-var')
 
-const mockedEnv = env.mock({
-  API_BASE_URL: 'https://my.api.com/'
-})
+try {
+  // will throw if you have not set this variable
+  env.get('MISSING_VARIABLE').required().asString()
 
-// apiUrl will be 'https://my.api.com/'
-const apiUrl = mockedEnv.get('API_BASE_URL').asUrlString()
+  // if catch error is set, we'll end up throwing here instead
+  throw new Error('some other error')
+} catch (e) {
+  if (e instanceof env.EnvVarError) {
+    console.log('we got an env-var error', e)
+  } else {
+    console.log('we got some error that wasn\'t an env-var error', e)
+  }
+}
 ```
@@ -245,0 +255,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

32569

increased by1.09%

Number of lines in readme file

341

increased by3.02%

Worsened metrics

Lines of code

461

decreased by-1.5%

No dependency changes