160 lines
4.8 KiB
Markdown
160 lines
4.8 KiB
Markdown
# stack-chain [](http://travis-ci.org/AndreasMadsen/stack-chain)
|
|
|
|
> API for combining call site modifyers
|
|
|
|
## Installation
|
|
|
|
```sheel
|
|
npm install stack-chain
|
|
```
|
|
## API documentation
|
|
|
|
```JavaScript
|
|
var chain = require('stack-chain');
|
|
```
|
|
|
|
When the `Error.stack` getter is executed, the `stack-chain` will perform the
|
|
following:
|
|
|
|
1. execute the `modifiers` attached by `chain.extend`.
|
|
2. execute the `modifiers` attached by `chain.filter`.
|
|
3. execute the `formater` set by `chain.format.replace`.
|
|
|
|
### chain.extend.attach(modifier)
|
|
### chain.filter.attach(modifier)
|
|
|
|
Will modify the callSite array. Note you shouldn't format the stack trace.
|
|
|
|
The `modifier` is a function there takes two arguments `error` and `frames`.
|
|
|
|
* `error` is the `Error` object.
|
|
* `frames` is an array of `callSite` objects, see
|
|
[v8 documentation](https://github.com/v8/v8/wiki/Stack-Trace-API)
|
|
for details.
|
|
|
|
When the `modifier` is done, it should `return` a modified `frames` array.
|
|
|
|
```JavaScript
|
|
chain.filter.attach(function (error, frames) {
|
|
|
|
// Filter out traces related to this file
|
|
var rewrite = frames.filter(function (callSite) {
|
|
return callSite.getFileName() !== module.filename;
|
|
});
|
|
|
|
return rewrite;
|
|
});
|
|
```
|
|
|
|
### chain.extend.deattach(modifier)
|
|
### chain.filter.deattach(modifier)
|
|
|
|
Removes a `modifier` function from the list of `modifiers`.
|
|
|
|
```JavaScript
|
|
var modifier = function () {};
|
|
|
|
// Attach modifier function
|
|
chain.extend.attach(modifier);
|
|
|
|
// Deattach modifier function
|
|
chain.extend.deattach(modifier);
|
|
```
|
|
|
|
### chain.format.replace(formater)
|
|
|
|
Replaces the default v8 `formater`. The new `formater` takes a two arguments
|
|
`error` and `frames`.
|
|
|
|
* `error` is the `Error` object.
|
|
* `callSites` is an array of `callSite` objects, see
|
|
[v8 documentation](https://github.com/v8/v8/wiki/Stack-Trace-API)
|
|
for details.
|
|
|
|
When the `formater` is done, it should `return` a `string`. The `string` will
|
|
what `Error.stack` returns.
|
|
|
|
```JavaScript
|
|
chain.format.replace(function (error, frames) {
|
|
var lines = [];
|
|
|
|
lines.push(error.toString());
|
|
|
|
for (var i = 0; i < frames.length; i++) {
|
|
lines.push(" at " + frames[i].toString());
|
|
}
|
|
|
|
return lines.join("\n");
|
|
});
|
|
```
|
|
|
|
### chain.format.restore()
|
|
|
|
Will restore the default v8 `formater`. Note that dude to the nature of v8
|
|
`Error` objects, if one of the getters `Error.stack` or `Error.callSite` has
|
|
already executed, the value of `Error.stack` won't change.
|
|
|
|
### chain.callSite([options])
|
|
|
|
This will return the unmodified `callSite` array from the current tick. This
|
|
is a performance shortcut, as it does not require generating the `.stack`
|
|
string. This behaviour is different from the `Error().callSite` properties.
|
|
|
|
While this is mostly generating `callSite` in hot code, it can be useful to
|
|
do some modification on the array. The `options` object, supports the following:
|
|
|
|
```javascript
|
|
options = {
|
|
// (default false) run the extenders on the callSite array.
|
|
extend: true,
|
|
|
|
// (default false) run the filters on the callSite array.
|
|
filter: true,
|
|
|
|
// (default 0) before running extend or filter methods, slice of some of the
|
|
// end. This can be useful for hiding the place from where you called this
|
|
// function.
|
|
slice: 2
|
|
}
|
|
```
|
|
|
|
### chain.originalCallSite(error)
|
|
|
|
Returns the original `callSite` array.
|
|
|
|
### chain.mutatedCallSite(error)
|
|
|
|
Returns the mutated `callSite` array, that is after `extend` and `filter`
|
|
is applied. The array will not exceed the `Error.stackTraceLimit`.
|
|
|
|
### Error.stackTraceLimit
|
|
|
|
This limites the size of the `callSites` array. The default value is 10, and
|
|
can be set to any positive number including `Infinity`. See
|
|
[v8 documentation](https://github.com/v8/v8/wiki/Stack-Trace-API)
|
|
for details.
|
|
|
|
## License
|
|
|
|
**The software is license under "MIT"**
|
|
|
|
> Copyright (c) 2012 Andreas Madsen
|
|
>
|
|
> Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
> of this software and associated documentation files (the "Software"), to deal
|
|
> in the Software without restriction, including without limitation the rights
|
|
> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
> copies of the Software, and to permit persons to whom the Software is
|
|
> furnished to do so, subject to the following conditions:
|
|
>
|
|
> The above copyright notice and this permission notice shall be included in
|
|
> all copies or substantial portions of the Software.
|
|
>
|
|
> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
> THE SOFTWARE.
|