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

eraro

v3.0.1

Published

Create JavaScript Error objects with code strings, context details, and templated messages.

Downloads

51,343

Readme

eraro

npm version build Coverage Status DeepScan grade Maintainability

Create JavaScript Error objects with code strings, context details, and templated messages.

For use in library modules to generate contextual errors with useful meta data. Your library module can throw or pass (to a callback) an Error object that has additional properties, such as a code, that can be used for programmatic inspection by client code that uses your library.

If you're using this module, feel free to contact me on twitter if you have any questions! :) @rjrodger

Quick example


var error = require('eraro')({package:'mylib'})

// throw an Error object that has a code
throw error('code_string')

// provide a user message
throw error('code_string', 'Message text.')

// supply context details for error
throw error('code_string', 'Message text.', {foo:1, bar:2})

// extend an existing Error object
var ex = new Error('Another message.')
throw error(ex,'code_string',{zed:3})

In all these cases, the Error object will have a code`` property with value "code_string"`.

Install

npm install eraro

There's an npm module page for eraro.

Usage

Use this module when you are writing a library that will be used by application code. It allows your library to generate informative error messages.

The module itself is a generator function (taking options) that returns the error-creating function that you will actually use. Thus the most common way to use eraro is to require and call immediately:

var error = require('eraro')({package:'mylib'})

The error function can then be used in your library code. The error function generates Error objects, which can be thrown or used in callbacks:

throw error('code1')

function doStuff (input, callback) {
  if (bad(input)) return callback(error('code2'));
}

The package option is normally the name of your library. That is, the value of the name property in package.json. The generated Error object will have two properties to define the package: package, a string that is the name of the package, and also a boolean, the name of the package itself. This lets you check for the type of error easily:

var error = require('eraro')({package:'mylib'})

var err0 = error('code0')
"mylib" === err0.package // true
err0.mylib // true

Error details

You can supply additional contextual details for debugging or other purposes. These are placed inside the details property of the generated Error:

var error = require('eraro')({package:'mylib'})

var err0 = error('code0', {foo: 'FOO', bar: 'BAR'})
"FOO" === err0.details.foo
"BAR" === err0.details.bar

Error codes and message templates

To provide consistent error messages to your users, you can define a set of message templates, keyed by code:

var error = require('eraro')({package: 'mylib', msgmap: {
  code0: "The first error, foo is <%=foo%>.",
  code1: "The second error, bar is <%=bar%>.",
}})

When you specify a code, and details, these are inserted into the message (if any) associated with that code:

var err0 = error('code0',{foo: 'FOO', bar: 'BAR'})
"mylib: The first error, foo is FOO." === err0.message

The message templates are underscorejs templates with the default settings.

If you specify a message directly, this is also interpreted as a template:

var err0 = error('code2',
                 'My custom message, details: <%=util.inspect(zed)%>',
                 {zed: {a: 1, b: 2}})
"mylib: My custom message, details: { a: 1, b: 2 }" === err0.message

Message templates always have the original error message and first stack line details available as: message: <%=errmsg%>, line: <%=errline%>.

The returned Error object

The returned Error object has the following additional properties:

  • code: String; the code string
  • package: String; the package name
  • package-name: Boolean (true); a convenience marker for the package
  • msg: String; the generated message, may differ from original exception message (if any)
  • details: Object; contextual details of error
  • callpoint: String; first line of stacktrace that is external to eraro and calling module

You can pass in an existing Error object. The additional properties will be added to it, but the original message will be used as the message template, overriding any matching code message.

Options

When creating an error function, you can use the following options:

  • package : (optional) String; package name to mark Error objects
  • prefix : (optional) Boolean/String; If false, then no prefix is used; If not defined, the package name is used
  • module : (optional) Object; module object to use as starting point for require calls
  • msgmap : (optional) Object; map codes to message templates
  • inspect : (optional) Boolean; If true, util.inspect is called on values; default: true.

In the Wild

For real-world usage examples, see:

  • use-plugin: a utility for providing a plugin interface for extensions to your module
  • seneca: a micro-services framework for Node.js