| 1 | # stack-utils
|
|---|
| 2 |
|
|---|
| 3 | > Captures and cleans stack traces.
|
|---|
| 4 |
|
|---|
| 5 | [](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)
|
|---|
| 6 |
|
|---|
| 7 |
|
|---|
| 8 | Extracted from `lib/stack.js` in the [`node-tap` project](https://github.com/tapjs/node-tap)
|
|---|
| 9 |
|
|---|
| 10 | ## Install
|
|---|
| 11 |
|
|---|
| 12 | ```
|
|---|
| 13 | $ npm install --save stack-utils
|
|---|
| 14 | ```
|
|---|
| 15 |
|
|---|
| 16 |
|
|---|
| 17 | ## Usage
|
|---|
| 18 |
|
|---|
| 19 | ```js
|
|---|
| 20 | const StackUtils = require('stack-utils');
|
|---|
| 21 | const stack = new StackUtils({cwd: process.cwd(), internals: StackUtils.nodeInternals()});
|
|---|
| 22 |
|
|---|
| 23 | console.log(stack.clean(new Error().stack));
|
|---|
| 24 | // outputs a beautified stack trace
|
|---|
| 25 | ```
|
|---|
| 26 |
|
|---|
| 27 |
|
|---|
| 28 | ## API
|
|---|
| 29 |
|
|---|
| 30 |
|
|---|
| 31 | ### new StackUtils([options])
|
|---|
| 32 |
|
|---|
| 33 | Creates a new `stackUtils` instance.
|
|---|
| 34 |
|
|---|
| 35 | #### options
|
|---|
| 36 |
|
|---|
| 37 | ##### internals
|
|---|
| 38 |
|
|---|
| 39 | Type: `array` of `RegularExpression`s
|
|---|
| 40 |
|
|---|
| 41 | A set of regular expressions that match internal stack stack trace lines which should be culled from the stack trace.
|
|---|
| 42 | The default is `StackUtils.nodeInternals()`, this can be disabled by setting `[]` or appended using
|
|---|
| 43 | `StackUtils.nodeInternals().concat(additionalRegExp)`. See also `ignoredPackages`.
|
|---|
| 44 |
|
|---|
| 45 | ##### ignoredPackages
|
|---|
| 46 |
|
|---|
| 47 | Type: `array` of `string`s
|
|---|
| 48 |
|
|---|
| 49 | An array of npm modules to be culled from the stack trace. This list will mapped to regular
|
|---|
| 50 | expressions and merged with the `internals`.
|
|---|
| 51 |
|
|---|
| 52 | Default `''`.
|
|---|
| 53 |
|
|---|
| 54 | ##### cwd
|
|---|
| 55 |
|
|---|
| 56 | Type: `string`
|
|---|
| 57 |
|
|---|
| 58 | The path to the current working directory. File names in the stack trace will be shown relative to this directory.
|
|---|
| 59 |
|
|---|
| 60 | ##### wrapCallSite
|
|---|
| 61 |
|
|---|
| 62 | Type: `function(CallSite)`
|
|---|
| 63 |
|
|---|
| 64 | 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.
|
|---|
| 65 |
|
|---|
| 66 |
|
|---|
| 67 | ### StackUtils.nodeInternals()
|
|---|
| 68 |
|
|---|
| 69 | Returns an array of regular expressions that be used to cull lines from the stack trace that reference common Node.js internal files.
|
|---|
| 70 |
|
|---|
| 71 |
|
|---|
| 72 | ### stackUtils.clean(stack, indent = 0)
|
|---|
| 73 |
|
|---|
| 74 | Cleans up a stack trace by deleting any lines that match the `internals` passed to the constructor, and shortening file names relative to `cwd`.
|
|---|
| 75 |
|
|---|
| 76 | Returns a `string` with the cleaned up stack (always terminated with a `\n` newline character).
|
|---|
| 77 | Spaces at the start of each line are trimmed, indentation can be added by setting `indent` to the desired number of spaces.
|
|---|
| 78 |
|
|---|
| 79 | #### stack
|
|---|
| 80 |
|
|---|
| 81 | *Required*
|
|---|
| 82 | Type: `string` or an `array` of `string`s
|
|---|
| 83 |
|
|---|
| 84 |
|
|---|
| 85 | ### stackUtils.capture([limit], [startStackFunction])
|
|---|
| 86 |
|
|---|
| 87 | 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).
|
|---|
| 88 |
|
|---|
| 89 | #### limit
|
|---|
| 90 |
|
|---|
| 91 | Type: `number`
|
|---|
| 92 | Default: `Infinity`
|
|---|
| 93 |
|
|---|
| 94 | Limits the number of lines returned by dropping all lines in excess of the limit. This removes lines from the stack trace.
|
|---|
| 95 |
|
|---|
| 96 | #### startStackFunction
|
|---|
| 97 |
|
|---|
| 98 | Type: `function`
|
|---|
| 99 |
|
|---|
| 100 | 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.
|
|---|
| 101 |
|
|---|
| 102 |
|
|---|
| 103 | ### stackUtils.captureString([limit], [startStackFunction])
|
|---|
| 104 |
|
|---|
| 105 | 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`.
|
|---|
| 106 |
|
|---|
| 107 |
|
|---|
| 108 | ### stackUtils.at([startStackFunction])
|
|---|
| 109 |
|
|---|
| 110 | 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).
|
|---|
| 111 |
|
|---|
| 112 | The available properties are:
|
|---|
| 113 |
|
|---|
| 114 | - `line`: `number`
|
|---|
| 115 | - `column`: `number`
|
|---|
| 116 | - `file`: `string`
|
|---|
| 117 | - `constructor`: `boolean`
|
|---|
| 118 | - `evalOrigin`: `string`
|
|---|
| 119 | - `native`: `boolean`
|
|---|
| 120 | - `type`: `string`
|
|---|
| 121 | - `function`: `string`
|
|---|
| 122 | - `method`: `string`
|
|---|
| 123 |
|
|---|
| 124 | ### stackUtils.parseLine(line)
|
|---|
| 125 |
|
|---|
| 126 | Parses a `string` (which should be a single line from a stack trace), and generates an object with the following properties:
|
|---|
| 127 |
|
|---|
| 128 | - `line`: `number`
|
|---|
| 129 | - `column`: `number`
|
|---|
| 130 | - `file`: `string`
|
|---|
| 131 | - `constructor`: `boolean`
|
|---|
| 132 | - `evalOrigin`: `string`
|
|---|
| 133 | - `evalLine`: `number`
|
|---|
| 134 | - `evalColumn`: `number`
|
|---|
| 135 | - `evalFile`: `string`
|
|---|
| 136 | - `native`: `boolean`
|
|---|
| 137 | - `function`: `string`
|
|---|
| 138 | - `method`: `string`
|
|---|
| 139 |
|
|---|
| 140 |
|
|---|
| 141 | ## License
|
|---|
| 142 |
|
|---|
| 143 | MIT © [Isaac Z. Schlueter](http://github.com/isaacs), [James Talmage](http://github.com/jamestalmage)
|
|---|
