readme.md
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)