feat(CordovaError): support for error cause & more

This commit bases CordovaError on the popular joyent/node-verror.

We actually use @netflix/nerror, a VError fork for now. That's because
we do not want printf style error formatting support and that forks
allows to disable it. There's [ongoing work][1] to integrate that change
into the original VError.

So basically CordovaError behaves like PError but with all the static
methods from VError and different parameter ordering for its
constructor.

One change that could break some existing tests in repositories that use
cordova-common is that `toString` (for errors without a cause argument)
now behaves like the Error default again:

    new CordovaError('foo').toString();
    // old result: 'foo'
    // new result: 'CordovaError: foo'

[1]: TritonDataCenter/node-verror#63 (comment)

Author: raphinesse

package.json

@@ -23,6 +23,7 @@
     "cover": "nyc npm run test:unit"
   },
   "dependencies": {
+    "@netflix/nerror": "^1.1.3",
     "ansi": "^0.3.1",
     "bplist-parser": "^0.2.0",
     "cross-spawn": "^6.0.5",

spec/CordovaError/CordovaError.spec.js

@@ -17,7 +17,8 @@
     under the License.
 */
 
-var CordovaError = require('../../src/CordovaError/CordovaError');
+const endent = require('endent');
+const CordovaError = require('../../src/CordovaError/CordovaError');
 
 describe('CordovaError class', function () {
     it('Test 001 : should be constructable', function () {
@@ -26,6 +27,33 @@ describe('CordovaError class', function () {
 
     it('Test 003 : toString works', function () {
         var error003_1 = new CordovaError('error');
-        expect(error003_1.toString()).toEqual('error');
+        expect(error003_1.toString()).toEqual('CordovaError: error');
+    });
+
+    describe('given a cause', () => {
+        let error, cause;
+
+        beforeEach(() => {
+            cause = new Error('cause');
+            error = new CordovaError('error', cause);
+        });
+
+        it('should save it', () => {
+            expect(CordovaError.cause(error)).toBe(cause);
+        });
+
+        it('should include the cause in toString result', () => {
+            expect(error.toString()).toEqual(`CordovaError: error: cause`);
+        });
+
+        it('should include the cause stack in valueOf result', () => {
+            cause.stack = 'CAUSE_STACK';
+            error.stack = 'ERROR_STACK';
+
+            expect(CordovaError.fullStack(error)).toEqual(endent`
+                ERROR_STACK
+                caused by: CAUSE_STACK
+            `);
+        });
     });
 });

src/CordovaError/CordovaError.js

@@ -17,30 +17,28 @@
     under the License.
 */
 
+const VError = require('@netflix/nerror');
+
 /**
- * A derived exception class
- *
- * Based on: https://stackoverflow.com/a/8460753/380229
+ * A custom exception class derived from VError
  */
-class CordovaError extends Error {
+class CordovaError extends VError {
     /**
      * Creates new CordovaError with given error message
      *
      * @param {String} message Error message
+     * @param {Error|VErrorOptions} causeOrOpts
+     *     The Error that caused this to be thrown or a VErrorOptions object
      */
-    constructor (message) {
-        super(message);
-        Error.captureStackTrace(this, this.constructor);
-        this.name = this.constructor.name;
-    }
+    constructor (message, causeOrOpts = {}) {
+        const defaults = { name: 'CordovaError' };
+        const overrides = { strict: false, skipPrintf: true };
+        const userOpts = causeOrOpts instanceof Error
+            ? { cause: causeOrOpts }
+            : causeOrOpts;
+        const opts = Object.assign(defaults, userOpts, overrides);
 
-    /**
-     * Converts this to its string representation
-     *
-     * @return {String} Stringified error representation
-     */
-    toString () {
-        return this.message;
+        super(opts, message);
     }
 }