Add option to skip more frames using report (#58)

New options parameter on report() for per-call config.

Add skipLocalFrames option to trim the head of a locally generated
stacktrace to remove more than one level.

Enforce valid jsdoc using eslint and add params for test helpers.

Add documentation for passing options to report().

Author: bz2

.eslintrc.json

@@ -46,7 +46,10 @@
     }],
     "spaced-comment": ["error", "always"],
     "switch-colon-spacing": "error",
-    "unicode-bom": ["error", "never"]
+    "unicode-bom": ["error", "never"],
+    "valid-jsdoc": ["error", {
+      "requireReturn": false
+    }]
   },
   "overrides": [{
     "files": ["test/*.js"],

README.md

@@ -79,7 +79,7 @@ window.addEventListener('DOMContentLoaded', function() {
     version: '<my-service-version>',            // (optional)
     // reportUncaughtExceptions: false          // (optional) Set to false to stop reporting unhandled exceptions.
     // reportUnhandledPromiseRejections: false  // (optional) Set to false to stop reporting unhandled promise rejections.
-    // disabled: true                           // (optional) Set to true to not report errors when calling report(), this can be used when developping locally.
+    // disabled: true                           // (optional) Set to true to not report errors when calling report(), this can be used when developing locally.
     // context: {user: 'user1'}                 // (optional) You can set the user later using setUser()
   });
 });
@@ -228,13 +228,28 @@ Consumption of the errorHandlerUtility would essentially follow the following pa
 // MyComponent.jsx
 import errorHandler from './errorHandlerUtility';
 
-// Some example code that throws an error
-.catch(error) {
+try {
+  someFunctionThatThrows();
+} catch (error) {
   errorHandler.report(error);
 }
 
 ```
 
+If the call to report has additional levels of wrapping code, extra
+frames can be trimmed from the top of generated stacks by using a
+number greater than one for the `skipLocalFrames` option:
+
+```javascript
+import errorHandler from './errorHandlerUtility';
+
+function backendReport (string) {
+  // Skipping the two frames, for report() and for backendReport()
+  errorHandler.report(error, {skipLocalFrames: 2});
+}
+
+```
+
 ## FAQ
 
 **Q: Should I use this code in my production application?** A: This is an experimental library provided without any guarantee or official support. We do not recommend using it on production without performing a review of its code.

stackdriver-errors.js

@@ -93,15 +93,18 @@
   /**
    * Report an error to the Stackdriver Error Reporting API
    * @param {Error|String} err - The Error object or message string to report.
+   * @param {Object} options - Configuration for this report.
+   * @param {number} [options.skipLocalFrames=1] - Omit number of frames if creating stack.
    * @returns {Promise} A promise that completes when the report has been sent.
    */
-  StackdriverErrorReporter.prototype.report = function(err) {
+  StackdriverErrorReporter.prototype.report = function(err, options) {
     if (this.disabled) {
       return Promise.resolve(null);
     }
     if (!err) {
       return Promise.reject(new Error('no error to report'));
     }
+    options = options || {};
 
     var payload = {};
     payload.serviceContext = this.serviceContext;
@@ -120,7 +123,7 @@
         err = e;
       }
       // the first frame when using report() is always this library
-      firstFrameIndex = 1;
+      firstFrameIndex = options.skipLocalFrames || 1;
     }
     var that = this;
     // This will use sourcemaps and normalize the stack frames

test/test.js

@@ -21,6 +21,7 @@ var WAIT_FOR_STACKTRACE_FROMERROR = 15;
 
 /**
  * Helper function testing if a given message has been reported
+ * @param {string} [message] - Substring that message must contain.
  */
 function expectRequestWithMessage(message) {
   expect(requests.length).to.equal(1);
@@ -31,6 +32,7 @@ function expectRequestWithMessage(message) {
 
 /**
  * Helper for testing call stack reporting
+ * @param {string} [message] - Contents of error to throw.
  */
 function throwError(message) {
   throw new TypeError(message);
@@ -129,6 +131,26 @@ describe('Reporting errors', function() {
       });
     });
 
+    it('should include report origin by default', function() {
+      var helper = function helperFn(handler) {
+        return handler.report('common message');
+      };
+      return helper(errorHandler).then(function() {
+        expectRequestWithMessage(': common message\n    at helperFn (');
+      });
+    });
+
+    it('should skip number of frames if option is given', function() {
+      var helper = function outerFn(handler) {
+        return (function innerFn() {
+          return handler.report('common message', {skipLocalFrames: 2});
+        })();
+      };
+      return helper(errorHandler).then(function() {
+        expectRequestWithMessage(': common message\n    at outerFn (');
+      });
+    });
+
     it('should extract and send stack traces from Errors', function() {
       var message = 'custom message';
       // Throw and catch error to attach a stacktrace