feat: add isRequired argument to required function

Author: evanshortiss

CHANGELOG.md

@@ -1,3 +1,6 @@
+## 3.5.0 (02/29/19)
+* Update `required()` to support boolean paramter to bypass the check
+
 ## 3.4.2 (06/11/18)
 * Fix README badge copy/paste error
 

README.md

@@ -116,21 +116,27 @@ try {
 A variable is returned by calling `env.get`. It has the exposes the following
 functions to validate and access the underlying value.
 
-#### required()
+#### required(isRequired = true)
 Ensure the variable is set on *process.env*. If the variable is not set this
 function will throw an `EnvVarError`. If the variable is set it returns itself
 so you can access the underlying variable.
 
-For example:
+Can be bypassed by passing `false`, i.e `required(false)`
+
+Full example:
 
 ```js
 const env = require('env-var')
 
 // Read PORT variable and ensure it's a positive integer. If it is not a
 // positive integer or is not set the process will exit with an error (unless
 // you catch it using a try/catch or "uncaughtException" handler)
+const NODE_ENV = env.get('NODE_ENV').asString()
 const PORT = env.get('PORT').required().asIntPositive()
 
+// If mode is production then this is required, else use default
+const SECRET = env.get('SECRET', 'bad-secret').required(NODE_ENV === 'production').asString()
+
 app.listen(PORT)
 ```
 

env-var.d.ts

@@ -104,9 +104,10 @@ interface IOptionalVariable {
   convertFromBase64: () => IOptionalVariable
 
   /**
-   * Ensure the variable is set on process.env, if not an exception will be thrown.
+   * Ensures the variable is set on process.env, if not an exception will be thrown.
+   * Can pass false to bypass the check
    */
-  required: () => IPresentVariable;
+  required: (isRequired?: boolean) => IPresentVariable;
 
   /**
    * Attempt to parse the variable to a float. Throws an exception if parsing fails.

lib/variable.js

@@ -96,8 +96,13 @@ module.exports = function getVariableAccessors (container, varName, defValue) {
     /**
      * Ensures a variable is set in the given environment container. Throws an
      * EnvVarError if the variable is not set or a default is not provided
+     * @param {Boolean} isRequired
      */
-    required: function () {
+    required: function (isRequired) {
+      if (isRequired === false) {
+        return accessors
+      }
+
       if (typeof container[varName] === 'undefined' && typeof defValue === 'undefined') {
         throw new EnvVarError(`"${varName}" is a required variable, but it was not set`)
       }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "env-var",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "description": "Verification, sanatization, and type coercion for environment variables in Node.js",
   "main": "env-var.js",
   "typings": "env-var.d.ts",

test/index.js

@@ -355,6 +355,12 @@ describe('env-var', function () {
       expect(mod.get('JSON').required().asJson()).to.be.an('object')
     })
 
+    it('should not throw if required is passed a false argument', function () {
+      delete process.env.JSON
+
+      expect(mod.get('JSON').required(false).asJson()).to.equal(undefined)
+    })
+
     it('should throw an exception when required, but not set', function () {
       delete process.env.JSON