stacktrace-gps
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.2 • Public • Published

    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!

    Install

    npm i stacktrace-gps

    DownloadsWeekly Downloads

    1,795,600

    Version

    3.1.2

    License

    MIT

    Unpacked Size

    166 kB

    Total Files

    11

    Last publish

    Collaborators

    • eriwen
    • niftylettuce
    • oliversalzburg
    • titanism