|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132 |
- # stack-utils
-
- > Captures and cleans stack traces.
-
- [](https://travis-ci.org/tapjs/stack-utils) [](https://ci.appveyor.com/project/jamestalmage/stack-utils-oiw96/branch/master) [](https://coveralls.io/github/tapjs/stack-utils?branch=master)
-
-
- Extracted from `lib/stack.js` in the [`node-tap` project](https://github.com/tapjs/node-tap)
-
- ## Install
-
- ```
- $ npm install --save stack-utils
- ```
-
-
- ## Usage
-
- ```js
- const StackUtils = require('stack-utils');
- const stack = new StackUtils({cwd: process.cwd(), internals: StackUtils.nodeInternals()});
-
- console.log(stack.clean(new Error().stack));
- // outputs a beautified stack trace
- ```
-
-
- ## API
-
-
- ### new StackUtils([options])
-
- Creates a new `stackUtils` instance.
-
- #### options
-
- ##### internals
-
- Type: `array` of `RegularExpression`s
-
- A set of regular expressions that match internal stack stack trace lines which should be culled from the stack trace.
- `StackUtils.nodeInternals()` returns a relatively set of sensible defaults for use on the node platform.
-
- ##### cwd
-
- Type: `string`
-
- The path to the current working directory. File names in the stack trace will be shown relative to this directory.
-
- ##### wrapCallSite
-
- Type: `function(CallSite)`
-
- A mapping function for manipulating CallSites before processing. The first argument is a CallSite instance, and the function should return a modified CallSite. This is useful for providing source map support.
-
-
- ### StackUtils.nodeInternals()
-
- Returns an array of regular expressions that be used to cull lines from the stack trace that reference common Node.js internal files.
-
-
- ### stackUtils.clean(stack)
-
- Cleans up a stack trace by deleting any lines that match the `internals` passed to the constructor, and shortening file names relative to `cwd`.
-
- Returns a `string` with the cleaned up stack (always terminated with a `\n` newline character).
-
- #### stack
-
- *Required*
- Type: `string` or an `array` of `string`s
-
-
- ### stackUtils.capture([limit], [startStackFunction])
-
- Captures the current stack trace, returning an array of `CallSite`s. There are good overviews of the available CallSite methods [here](https://github.com/v8/v8/wiki/Stack%20Trace%20API#customizing-stack-traces), and [here](https://github.com/sindresorhus/callsites#api).
-
- #### limit
-
- Type: `number`
- Default: `Infinity`
-
- Limits the number of lines returned by dropping all lines in excess of the limit. This removes lines from the stack trace.
-
- #### startStackFunction
-
- Type: `function`
-
- The function where the stack trace should start. The first line of the stack trace will be the function that called `startStackFunction`. This removes lines from the end of the stack trace.
-
-
- ### stackUtils.captureString([limit], [startStackFunction])
-
- Captures the current stack trace, cleans it using `stackUtils.clean(stack)`, and returns a string with the cleaned stack trace. It takes the same arguments as `stackUtils.capture`.
-
-
- ### stackUtils.at([startStackFunction])
-
- Captures the first line of the stack trace (or the first line after `startStackFunction` if supplied), and returns a `CallSite` like object that is serialization friendly (properties are actual values instead of getter functions).
-
- The available properties are:
-
- - `line`: `number`
- - `column`: `number`
- - `file`: `string`
- - `constructor`: `boolean`
- - `evalOrigin`: `string`
- - `native`: `boolean`
- - `typename`: `string`
- - `function`: `string`
- - `method`: `string`
-
- ### stackUtils.parseLine(line)
-
- Parses a `string` (which should be a single line from a stack trace), and generates an object with the following properties:
-
- - `line`: `number`
- - `column`: `number`
- - `file`: `string`
- - `constructor`: `boolean`
- - `evalOrigin`: `string`
- - `evalLine`: `number`
- - `evalColumn`: `number`
- - `evalFile`: `string`
- - `native`: `boolean`
- - `function`: `string`
- - `method`: `string`
-
-
- ## License
-
- MIT © [Isaac Z. Schlueter](http://github.com/isaacs), [James Talmage](http://github.com/jamestalmage)
|
