stack-source-mapper

nodejs library to parse stack trace and map it with source maps to get meaningful error stack.

what it does

Any typescript web applications e.g. Angular is/should not deployed in production with source maps. Hence the exception stack in producton is unreadable and makes no sense.

we have two options in that case

$3

Angular applications you can build with "hidden" source maps where source maps are generated along with build but not visible to browser.

$3

Source maps are generated separately, hence the source map files names may not match with the prod build file names.

$3

In both these cases we need an an offline processing to convert the production stack to a meaningful development stack by mapping it to source maps.

This library does exactly that!!

How to use

``
import { mapStackTrace, parseStackTrace } from 'stack-source-mapper';

const stackStr =
TypeError: {}.helloWorld is not a function
at a.throwError (main.15600dbb30d4c3c4c884.js:1:196320)
at main.15600dbb30d4c3c4c884.js:1:213496
at nD (main.15600dbb30d4c3c4c884.js:1:59586)
at d (main.15600dbb30d4c3c4c884.js:1:59748)
..........
..........

;

const sourceMapLocation = .../location/...;

const result: string = await mapStackTrace(stackStr, sourceLocation, {
strict: false, sourceSnippet: true
});
console.log(result);

`
OR
`
const parsed = await parseStackTrace(stackStr);
const r = await mapStackTrace(parsed, sourceLocation, {strict: true, sourceSnippet: false});
console.log(r);

`

Library has two overloaded signatures
`
export async function mapStackTrace(
stackTrace: string,
sourceMapLocation: string,
options: MapStackOptions): Promise;

export async function mapStackTrace(
stackTrace: StackTraceFrame[],
sourceMapLocation: string,
options: MapStackOptions): Promise;

`

It returns a serialized dev stack mapped with sourcemaps if mapStackTrace is invoked with string. If you dont want a string and want to log the error the way you like, you can get the parsed stack back.

$3


`
export interface MapStackOptions {
strict: boolean;
sourceSnippet: boolean;
sourceLines?: number;
}

`
#### strict: true
to control the file name matching logic. If true library will try to find the source map file name which match exactly with the exception stack trace file name. Works when "Hidden" source maps are generated along with prod build.
#### strict: false
If false, libraries tries best effort to find the matching source map file. This is required in case the source maps are not generated with the prod build. Hence the source map file name may not be exactly same as prod build file names.

#### sourceSnippet
Try to add exception source code from source map.

#### sourceLines
how many source code lines to add. If number is 3, it adds 3 lines from top and 3 lines from bottom of the line where exception occured.

Example


`
const stackStr =
TypeError: {}.helloWorld is not a function
at a.throwError (main.15600dbb30d4c3c4c884.js:1:196320)
at main.15600dbb30d4c3c4c884.js:1:213496
at nD (main.15600dbb30d4c3c4c884.js:1:59586)
at d (main.15600dbb30d4c3c4c884.js:1:59748)
at HTMLButtonElement. (main.15600dbb30d4c3c4c884.js:1:117054)
at T.invokeTask (polyfills.bfdd93de4f99fb5503f5.js:1:7138)
at Object.onInvokeTask (main.15600dbb30d4c3c4c884.js:1:88522)
at T.invokeTask (polyfills.bfdd93de4f99fb5503f5.js:1:7059)
at I.runTask (polyfills.bfdd93de4f99fb5503f5.js:1:2533)
at m.invokeTask [as invoke] (polyfills.bfdd93de4f99fb5503f5.js:1:8189)
;
const sourceLocation = ${__dirname}/../../../packages/stack-source-mapper-test-app/src/example/app-source-maps/;

const result = await mapStackTrace(stackStr, sourceLocation, {strict: false, sourceSnippet: true});
console.log(result);

`
Result:
`
helloWorld -> ( webpack:///src/app/app.component.ts [14:6] )
--------------------source code -----------------
12: throwError() {
13: const x: any = {};
14: x.helloWorld();
15: }
16: }

ctx -> ( webpack:///src/app/app.component.html [491:19] )
--------------------source code -----------------
489:
490:
491: Throw Error
492:
493: