Skip to content
Turns partial code location into precise code location
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
dist
spec
.editorconfig
.gitignore
.jscsrc
.jshintrc
.npmignore
.travis.yml
CHANGELOG.md
LICENSE
README.md
bower.json
component.json
gulpfile.js
karma.conf.ci.js
karma.conf.js
package-lock.json
package.json
polyfills.js
stacktrace-gps.js

README.md

stacktrace-gps - Turn partial code location into precise code location

Build Status Coverage Status GitHub license

This library accepts a code location (in the form of a StackFrame) and returns a new StackFrame with a more accurate location (using source maps) and guessed function names.

This is primarily a browser-centric library, but can be used with node.js. See the Offline Usage section below.

Usage

var stackframe = new StackFrame({fileName: 'http://localhost:3000/file.min.js', lineNumber: 1, columnNumber: 3284});
var callback = function myCallback(foundFunctionName) { console.log(foundFunctionName); };

// Such meta. Wow
var errback = function myErrback(error) { console.log(StackTrace.fromError(error)); };

var gps = new StackTraceGPS();

// Pinpoint actual function name and source-mapped location
gps.pinpoint(stackframe).then(callback, errback);
//===> Promise(StackFrame({functionName: 'fun', fileName: 'file.js', lineNumber: 203, columnNumber: 9}), Error)

// Better location/name information from source maps
gps.getMappedLocation(stackframe).then(callback, errback);
//===> Promise(StackFrame({fileName: 'file.js', lineNumber: 203, columnNumber: 9}), Error)

// Get function name from location information
gps.findFunctionName(stackframe).then(callback, errback);
//===> Promise(StackFrame({functionName: 'fun', fileName: 'http://localhost:3000/file.min.js', lineNumber: 1, columnNumber: 3284}), Error)

Offline Usage

With a bit of preparation, you can use this library offline in any environment. Any encountered fileNames not in the cache return resolved Promises with the original StackFrame. StackTraceGPS will make a best effort to provide as good of response with what is given and will fallback to the original StackFrame if nothing better could be found.

var stack = ErrorStackParser.parse(new Error('boom'));
console.assert(stack[0] == new StackFrame({fileName: 'http://localhost:9999/file.min.js', lineNumber: 1, columnNumber: 32}));

var sourceCache = {'http://localhost:9999/file.min.js': 'var foo=function(){};function bar(){}var baz=eval("XXX");\n//# sourceMappingURL=file.js.map'};
var sourceMap = '{"version":3,"sources":["./file.js"],"sourceRoot":"http://localhost:4000/","names":["foo","bar","baz","eval"],"mappings":"AAAA,GAAIA,KAAM,YACV,SAASC,QACT,GAAIC,KAAMC,KAAK","file":"file.min.js"}';
var sourceMapConsumerCache = {'http://localhost:4000/file.js.map': new SourceMap.SourceMapConsumer(sourceMap)};

var gps = new StackTraceGPS({offline: true, sourceCache: sourceCache, sourceMapConsumerCache: sourceMapConsumerCache});
gps.pinpoint(stack[0]).then(function(betterStackFrame) {
    console.assert(betterStackFrame === new StackFrame({functionName: 'bar', fileName: 'http://localhost:9999/file.js', lineNumber: 2, columnNumber: 9}));
});

Installation

npm install stacktrace-gps
bower install stacktrace-gps
https://raw.githubusercontent.com/stacktracejs/stacktrace-gps/master/dist/stacktrace-gps.min.js

API

new StackTraceGPS(/*optional*/ options) => StackTraceGPS

options: Object

  • sourceCache: Object (String URL : String Source) - Pre-populate source cache to avoid network requests
  • sourceMapConsumerCache: Object (Source Mapping URL : SourceMap.SourceMapConsumer) - Pre-populate source cache to avoid network requests
  • offline: Boolean (default false) - Set to true to prevent all network requests
  • ajax: Function (String URL => Promise(responseText)) - Function to be used for making X-Domain requests
  • atob: Function (String => String) - Function to convert base64-encoded strings to their original representation

.pinpoint(stackframe) => Promise(StackFrame)

Enhance function name and use source maps to produce a better StackFrame.

  • stackframe - StackFrame or like object e.g. {fileName: 'path/to/file.js', lineNumber: 100, columnNumber: 5}

.findFunctionName(stackframe) => Promise(StackFrame)

Enhance function name and use source maps to produce a better StackFrame.

.getMappedLocation(stackframe) => Promise(StackFrame)

Enhance function name and use source maps to produce a better StackFrame.

Browser Support

Sauce Test Status

Functions that rely on Source Maps (pinpoint and getMappedLocation) require recent browsers.

Contributing

Want to be listed as a Contributor? Start with the Contributing Guide!

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.