• Stars
    star
    218
  • Rank 181,805 (Top 4 %)
  • Language
    JavaScript
  • License
    The Unlicense
  • Created over 8 years ago
  • Updated 9 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Parses call stacks. Reads sources. Clean & filtered output. Sourcemaps. Node & browsers.

StackTracey

Build Status Windows Build Status Coverage Status NPM Scrutinizer Code Quality dependencies Status

Parses call stacks. Reads sources. Clean & filtered output. Sourcemaps. Node & browsers.

Why

  • Simple
  • Works in Node and browsers, *nix and Windows
  • Allows hiding library calls / ad-hoc exclusion (via // @hide marker)
  • Provides source text for call locations
  • Fetches sources (via get-source)
  • Supports both asynchronous and synchronous interfaces (works even in browsers)
  • Full sourcemap support
  • Extracts useful information from SyntaxError instances
  • Pretty printing screen shot 2017-09-27 at 16 53 46

What For

How To

npm install stacktracey
import StackTracey from 'stacktracey'

Captures the current call stack:

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

Parses stacks from an Error object:

stack = new StackTracey (error)
stack = new StackTracey (error.stack) // ...or from raw string

Stores parsed data in .items:

stack.items.length // num entries
stack.items[0]     // top

...where each item exposes:

{
    beforeParse:  <original text>,
    callee:       <function name>,
    calleeShort:  <shortened function name>,
    file:         <full path to file>,       // e.g. /Users/john/my_project/node_modules/foobar/main.js
    fileRelative: <relative path to file>,   // e.g. node_modules/foobar/main.js
    fileShort:    <short path to file>,      // e.g. foobar/main.js
    fileName:     <file name>,               // e.g. main.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    */,
    syntaxError:    /* true if generated from a SyntaxError instance */
}

Accessing sources (synchronously, use with caution in browsers):

stack = stack.withSources () // returns a copy of stack with all items supplied with sources
top   = stack.items[0]       // top item

Accessing sources (asynchronously, preferred method in browsers):

stack = await stack.withSourcesAsync () // returns a copy of stack with all items supplied with sources
top   = stack.items[0]                  // top item

...or:

top = stack.withSourceAt (0) // supplies source for an individiual item (by index)
top = await stack.withSourceAsyncAt (0) // supplies source for an individiual item (by index)

...or:

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

The returned items contain the following additional fields (already mapped through sourcemaps):

{
    ... // all the previously described fields

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

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

Cleaning Output

Synchronously (use with caution in browsers):

stack = stack.clean ()

...or (asynchronously):

stack = await stack.cleanAsync ()

It does the following:

  1. Reads sources (if available)
  2. Excludes locations marked with the isThirdParty flag (library calls)
  3. Excludes locations marked with a // @hide comment (user defined exclusion)
  4. Merges repeated lines (via the .mergeRepeatedLines)

You can customize its behavior by overriding the isClean (entry, index) predicate.

Custom isThirdParty Predicate

You can override the isThirdParty behavior by subclassing StackTracey:

class MyStackTracey extends StackTracey {

    isThirdParty (path, externalDomain) {    // you can use externalDomain to include traces from libs from other domains
        return (super.isThirdParty (path)    // include default behavior
                || path.includes ('my-lib')) // paths including 'my-lib' will be marked as thirdParty
                && !path.includes ('jquery') // jquery paths won't be marked as thirdParty
    }
}

...

const stack = new MyStackTracey (error).withSources ()

Pretty Printing

const prettyPrintedString = new StackTracey (error).withSources ().asTable ()
const prettyPrintedString = (await new StackTracey (error).withSourcesAsync ()).asTable () // asynchronous version

...or (for pretty printing cleaned output):

const prettyPrintedString = new StackTracey (error).clean ().asTable ()
const prettyPrintedString = (await new StackTracey (error).cleanAsync ()).asTable () // asynchronous version

It produces a nice compact table layout (thanks to as-table), supplied with source lines (if available):

at shouldBeVisibleInStackTrace     test.js:25                 const shouldBeVisibleInStackTrace = () => new StackTracey ()
at it                              test.js:100                const stack = shouldBeVisibleInStackTrace ()                
at callFn                          mocha/lib/runnable.js:326  var result = fn.call(ctx);                                  
at run                             mocha/lib/runnable.js:319  callFn(this.fn);                                            
at runTest                         mocha/lib/runner.js:422    test.run(fn);                                               
at                                 mocha/lib/runner.js:528    self.runTest(function(err) {                                
at next                            mocha/lib/runner.js:342    return fn();                                                
at                                 mocha/lib/runner.js:352    next(suites.pop());                                         
at next                            mocha/lib/runner.js:284    return fn();                                                
at <anonymous>                     mocha/lib/runner.js:320    next(0);                  

If you find your pretty printed tables undesirably trimmed (or maybe too long to fit in the line), you can provide custom column widths when calling asTable (...or, alternatively, by overriding maxColumnWidths () method):

stack.asTable ({
    callee:     30,
    file:       60,
    sourceLine: 80
})

Using As A Custom Exception Printer In Node

You can even replace the default NodeJS exception printer with this! This is how you can do it:

process.on ('uncaughtException',  e => { /* print the stack here */ })
process.on ('unhandledRejection', e => { /* print the stack here */ })

But the most simple way to achieve that is to use the ololog library (that is built upon StackTracey and several other handy libraries coded by me). Check it out, it's pretty awesome and will blow your brains out :)

const log = require ('ololog').handleNodeErrors ()

// you can also print Errors by simply passing them to the log() function

screen shot 2018-05-11 at 19 51 03

Parsing SyntaxError instances

For example, when trying to require a file named test_files/syntax_error.js:

// next line contains a syntax error (not a valid JavaScript)
foo->bar ()

...the pretty printed call stack for the error thrown would be something like:

at (syntax error)                  test_files/syntax_error.js:2  foo->bar ()
at it                              test.js:184                   try { require ('./test_files/syntax_error.js') }
at runCallback                     timers.js:781
at tryOnImmediate                  timers.js:743
at processImmediate [as _immediat  timers.js:714

...where the first line is generated from parsing the raw output from the util.inspect call in Node. Unfortunately, this won't work in older versions of Node (v4 and below) as these versions can't provide any meaningful information for a SyntaxError instance.

Array Methods

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

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

s instanceof StackTracey // true

Extra Stuff

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

StackTracey.locationsEqual (a, b)

To force-reload the sources, you can invalidate the global source cache:

StackTracey.resetCache ()

Projects That Use StackTracey

  • Ololog β€” a better console.log for the log-driven debugging junkies!
  • CCXT β€” a cryptocurrency trading library that supports 130+ exchanges
  • pnpm β€” a fast, disk space efficient package manager (faster than npm and Yarn!)
  • panic-overlay β€” a lightweight standalone alternative to react-error-overlay

More Repositories

1

crx-hotreload

Chrome Extension Hot Reloader
JavaScript
851
star
2

ololog

A better console.log for the log-driven debugging junkies
JavaScript
215
star
3

ansicolor

A JavaScript ANSI color/style management. ANSI parsing. ANSI to CSS. Small, clean, no dependencies.
JavaScript
119
star
4

panic-overlay

Displays JS errors in browsers. Shows sources. Use with any framework. πŸ’₯✨
JavaScript
80
star
5

wyg

A new WYSIWYG editing experience for the modern web
JavaScript
76
star
6

as-table

A simple function that prints objects as ASCII tables. Supports ANSI styling and weird Unicode πŸ’© emojis – they won't break the layout.
JavaScript
62
star
7

expression

An interactive paint application driven by cellular automation (WebGL)
JavaScript
37
star
8

get-source

Fetch source-mapped sources. Peek by file, line, column. Node & browsers. Sync & async.
JavaScript
28
star
9

string.ify

A small, simple yet powerful JavaScript object stringifier / pretty-printer
JavaScript
26
star
10

what-code-is-faster

A browser-based tool for speedy and correct JS performance comparisons!
TypeScript
24
star
11

react-gpu

React WebGPU Renderer
TypeScript
24
star
12

life

A nice looking version of Life in WebGL
JavaScript
21
star
13

printable-characters

A little helper for handling strings containing zero width characters, ANSI styling, whitespaces, newlines, πŸ’©, etc.
JavaScript
19
star
14

pipez

Function sequencing reloaded
JavaScript
14
star
15

gop

Π“ΠžΠŸΠΠ˜Πš.EXE (Π’Π΅Π±-вСрсия)
JavaScript
14
star
16

git-slack-notify

Sends Slack notifications for new commits in Git repositories
JavaScript
13
star
17

mole

Mole Simulator
JavaScript
8
star
18

skychat

An example of WebRTC chat/paint app with distributed message history
HTML
8
star
19

es7-object-polyfill

A polyfill for missing Object.values / Object.entries
JavaScript
7
star
20

string.bullet

ASCII-mode bulleting for the list-style data
JavaScript
5
star
21

turing-2d

A toroidal turing machine (WebGL)
JavaScript
5
star
22

parcel-plugin-svg-react

Import SVG as React components (Parcel plugin)
JavaScript
5
star
23

chai-spies-decorators

Chai Spies + ES7 decorators
JavaScript
4
star
24

slack-js-console

A JavaScript interpreter for Slack channels
JavaScript
4
star
25

meta-fields

Meta-annotations for data structures in JavaScript
JavaScript
2
star
26

gop2

Π“ΠžΠŸΠΠ˜Πš-2.EXE
JavaScript
2
star
27

mutko

The simplest context menu translator for Chrome // WIP
JavaScript
2
star