Package Exports

stacktracey

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (stacktracey) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

StackTracey

Platform-agnostic callstack access helper.

Why

Simple
Allows hiding library calls / ad-hoc exclusion (via // @hide marker)
Provides source text for call locations
Fetches sources synchronously, via get-source
Full sourcemap support

What for

Better exception reporting for Node and browsers
Advanced logging (displaying call locations)
Assertion printing

How to

npm install stacktracey

StackTracey = require ('stacktracey')

Captures current call stack:

stack = new StackTracey ()            // captures current call stack

Parses stacks from Error object:

stack = new StackTracey (error)       // parses error.stack
stack = new StackTracey (error.stack) // raw string

It is an array instance:

stack instanceof Array // returns true
stack.length           // num entries
stack[0]               // top

Each item exposes:

{
    beforeParse: <original text>,
    callee:      <function name>,
    calleeShort: <shortened function name>,
    file:        <full path to file>,       // e.g. /Users/john/my_project/src/foo.js
    fileShort:   <shortened path to file>,  // e.g. src/foo.js
    fileName:    <file name>',              // e.g. foo.js
    line:        <line number>,             // starts from 1
    column:      <column number>,           // starts from 1

    index:          /* true if occured in HTML file at index page   */,
    native:         /* true if occured in native browser code       */,
    thirdParty:     /* true if occured in library code              */,
    hide:           /* true if marked as hidden by "// @hide" tag   */
}

Accessing sources:

stack = stack.withSources // will return a copy of stack with all items supplied with sources
top   = stack[0]

top = stack.withSource (0) // supplies source for an individiual item

top = StackTracey.withSource (stack[0]) // supplies source for an individiual item

This will return item supplied with source code info (already mapped through sourcemaps):

{
    ... // all previous fields

    line:       <original line number>,
    column:     <original column number>,
    sourceFile: <original source file object>,
    sourceLine: <original source line text>
}

To learn about sourceFile object, read get-source docs.

Cleaning output

stack = stack.withSources.clean // it is better to call .clean on stacks supplied with sources, to make // @hide magic work

Merges repeated lines (via .mergeRepeatedLines)
Excludes locations marked with isThirdParty (library calls)
Excludes locations marked with // @hide comment (user defined exclusion)

You can override isThirdParty behaviour by replacing the predicate implementation:

StackTracey.isThirdParty = path => path.includes ('jquery')

Array methods

All StackTracey instances expose map, filter, concat and slice methods. These methods will return mapped, filtered, joined and sliced stacks, respectively.

s = new StackTracey ().slice (1).filter (x => !x.isThirdParty) // current stack shifted by 1 and cleaned from library class

s instanceof StackTracey // true
s instanceof Array       // true

Any other method of the Array is supported too, but they will return Array instances, not StackTracey instances. You can convert from array via this:

stack = new StackTracey (array)

..and to array via this (but generally this is not needed — you can pass around StackTracey instances as if they were real Arrays):

Array.from (stack)

Extra stuff

You can compare two locations via this predicate (tests file, line and column for equality):

StackTracey.locationsEqual (a, b)