stacktrace-gps

What is stacktrace-gps?

The stacktrace-gps npm package is a library for enhancing JavaScript stack traces. It provides functionalities to map minified stack traces back to their original source locations, retrieve function names, and resolve source maps. This is particularly useful for debugging and error tracking in production environments where code is often minified.

What are stacktrace-gps's main functionalities?

Pinpointing Original Source Locations

This feature allows you to pinpoint the original source location of a stack frame. The `pinpoint` method takes a stack frame object and returns a promise that resolves to the original position in the source code.

const StackTraceGPS = require('stacktrace-gps');
const stackFrame = { fileName: 'http://example.com/app.min.js', lineNumber: 1, columnNumber: 32 };
const gps = new StackTraceGPS();
gps.pinpoint(stackFrame).then(function(originalPosition) {
  console.log(originalPosition);
}).catch(function(error) {
  console.error(error);
});

Getting Function Names

This feature allows you to retrieve the function name from a stack frame. The `findFunctionName` method takes a stack frame object and returns a promise that resolves to the function name.

const StackTraceGPS = require('stacktrace-gps');
const stackFrame = { fileName: 'http://example.com/app.min.js', lineNumber: 1, columnNumber: 32 };
const gps = new StackTraceGPS();
gps.findFunctionName(stackFrame).then(function(functionName) {
  console.log(functionName);
}).catch(function(error) {
  console.error(error);
});

Resolving Source Maps

This feature allows you to resolve source maps for a given stack frame. The `getMappedLocation` method takes a stack frame object and returns a promise that resolves to the mapped location in the source code.

const StackTraceGPS = require('stacktrace-gps');
const stackFrame = { fileName: 'http://example.com/app.min.js', lineNumber: 1, columnNumber: 32 };
const gps = new StackTraceGPS();
gps.getMappedLocation(stackFrame).then(function(mappedLocation) {
  console.log(mappedLocation);
}).catch(function(error) {
  console.error(error);
});

Other packages similar to stacktrace-gps

source-map

The source-map package provides a library for working with source maps. It allows you to parse, generate, and manipulate source maps, which can be used to map minified code back to its original source. Compared to stacktrace-gps, source-map offers more low-level control over source map manipulation but does not provide higher-level functionalities like finding function names.

stacktrace-js

The stacktrace-js package is a library for generating, parsing, and enhancing JavaScript stack traces. It provides functionalities to capture stack traces, map them to original source locations, and integrate with source maps. Compared to stacktrace-gps, stacktrace-js offers a more comprehensive solution for working with stack traces, including capturing stack traces and integrating with various error tracking services.

README

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

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.

• stackframe - StackFrame or like object

.getMappedLocation(stackframe) => Promise(StackFrame)

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

• stackframe - StackFrame or like object

Browser Support

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!