stacktrace-gps

stacktrace-gps takes a StackFrame produced by a stack trace parser and resolves it against source maps to recover the original, pre-minification file name, line number, column number, and function name. It’s built by the stacktracejs project as the resolution layer under stacktrace.js, filling in what a raw error stack alone can’t tell you once code has been bundled, minified, or transpiled.

It works both online, fetching source files and .map files over XHR, and fully offline by pre-populating a source cache and SourceMapConsumer cache, which makes it usable in Node.js as well as browsers.

What You Get

• pinpoint() to combine location and function-name resolution into a single Promise-returning call
• getMappedLocation() to resolve a minified file/line/column back to the original source position via a source map
• findFunctionName() to guess the enclosing function name from source when no name mapping exists
• Offline mode with pluggable sourceCache and sourceMapConsumerCache objects for use outside a browser

Common Use Cases

• Enhancing browser error reports with original file, line, and function info before sending them to an error tracker
• Building custom source-map-aware crash-reporting pipelines
• Powering stacktrace.js’s automatic stack-frame enhancement feature
• Resolving stack frames offline in CI or test environments where source maps are pre-fetched

Under The Hood

Architecture The library is a single UMD module (stacktrace-gps.js) exposing one constructor, StackTraceGPS, alongside a handful of private helper functions (_xdr, _atob, _findFunctionName, _findSourceMappingURL, _extractLocationInfoFromSourceMapSource). Instance methods (pinpoint, getMappedLocation, findFunctionName, and the internal _get/_getSourceMapConsumer) are all Promise-based and layer cleanly: pinpoint calls getMappedLocation then findFunctionName, and getMappedLocation calls the shared _get fetch/cache helper before handing off to _getSourceMapConsumer and _extractLocationInfoFromSourceMapSource. In-flight fetches and SourceMapConsumer creation are memoized directly on this.sourceCache/this.sourceMapConsumerCache, so a file or map URL requested twice in parallel only hits the network once. There’s no framework or DI container here; it’s a small, self-contained resolution engine meant to be composed by callers like stacktrace.js.

Tech Stack Written in plain ES5 JavaScript with a UMD wrapper supporting AMD, CommonJS, and global-script consumption. Runtime dependencies are source-map (for SourceMapConsumer) and stackframe (for the StackFrame value object); es6-promise is a dev-only polyfill for older test targets. The build pipeline uses webpack and uglify-js to produce browser bundles in dist/, karma + jasmine/jasmine-ajax for cross-browser test execution (including a Sauce Labs matrix in CI), and a hand-authored stacktrace-gps.d.ts for TypeScript consumers even though the source itself isn’t TypeScript.

Code Quality Test coverage is extensive: spec/stacktrace-gps-spec.js exercises the constructor, request de-duplication, offline mode, malformed source maps, and each public method individually via Jasmine. CI (GitHub Actions) runs ESLint (eslint:recommended plus a strict 4-space/single-quote/semicolon style config) and the full Karma suite across real browsers through Sauce Labs, then reports coverage to Coveralls. Error handling is explicit throughout — helper functions throw typed Error/TypeError instances with specific messages (e.g. for malformed StackFrames or unsupported environments) rather than failing silently.

API Design The public surface is deliberately small: three Promise-returning methods plus a constructor with well-documented options (sourceCache, sourceMapConsumerCache, offline, ajax, atob). JSDoc comments precede nearly every function, and the README documents each option and method with runnable examples, including a complete offline-usage walkthrough. Getting started requires no configuration at all — new StackTraceGPS().pinpoint(stackframe) works out of the box in a browser — while advanced use (Node.js, offline, custom transport) is opt-in via constructor options rather than required boilerplate.