Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/felixge/node-stack-trace
Get v8 stack traces as an array of CallSite objects.
https://github.com/felixge/node-stack-trace
Last synced: 5 days ago
JSON representation
Get v8 stack traces as an array of CallSite objects.
- Host: GitHub
- URL: https://github.com/felixge/node-stack-trace
- Owner: felixge
- License: mit
- Created: 2011-06-25T15:52:22.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2023-03-06T02:28:43.000Z (almost 2 years ago)
- Last Synced: 2024-12-12T18:04:14.306Z (12 days ago)
- Language: JavaScript
- Homepage:
- Size: 1.46 MB
- Stars: 455
- Watchers: 7
- Forks: 41
- Open Issues: 23
-
Metadata Files:
- Readme: Readme.md
- License: License
Awesome Lists containing this project
README
# stack-trace
[](https://travis-ci.org/felixge/node-stack-trace)
Get v8 stack traces as an array of CallSite objects.
## Install
``` bash
npm install stack-trace
```
## Usage
The stack-trace module makes it easy for you to capture the current stack:
```javascript
import { get } from 'stack-trace';
const trace = get();
expect(trace[0].getFileName()).toBe(__filename);
```
However, sometimes you have already popped the stack you are interested in,
and all you have left is an `Error` object. This module can help:
```javascript
import { parse } from 'stack-trace';
const err = new Error('something went wrong');
const trace = parse(err);
expect(trace[0].getFileName()).toBe(__filename);
```
Please note that parsing the `Error#stack` property is not perfect, only
certain properties can be retrieved with it as noted in the API docs below.
## Long stack traces
stack-trace works great with [long-stack-traces][], when parsing an `err.stack`
that has crossed the event loop boundary, a `CallSite` object returning
`'----------------------------------------'` for `getFileName()` is created.
All other methods of the event loop boundary call site return `null`.
[long-stack-traces]: https://github.com/tlrobinson/long-stack-traces
## API
### stackTrace.get([belowFn])
Returns an array of `CallSite` objects, where element `0` is the current call
site.
When passing a function on the current stack as the `belowFn` parameter, the
returned array will only include `CallSite` objects below this function.
### stackTrace.parse(err)
Parses the `err.stack` property of an `Error` object into an array compatible
with those returned by `stackTrace.get()`. However, only the following methods
are implemented on the returned `CallSite` objects.
* getTypeName
* getFunctionName
* getMethodName
* getFileName
* getLineNumber
* getColumnNumber
* isNative
Note: Except `getFunctionName()`, all of the above methods return exactly the
same values as you would get from `stackTrace.get()`. `getFunctionName()`
is sometimes a little different, but still useful.
### CallSite
The official v8 CallSite object API can be found [here][https://github.com/v8/v8/wiki/Stack-Trace-API#customizing-stack-traces]. A quick
excerpt:
> A CallSite object defines the following methods:
>
> * **getThis**: returns the value of this
> * **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.
> * **getFunction**: returns the current function
> * **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.
> * **getMethodName**: returns the name of the property of this or one of its prototypes that holds the current function
> * **getFileName**: if this function was defined in a script returns the name of the script
> * **getLineNumber**: if this function was defined in a script returns the current line number
> * **getColumnNumber**: if this function was defined in a script returns the current column number
> * **getEvalOrigin**: if this function was created using a call to eval returns a CallSite object representing the location where eval was called
> * **isToplevel**: is this a toplevel invocation, that is, is this the global object?
> * **isEval**: does this call take place in code defined by a call to eval?
> * **isNative**: is this call in native V8 code?
> * **isConstructor**: is this a constructor call?
[v8stackapi]: https://v8.dev/docs/stack-trace-api
## License
stack-trace is licensed under the MIT license.