1 | # stack-trace
|
2 |
|
3 | Get v8 stack traces as an array of CallSite objects.
|
4 |
|
5 | ## Install
|
6 |
|
7 | ``` bash
|
8 | npm install stack-trace
|
9 | ```
|
10 |
|
11 | ## Usage
|
12 |
|
13 | The stack-trace module makes it easy for you to capture the current stack:
|
14 |
|
15 | ``` javascript
|
16 | var stackTrace = require('stack-trace');
|
17 | var trace = stackTrace.get();
|
18 |
|
19 | require('assert').strictEqual(trace[0].getFileName(), __filename);
|
20 | ```
|
21 |
|
22 | However, sometimes you have already popped the stack you are interested in,
|
23 | and all you have left is an `Error` object. This module can help:
|
24 |
|
25 | ``` javascript
|
26 | var stackTrace = require('stack-trace');
|
27 | var err = new Error('something went wrong');
|
28 | var trace = stackTrace.parse(err);
|
29 |
|
30 | require('assert').strictEqual(trace[0].getFileName(), __filename);
|
31 | ```
|
32 |
|
33 | Please note that parsing the `Error#stack` property is not perfect, only
|
34 | certain properties can be retrieved with it as noted in the API docs below.
|
35 |
|
36 | ## Long stack traces
|
37 |
|
38 | stack-trace works great with [long-stack-traces][], when parsing an `err.stack`
|
39 | that has crossed the event loop boundary, a `CallSite` object returning
|
40 | `'----------------------------------------'` for `getFileName()` is created.
|
41 | All other methods of the event loop boundary call site return `null`.
|
42 |
|
43 | [long-stack-traces]: https://github.com/tlrobinson/long-stack-traces
|
44 |
|
45 | ## API
|
46 |
|
47 | ### stackTrace.get([belowFn])
|
48 |
|
49 | Returns an array of `CallSite` objects, where element `0` is the current call
|
50 | site.
|
51 |
|
52 | When passing a function on the current stack as the `belowFn` parameter, the
|
53 | returned array will only include `CallSite` objects below this function.
|
54 |
|
55 | ### stackTrace.parse(err)
|
56 |
|
57 | Parses the `err.stack` property of an `Error` object into an array compatible
|
58 | with those returned by `stackTrace.get()`. However, only the following methods
|
59 | are implemented on the returned `CallSite` objects.
|
60 |
|
61 | * getTypeName
|
62 | * getFunctionName
|
63 | * getMethodName
|
64 | * getFileName
|
65 | * getLineNumber
|
66 | * getColumnNumber
|
67 | * isNative
|
68 |
|
69 | Note: Except `getFunctionName()`, all of the above methods return exactly the
|
70 | same values as you would get from `stackTrace.get()`. `getFunctionName()`
|
71 | is sometimes a little different, but still useful.
|
72 |
|
73 | ### CallSite
|
74 |
|
75 | The official v8 CallSite object API can be found [here][v8stackapi]. A quick
|
76 | excerpt:
|
77 |
|
78 | > A CallSite object defines the following methods:
|
79 | >
|
80 | > * **getThis**: returns the value of this
|
81 | > * **getTypeName**: returns the type of this as a string. This is the name of the function stored in the constructor field of this, if available, otherwise the object's [[Class]] internal property.
|
82 | > * **getFunction**: returns the current function
|
83 | > * **getFunctionName**: returns the name of the current function, typically its name property. If a name property is not available an attempt will be made to try to infer a name from the function's context.
|
84 | > * **getMethodName**: returns the name of the property of this or one of its prototypes that holds the current function
|
85 | > * **getFileName**: if this function was defined in a script returns the name of the script
|
86 | > * **getLineNumber**: if this function was defined in a script returns the current line number
|
87 | > * **getColumnNumber**: if this function was defined in a script returns the current column number
|
88 | > * **getEvalOrigin**: if this function was created using a call to eval returns a CallSite object representing the location where eval was called
|
89 | > * **isToplevel**: is this a toplevel invocation, that is, is this the global object?
|
90 | > * **isEval**: does this call take place in code defined by a call to eval?
|
91 | > * **isNative**: is this call in native V8 code?
|
92 | > * **isConstructor**: is this a constructor call?
|
93 |
|
94 | [v8stackapi]: http://code.google.com/p/v8/wiki/JavaScriptStackTraceApi
|
95 |
|
96 | ## License
|
97 |
|
98 | stack-trace is licensed under the MIT license.
|