@tapjs/stack

@tapjs/stack

A comprehensive library for dealing with stack traces, supporting source map lookup (when enabled in node with --enable-source-maps), filtering of specified packages and/or Node.js internals, and capturing call sites relative to a given function.

The spiritual descendant of stack-utils.

Class CallSiteLike

This is similar to the CallSite class in V8. However, rather than provide methods to get all the relevant details about the call site, it has them set as properties. Additionally, it may be generated by parsing a line from a string stack trace, which is useful when tracking down the source of thrown errors.

See the typedocs for more information.

Class CallSiteLikeJSON

This is the "plain old JavaScript object" form of a CallSiteLike object, for use when serializing a CallSiteLike to YAML or JSON.

It contains all the same fields as CallSiteLike, but fields are unset rather than being set to null or undefined if they are not relevant to the call site, to reduce noise when printing test diagnostics.

The toString() value of CallSiteLike objects is a much terser representation of the call site than the standard Error.stack string, and it contains both the generated and origin call sites in the case of source mapped files.

See the typedocs for more information.

at(fn?: Function): CallSiteLike | undefined

Get the call site in the stack either where at() is called, or where the supplied fn function is called.

If fn is provided, and is not in the current call stack, then undefined will be returned.

capture(limit = 0, fn?: Function): CallSiteLike[]

Get an array of CallSiteLike objects for the current location, from the call to the fn argument if supplied, limited to the number of frames specified by limit.

If fn is supplied, and not in the current call stack, then an empty array will be returned.

If the limit argument is 0, then the current Error.stackTraceLimit value will be used.

This method is not re-entry safe, due to the fact that it relies on temporarily overriding the global Error.prepareStackTrace. As a result, if a capture() is triggered in any of the methods used by the CallSiteLike constructor (for example, if @tapjs/intercept is used to capture the process.cwd() method, which is used by path.resolve()), then that will cause problems. To work around this, if a re-entry is detected, then an empty stack of [] is returned.

Even if it was made re-entry safe, it would be easy to accidentally trigger an infinite recursion and stack overflow in such a scenario, so returning an empty stack in the case of re-entry is the best workaround.

captureString(limit = 0, fn?: Function): string

The same as capture(), but returns a string stack where each line is the toString() of the CallSiteLike object.

captureError(er: Error): CallSiteLike[]

Get a stack of CallSiteLike objects by parsing the stack property of the supplied Error object.

This does not actually look at the current call site, or do anything magical with the V8 engine. It's just parsing a string.

While some effort is made to interpret stacks correctly when an Error contains a name and message, remember that the Error.stack property in JavaScript is remarkably sloppy. In some cases, if the Error.message contains \n and some lines after the first look like stack trace lines, incorrect data may result. It's only as good as the stack you pass to it.

captureErrorString(er: Error): string

The same as captureError (with the same caveats) but presenting the string stack where each line is the toString() value of the CallSiteLike object.

parseStack(stack: string): CallSiteLike[]

Turn a string stack (either from @tapjs/stack or from a native Error object) into an array of CallSiteLike objects.

Only useful in some niche situations, most of the time you're better off using capture() or captureError().

expandStack(stack?: string | CallSiteLike[]): string

Expand a stack string (either from @tapjs/stack or from a JS Error object) into its conventional Error.stack form, complete with absolute paths, indentation, and repetitive at prefixes.

When a call site is source mapped, the origin source will be shown if the generated source is outside the cwd. If the cwd is not set on the CallSiteLike object, then generated location is always shown.

setCwd(cwd: string | undefined)

Set the current working directory used to shorten filename paths in CallSiteLike objects.

Default value is process.cwd(). Setting it to undefined will cause the CallSiteLike objects returned by the capture methods to display full file paths.

getCwd(): string | undefined

Get the current value of the effective cwd used by capture methods.

getFilterNodeInternals(): boolean

Tells you whether or not node internals are being filtered out.

Defaults to true

setFilterNodeInternals(f: boolean)

Specify whether node internals should be filtered out.

getFilterIgnoredPackages(): boolean

Tells you whether or not the set of ignored packages are being filtered out.

Defaults to true

setFilterIgnoredPackages(f: boolean)

Specify whether or not ignored packages should be filtered out.

getIgnoredPackages(): string[]

Get the list of packages that are filtered out of captured stacks.

addIgnoredPackage(pkg: string)

Add a package to the filter set.

removeIgnoredPackage(pkg: string)

Remove a package from the filter set.