# stack-utils

> Captures and cleans stack traces

Latest version **2.0.6** (published 2022-11-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install stack-utils
pnpm add stack-utils
yarn add stack-utils
bun add stack-utils
```

## Health

**Score 13/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score; declining downloads.

## Facts

| | |
|---|---|
| Version | 2.0.6 |
| Published | 2022-11-08 |
| First published | 2016-01-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/stack-utils) |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 1 |
| Unpacked size | 14.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 196 |
| Author | James Talmage |
| Maintainers | jamestalmage, isaacs |

## Links

- npm: https://www.npmjs.com/package/stack-utils
- Repository: https://github.com/tapjs/stack-utils
- Homepage: https://github.com/tapjs/stack-utils#readme
- Issues: https://github.com/tapjs/stack-utils/issues
- npm.io page: https://npm.io/package/stack-utils

## Dependencies (1)

- [escape-string-regexp](https://npm.io/package/escape-string-regexp.md) ^2.0.0

## Recent versions

- 2.0.6 (latest) — 2022-11-08
- 1.0.5 (v1-legacy) — 2021-04-05
- 2.0.5 — 2021-09-17
- 2.0.4 — 2021-09-14
- 1.0.4 — 2020-11-26
- 1.0.3 — 2020-11-13
- 2.0.3 — 2020-11-13
- 2.0.2 — 2020-04-28
- 2.0.1 — 2019-12-13
- 2.0.0 — 2019-12-13
- 1.0.2 — 2018-11-14
- 1.0.1 — 2017-04-23
- 1.0.0 — 2017-02-02
- 0.4.0 — 2016-02-05
- 0.3.0 — 2016-01-14
- … 3 more at https://npm.io/package/stack-utils/versions

## README

# stack-utils 

> Captures and cleans stack traces.

[![Linux Build](https://travis-ci.org/tapjs/stack-utils.svg?branch=master)](https://travis-ci.org/tapjs/stack-utils) [![Build status](https://ci.appveyor.com/api/projects/status/fb9i157knoixe3iq/branch/master?svg=true)](https://ci.appveyor.com/project/jamestalmage/stack-utils-oiw96/branch/master)  [![Coverage](https://coveralls.io/repos/tapjs/stack-utils/badge.svg?branch=master&service=github)](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.
The default is `StackUtils.nodeInternals()`, this can be disabled by setting `[]` or appended using
`StackUtils.nodeInternals().concat(additionalRegExp)`.  See also `ignoredPackages`.

##### ignoredPackages

Type: `array` of `string`s

An array of npm modules to be culled from the stack trace.  This list will mapped to regular
expressions and merged with the `internals`.

Default `''`.

##### 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, indent = 0)

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).
Spaces at the start of each line are trimmed, indentation can be added by setting `indent` to the desired number of spaces.

#### 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`
 - `type`: `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)

---
_Source: https://npm.io/package/stack-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._