npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

trace-unhandled

v2.0.1

Published

Much better tracing of unhandled promise rejections in JavaScript

Downloads

356,778

Readme

npm version downloads build status coverage status Language grade: JavaScript

trace-unhandled

Node.js and browsers warn on unhandled promise rejections. You might have seen:

(node:1234) UnhandledPromiseRejectionWarning

When this happens, it's not always obvious what promise is unhandled. The error stacktrace will tell where the error object construction is, not the construction of the promise which left it dangling. It might have travelled through various asynchronous chains before it got to an unhandled promise chain.

trace-unhandled helps with this. It keeps track of promises and when an unhandled promise rejection is logged, the location of both the error object and the promise is logged. This makes it a lot easier to find the bug.

This package is not intended to be used in production, only to aid locating bugs

Why

Consider the following code which creates an error (on line 1) and rejects a promise (on line 3) and "forgets" to catch it on line 9 (the last line). This is an incredibly simple example, and in real life, this would span over a lot of files and a lot of complexity.

1. const err = new Error( "foo" );
2. function b( ) {
3.	return Promise.reject( err );
4. }
5. function a( ) {
6.	return b( );
7. }
8. const foo = a( );
9. foo.then( ( ) => { } );

Without trace-unhandled, you would get something like:

(node:1234) UnhandledPromiseRejectionWarning: Error: foo
    at Object.<anonymous> (/my/directory/test.js:1:13)
    at Module._compile (internal/modules/cjs/loader.js:776:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:787:10)
    at Module.load (internal/modules/cjs/loader.js:643:32)
    at Function.Module._load (internal/modules/cjs/loader.js:556:12)
    at Function.Module.runMain (internal/modules/cjs/loader.js:839:10)
    at internal/main/run_main_module.js:17:11

This is the output of Node.js. You'll see the stacktrace up to the point of the Error err, but that's rather irrelevant. What you want to know is where the promise was used leaving a rejection unhandled (i.e. a missing catch()). With trace-unhandled this is exactly what you get, including the Error construction location:

(node:1234) UnhandledPromiseRejectionWarning
[ Stacktrace altered by https://github.com/grantila/trace-unhandled ]
Error: foo
    ==== Promise at: ==================
    at Promise.then (<anonymous>)
    at Object.<anonymous> (/my/directory/test.js:9:5)  👈

    ==== Error at: ====================
    at Object.<anonymous> (/my/directory/test.js:1:13)

    ==== Shared trace: ================
    at Module._compile (internal/modules/cjs/loader.js:776:30)
	... more lines below ...

We "used" the promise by appending another .then() to it. This means that the promise was actually "handled", and that the new promise should handle rejections. If we delete the last line (line 9), we see where the promise was last "used":

(node:1234) UnhandledPromiseRejectionWarning
[ Stacktrace altered by https://github.com/grantila/trace-unhandled ]
Error: foo
    ==== Promise at: ==================
    at b (/my/directory/test.js:3:17)                   👈
    at a (/my/directory/test.js:6:9)                    👈
    at Object.<anonymous> (/my/directory/test.js:8:13)  👈

    ==== Error at: ====================
    at Object.<anonymous> (/my/directory/test.js:1:13)

    ==== Shared trace: ================
    at Module._compile (internal/modules/cjs/loader.js:776:30)
	... more lines below ...

Both these examples show clearly where the promise is left unhandled, and not only where the Error object is constructed.

Usage

trace-unhandled can be used in 4 ways.

As a standalone program

trace-unhandled exports a program which can run JavaScript files and shebang scripts. Instead of running your program as node index.js you can do trace-unhandled index.js as long as trace-unhandled is globally installed.

You can also use npx:

npx trace-unhandled index.js

In a website

<head><script src="https://cdn.jsdelivr.net/npm/trace-unhandled@latest/browser.js"></script></head>

To specify a custom logger function, use setTraceUnhandledLogger:

window.setTraceUnhandledLogger( msg => { ... } ); // msg is a string

Programatically - API

require( 'trace-unhandled/register' ); // As early as possible

or if you want to allow some code to execute before you start tracing:

const { register } = require( 'trace-unhandled' );

// ... whenever you want to start tracing
register( );

To specify a custom logger function, use setLogger:

const { setLogger } = require( 'trace-unhandled' );
setLogger( msg => { ... } ); // msg is a string

In unit tests

To use this package when running jest, install the package and configure jest with the following setup:

{
  setupFiles: [
    "trace-unhandled/register"
  ]
}

For mocha you can use --require node_modules/trace-unhandled/register.js.