# stacktrace-gps

> Turns partial code location into precise code location

Latest version **3.1.2** (published 2022-06-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install stacktrace-gps
pnpm add stacktrace-gps
yarn add stacktrace-gps
bun add stacktrace-gps
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.1.2 |
| Published | 2022-06-06 |
| First published | 2014-10-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 161.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 127 |
| Maintainers | eriwen, niftylettuce, oliversalzburg, titanism |
| Keywords | stacktrace, error, debugger |

## Links

- npm: https://www.npmjs.com/package/stacktrace-gps
- Repository: https://github.com/stacktracejs/stacktrace-gps
- Homepage: https://www.stacktracejs.com
- Issues: https://github.com/stacktracejs/stacktrace-gps/issues
- npm.io page: https://npm.io/package/stacktrace-gps

## Dependencies (2)

- [source-map](https://npm.io/package/source-map.md) 0.5.6
- [stackframe](https://npm.io/package/stackframe.md) ^1.3.4

## Alternatives

- [@sentry/react-native](https://npm.io/package/@sentry/react-native.md) — 2.6M weekly downloads
- [@ardatan/aggregate-error](https://npm.io/package/@ardatan/aggregate-error.md) — 708.1K weekly downloads
- [custom-error-generator](https://npm.io/package/custom-error-generator.md) — 2.0K weekly downloads
- [@technik-sde/prosemirror-recreate-transform](https://npm.io/package/@technik-sde/prosemirror-recreate-transform.md) — 1.5K weekly downloads
- [@suchipi/error-utils](https://npm.io/package/@suchipi/error-utils.md) — 78 weekly downloads

## Recent versions

- 3.1.2 (latest) — 2022-06-06
- 2.4.0 (next) — 2016-01-06
- 3.1.1 — 2022-06-06
- 3.1.0 — 2022-06-06
- 3.0.4 — 2020-01-06
- 3.0.3 — 2019-09-18
- 3.0.2 — 2017-08-12
- 3.0.1 — 2017-04-30
- 3.0.0 — 2016-12-18
- 2.4.4 — 2016-05-17
- 2.4.3 — 2016-05-15
- 2.4.2 — 2016-05-08
- 2.4.1 — 2016-02-21
- 2.3.3 — 2015-11-22
- 2.3.2 — 2015-11-06
- … 17 more at https://npm.io/package/stacktrace-gps/versions

## README

stacktrace-gps - Turn partial code location into precise code location
===================
[![Build Status](https://img.shields.io/github/workflow/status/stacktracejs/stacktrace-gps/Continuous%20Integration/master?logo=github&style=flat-square)](https://github.com/stacktracejs/stacktrace-gps/actions?query=workflow%3AContinuous+Integration+branch%3Amaster)
[![Coverage Status](https://img.shields.io/coveralls/stacktracejs/stacktrace-gps.svg?style=flat-square)](https://coveralls.io/r/stacktracejs/stacktrace-gps?branch=master)
[![GitHub license](https://img.shields.io/github/license/stacktracejs/stacktrace-gps.svg?style=flat-square)](https://opensource.org/licenses/MIT)

This library accepts a code location (in the form of a [StackFrame](https://github.com/stacktracejs/stackframe)) and
returns a new StackFrame with a more accurate location (using [source maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/)) and guessed function names.

This is primarily a browser-centric library, but can be used with node.js. See the [Offline Usage section](#offline-usage) below.

## Usage
```js
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.

```js
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](https://github.com/stacktracejs/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](https://github.com/stacktracejs/stackframe) or like object

#### `.getMappedLocation(stackframe)` => Promise(StackFrame)
Enhance function name and use source maps to produce a better StackFrame.
* **stackframe** - [StackFrame](https://github.com/stacktracejs/stackframe) or like object

## Browser Support
[![Sauce Test Status](https://saucelabs.com/browser-matrix/stacktracejs.svg)](https://saucelabs.com/u/stacktracejs)

Functions that rely on [Source Maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/)
(`pinpoint` and `getMappedLocation`) require recent browsers.

## Contributing
Want to be listed as a *Contributor*? Start with the [Contributing Guide](.github/CONTRIBUTING.md)!

---
_Source: https://npm.io/package/stacktrace-gps · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._