5.0.0 (#58)

* BREAKING CHANGE: URL verification logic now uses Node.js core APIs

Author: evanshortiss

CHANGELOG.md

@@ -1,4 +1,10 @@
-## 4.1.0 (11/06/19)
+## 5.0.0 (14/06/19)
+* Return values from `asArray()` are now more intuitive & consitent
+* `asUrlString()` and `asUrlObject`now use the built-in `URL` class in Node.js
+to perform validation
+* README updated in accordance with changes listed above
+
+## 4.1.0 (14/06/19)
 * Add `asPortNumber()` function
 * Update documentation structure
 

README.md

@@ -35,6 +35,9 @@ some functions to verify it satisfies our program's needs.
 ```js
 const env = require('env-var');
 
+// Or using import syntax:
+// import * as env from 'env-var'
+
 const PASSWORD = env.get('DB_PASSWORD')
   // Throws an error if the DB_PASSWORD variable is not set (optional)
   .required()
@@ -176,15 +179,15 @@ app.listen(PORT)
 
 #### convertFromBase64()
 Sometimes environment variables need to be encoded as base64. You can use this
-function to convert them before reading their value.
+function to convert them to UTF-8 strings before parsing them.
 
 For example if we run the script script below, using the command `DB_PASSWORD=
 $(echo -n 'secret_password' | base64) node`, we'd get the following results:
 
 ```js
 console.log(process.env.DB_PASSWORD) // prints "c2VjcmV0X3Bhc3N3b3Jk"
 
-// dbpass will contain the value "secret_password"
+// dbpass will contain the converted value of "secret_password"
 const dbpass = env.get('DB_PASSWORD').convertFromBase64().asString()
 ```
 
@@ -249,16 +252,22 @@ The same as _asJson_ but checks that the data is a JSON Object, e.g {a: 1}.
 #### asArray([delimiter: string])
 Reads an environment variable as a string, then splits it on each occurence of
 the specified _delimiter_. By default a comma is used as the delimiter. For
-example a var set to "1,2,3" would become ['1', '2', '3'].
+example a var set to "1,2,3" would become ['1', '2', '3']. Example outputs for
+specific values are:
+
+* Reading `MY_ARRAY=''` results in `[]`
+* Reading `MY_ARRAY='1'` results in `['1']`
+* Reading `MY_ARRAY='1,2,3'` results in `['1', '2', '3']`
 
 #### asUrlString()
-Verifies that the variable is a valid URL string and returns that string. Uses
-`is-url` to perform validation, so check that module for validation rules.
+Verifies that the variable is a valid URL string and returns the validated
+string. The validation is performed by passing the URL string to the
+[Node.js URL Constructor](https://nodejs.org/docs/latest/api/url.html).
 
 #### asUrlObject()
-Verifies that the variable is a valid URL string, then parses it using
-`url.parse` from the Node.js core `url` module and returns the parsed Object.
-See the [Node.js docs](https://nodejs.org/api/url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost) for more info
+Verifies that the variable is a valid URL string using the same method as
+`asUrlString()`, but instead returns the resulting URL instance. For details
+see the [Node.js URL docs](https://nodejs.org/docs/latest/api/url.html).
 
 ## Examples
 
@@ -301,15 +310,6 @@ const commaArray = env.get('DASH_ARRAY').asArray('-');
 const enumVal = env.get('ENVIRONMENT').asEnum(['dev', 'test', 'live'])
 ```
 
-## Contributors
-* @caccialdo
-* @evanshortiss
-* @hhravn
-* @itavy
-* @MikeyBurkman
-* @pepakriz
-* @rmblstrp
-
 ## Contributing
 Contributions are welcomed. If you'd like to discuss an idea open an issue, or a
 PR with an initial implementation.
@@ -353,3 +353,13 @@ Once you've done that, add some unit tests and use it like so:
 // Uses your new function to ensure the SOME_NUMBER is the integer 0
 env.get('SOME_NUMBER').asNumberZero()
 ```
+
+## Contributors
+* @caccialdo
+* @evanshortiss
+* @gabrieloczkowski
+* @hhravn
+* @itavy
+* @MikeyBurkman
+* @pepakriz
+* @rmblstrp

lib/accessors/url-object.js

@@ -1,8 +1,14 @@
 'use strict'
 
-const parseUrl = require('url').parse
-const asUrlString = require('./url-string')
+const URL = require('url').URL
+const asString = require('./string')
 
 module.exports = function asUrlObject (raiseError, value) {
-  return parseUrl(asUrlString(raiseError, value))
+  const ret = asString(raiseError, value)
+
+  try {
+    return new URL(ret)
+  } catch (e) {
+    raiseError('should be a valid URL')
+  }
 }

lib/accessors/url-string.js

@@ -1,14 +1,7 @@
 'use strict'
 
-const isUrl = require('is-url')
-const asString = require('./string')
+const urlObject = require('./url-object')
 
 module.exports = function (raiseError, value) {
-  var ret = asString(raiseError, value)
-
-  if (!isUrl(ret)) {
-    raiseError('should be a valid URL')
-  }
-
-  return ret
+  return urlObject(raiseError, value).toString()
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "env-var",
-  "version": "4.1.0",
+  "version": "5.0.0",
   "description": "Verification, sanatization, and type coercion for environment variables in Node.js",
   "main": "env-var.js",
   "typings": "env-var.d.ts",
@@ -58,9 +58,6 @@
     "standard": "~12.0.1",
     "typescript": "~3.1.3"
   },
-  "dependencies": {
-    "is-url": "~1.2.2"
-  },
   "engines": {
     "node": ">=6.0"
   }

test/index.js

@@ -2,7 +2,8 @@
 
 /* eslint-env mocha */
 
-var expect = require('chai').expect
+const expect = require('chai').expect
+const URL = require('url').URL
 
 describe('env-var', function () {
   // Some default env vars for tests
@@ -22,7 +23,7 @@ describe('env-var', function () {
     ARRAY_WITH_DELIMITER: 'value,',
     ARRAY_WITH_DELIMITER_PREFIX: ',value',
     DASH_ARRAY: '1-2-3',
-    URL: 'http://google.com',
+    URL: 'http://google.com/',
     ENUM: 'VALID'
   }
 
@@ -107,8 +108,7 @@ describe('env-var', function () {
 
   describe('#asUrlObject', function () {
     it('should return a url object', function () {
-      expect(mod.get('URL').asUrlObject()).to.be.a('object')
-      expect(mod.get('URL').asUrlObject()).to.deep.equal(require('url').parse(process.env.URL))
+      expect(mod.get('URL').asUrlObject()).to.be.an.instanceOf(URL)
     })
 
     it('should throw due to bad url', function () {