Add StackTrace.report() for easy stack reporting.

Author: eriwen

README.md

@@ -67,7 +67,8 @@ StackTrace.deinstrument(interestingFn)
 ```
 npm install stacktrace-js
 bower install stacktrace-js
-https://cdnjs.cloudflare.com/ajax/libs/stacktrace.js/1.0.0/stacktrace.min.js
+component install stacktracejs/stacktrace.js
+http://cdnjs.com/libraries/stacktrace.js
 ```
 
 ## API
@@ -99,18 +100,35 @@ Use [stack-generator](https://github.com/stacktracejs/stack-generator) to genera
 * *sourceCache: Object (String URL => String Source)* - Pre-populate source cache to avoid network requests
 * *offline: Boolean (default: false)* - Set to `true` to prevent all network requests
 
-#### `StackTrace.instrument(fn, callback, /*optional*/ errback)` => Boolean
-Call callback with a _stack trace_ anytime `fn` is called. Returns `true` if given Function is successfully instrumented
+#### `StackTrace.instrument(fn, callback, /*optional*/ errback)` => Function
+* Given a function, wrap it such that invocations trigger a callback that is called with a stack trace.
 
 * **fn: Function** - to wrap, call callback on invocation and call-through
 * **callback: Function** - to call with stack trace (generated by `StackTrace.get()`) when fn is called
 * **(Optional) errback: Function** - to call with Error object if there was a problem getting a stack trace. 
 Fails silently (though `fn` is still called) if a stack trace couldn't be generated.
 
-#### `StackTrace.deinstrument(fn)` => Boolean
-Remove StackTrace instrumentation on `fn`. Returns `true` if de-instrumentation succeeds.
+#### `StackTrace.deinstrument(fn)` => Function
+Given a function that has been instrumented, revert the function to it's original (non-instrumented) state.
 
-* **fn: Function** - Previously wrapped Function
+* **fn: Function** - Instrumented Function
+
+#### `StackTrace.report(stackframes, url)` => [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)(String)
+Given an Array of StackFrames, serialize and POST to given URL. Promise is resolved with response text from POST request.
+
+Example JSON POST data:
+```
+{
+  stack: [
+    {functionName: 'fn', fileName: 'file.js', lineNumber: 32, columnNumber: 1},
+    {functionName: 'fn2', fileName: 'file.js', lineNumber: 543, columnNumber: 32},
+    {functionName: 'fn3', fileName: 'file.js', lineNumber: 8, columnNumber: 1}
+  ]
+}
+```
+
+* **stackframes: Array([StackFrame](https://github.com/stacktracejs/stackframe))** - Previously wrapped Function
+* **url: String** - URL to POST stack JSON to
 
 ## Browser Support
 * Chrome 1+

spec/stacktrace-spec.js

@@ -24,7 +24,7 @@ describe('StackTrace', function () {
     describe('#get', function () {
         it('gets stacktrace from current location', function () {
             runs(function testStackTraceGet() {
-                StackTrace.get().then(callback, errback)['catch'](debugErrback);
+                StackTrace.get().then(callback, errback)['catch'](errback);
             });
             waits(100);
             runs(function () {
@@ -60,7 +60,7 @@ describe('StackTrace', function () {
             runs(function () {
                 server.respondWith('GET', 'http://path/to/file.js', [404, {'Content-Type': 'text/plain'}, '']);
                 StackTrace.fromError(Errors.IE_11)
-                    .then(callback, debugErrback)['catch'](debugErrback);
+                    .then(callback, errback)['catch'](errback);
                 server.respond();
             });
             waits(100);
@@ -81,7 +81,7 @@ describe('StackTrace', function () {
 
                 server.respondWith('GET', 'http://path/to/file.js', [404, {'Content-Type': 'text/plain'}, '']);
                 StackTrace.fromError(Errors.IE_11, {filter: onlyFoos})
-                    .then(callback, debugErrback)['catch'](debugErrback);
+                    .then(callback, errback)['catch'](errback);
                 server.respond();
             });
             waits(100);
@@ -103,7 +103,7 @@ describe('StackTrace', function () {
                 server.respondWith('GET', 'test.js.map', [200, {'Content-Type': 'application/json'}, sourceMap]);
 
                 var stack = 'TypeError: Unable to get property \'undef\' of undefined or null reference\n   at foo (http://path/to/file.js:45:13)';
-                StackTrace.fromError({stack: stack}).then(callback, errback)['catch'](debugErrback);
+                StackTrace.fromError({stack: stack}).then(callback, errback)['catch'](errback);
                 server.respond();
             });
             waits(100);
@@ -129,7 +129,7 @@ describe('StackTrace', function () {
                         stackFrame.getFunctionName().indexOf('testGenerateArtificially') > -1;
                 };
                 StackTrace.generateArtificially({filter: stackFrameFilter})
-                    .then(callback, errback)['catch'](debugErrback);
+                    .then(callback, errback)['catch'](errback);
             });
             waits(100);
             runs(function () {
@@ -209,4 +209,47 @@ describe('StackTrace', function () {
             expect(unwrapped).toEqual(interestingFn);
         });
     });
+
+    describe('#report', function () {
+        var server;
+        beforeEach(function () {
+            server = sinon.fakeServer.create();
+        });
+        afterEach(function () {
+            server.restore();
+        });
+
+        it('sends POST request to given URL', function () {
+            var url = 'http://domain.ext/endpoint';
+            var stackframes = [new StackFrame('fn', undefined, 'file.js', 32, 1)];
+
+            runs(function () {
+                server.respondWith('POST', url, [201, {'Content-Type': 'text/plain'}, 'OK']);
+                StackTrace.report(stackframes, url).then(callback, errback)['catch'](errback);
+                server.respond();
+            });
+            waits(100);
+            runs(function () {
+                expect(server.requests[0].requestBody).toEqual({stack: stackframes});
+                expect(server.requests[0].url).toEqual(url);
+                expect(callback).toHaveBeenCalledWith('OK');
+                expect(errback).not.toHaveBeenCalled();
+            });
+        });
+
+        it('rejects if POST request fails', function () {
+            runs(function () {
+                var url = 'http://domain.ext/endpoint';
+                var stackframes = [new StackFrame('fn', undefined, 'file.js', 32, 1)];
+                server.respondWith('POST', url, [404, {'Content-Type': 'text/plain'}, '']);
+                StackTrace.report(stackframes, url).then(callback, errback)['catch'](errback);
+                server.respond();
+            });
+            waits(100);
+            runs(function () {
+                expect(callback).not.toHaveBeenCalled();
+                expect(errback).toHaveBeenCalled();
+            });
+        });
+    });
 });

stacktrace.js

@@ -155,6 +155,31 @@
                 // Function not instrumented, return original
                 return fn;
             }
+        },
+
+        /**
+         * Given an Array of StackFrames, serialize and POST to given URL.
+         *
+         * @param stackframes - Array[StackFrame]
+         * @param url - URL as String
+         */
+        report: function StackTrace$$report(stackframes, url) {
+            return new Promise(function (resolve, reject) {
+                var req = new XMLHttpRequest();
+                req.onerror = reject;
+                req.onreadystatechange = function onreadystatechange() {
+                    if (req.readyState === 4) {
+                        if (req.status >= 200 && req.status < 400) {
+                            resolve(req.responseText);
+                        } else {
+                            reject(new Error('POST to ' + url + ' failed with status: ' + req.status));
+                        }
+                    }
+                };
+                req.open('post', url);
+                req.setRequestHeader('Content-Type', 'application/json');
+                req.send({stack: stackframes});
+            });
         }
     };
 }));