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

pony-cause

v2.1.11

Published

Ponyfill and helpers for Error Causes

Downloads

5,264,183

Readme

Helpers and ponyfill for Error Causes

npm version npm downloads Module type: CJS+ESM Types in JS js-semistandard-style Follow @voxpelli@mastodon.social

Exports

Helpers for working with error causes

All the above are backwards compatible with causes created by the VError module which predated the Error Causes spec and is still used in parts of the ecosystem.

Ponyfill for Error Causes

CJS + ESM + Types

pony-cause is dual published as both CommonJS and ESM, use whichever you like and make use of the TypeScript compliant types no matter which.

Examples

ErrorWithCause

Ponyfill of the cause-supporting Error class

const { ErrorWithCause } = require('pony-cause');

try { /* Something that can break */ } catch (err) {
  throw new ErrorWithCause('Failed doing what I intended', { cause: err });
}

findCauseByReference

Finding an error of a specific type within the cause chain. Is typescript friendly.

const { findCauseByReference } = require('pony-cause');

try { /* Something that can break */ } catch (err) {
  /** @type {MySpecialError} */
  const specialErr = findCauseByReference(err, MySpecialError);

  if (specialErr && specialErr.specialProperty === 'specialValue') {
    // Its okay, chill!
  } else {
    throw err;
  }
}

Used to find a specific type of error in the chain of causes in an error.

Similar to VError.findCauseByName but resolves causes in both Error Causes style, .cause, and VError style, .cause() + takes a reference to the Error class that you are looking for rather than simply the name of it, as that enables the TypeScript types to properly type the returned error, typing it with the same type as the reference.

Can be useful if there's some extra data on it that can help determine whether it's an unexpected error or an error that can be handled.

If it's an error related to a HTTP request, then maybe the request can be retried? If its a database error that tells you about a duplicated row, then maybe you know how to work with that? Maybe forward that error to the user rather than show a 500 error?

Note: findCauseByReference has protection against circular causes

getErrorCause

Getting the direct cause of an error, if there is any

const { getErrorCause } = require('pony-cause');

try { /* Something that can break */ } catch (err) {
  // Returns the Error cause, VError cause or undefined
  const cause = getErrorCause(err);
}

The output is similar to VError.cause() but resolves causes in both Error Causes style, .cause, and VError style, .cause().

Always return an Error, a subclass of Error or undefined. If a cause in Error Causes style cause is not an Error or a subclass of Error, it will be ignored and undefined will be returned.

messageWithCauses

Gets the error message with the messages of its cause chain appended to it.

const { messageWithCauses, ErrorWithCause } = require('pony-cause');

try {
  try {
    // First error...
    throw new Error('First error');
  } catch (err) {
    // ...that's caught and wrapped in a second error
    throw new ErrorWithCause('Second error', { cause: err });
  }
} catch (err) {
  // Logs the full message trail: "Second error: First error"
  console.log(messageWithCauses(err));
}

The output is similar to the standard VError behaviour of appending message with the cause.message, separating the two with a : .

Since Error Causes doesn't do this, messageWithCauses exist to mimic that behaviour.

It respects VError messages, it won't append any error message of their causes, though it will walk past the VError causes to see if there's a non-VError cause up the chain and then append that.

The reason to use this method is explained by VError:

The idea is that each layer in the stack annotates the error with a description of what it was doing. The end result is a message that explains what happened at each level.

If an inner error has a message ENOENT, stat '/nonexistent', an outer error wraps it and adds Can't perform X and maybe one more error wraps that and adds Can't start program, then messageWithCauses will join those three errors together when providing it with the outer most error and return Can't start program: Can't perform X: ENOENT, stat '/nonexistent' which provides details about both cause and effect as well as the connection between the two – each which on their own would be a lot harder to understand the impact of.

Note: messageWithCauses has protection against circular causes

stackWithCauses

Gets a stack trace for the error + all its causes.

const { stackWithCauses } = require('pony-cause');

try { /* Something that can break */ } catch (err) {
  console.log('We had a mishap:', stackWithCauses(err));
}

The output is similar to VError.fullStack() but resolves causes in both Error Causes style, .cause, and VError style, .cause().

Note: stackWithCauses has protection against circular causes

Output looks like:

Error: something really bad happened here
    at Object.<anonymous> (/examples/fullStack.js:5:12)
    at Module._compile (module.js:409:26)
    at Object.Module._extensions..js (module.js:416:10)
    at Module.load (module.js:343:32)
    at Function.Module._load (module.js:300:12)
    at Function.Module.runMain (module.js:441:10)
    at startup (node.js:139:18)
    at node.js:968:3
caused by: Error: something bad happened
    at Object.<anonymous> (/examples/fullStack.js:3:12)
    at Module._compile (module.js:409:26)
    at Object.Module._extensions..js (module.js:416:10)
    at Module.load (module.js:343:32)
    at Function.Module._load (module.js:300:12)
    at Function.Module.runMain (module.js:441:10)
    at startup (node.js:139:18)
    at node.js:968:3

For enterprise

Available as part of the Tidelift Subscription.

The maintainers of pony-cause and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. Learn more.

Similar modules

  • verror – a module which has long enabled error causes in javascript. Superseded by the new Error Cause proposal. Differs in that.cause represents a function that returns the cause, its not the cause itself.
  • @netflix/nerror – a Netflix fork of verror
  • error-cause – strict polyfill for the Error Cause proposal. Provides no helpers or similar to achieve VError-like functionality, which pony-cause does.

See also