Wrap errors without losing the original message, stack trace, or properties
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist release v4.0.11 Dec 9, 2018
lib ESLint auto-fixes (replaced single quotes with double quotes) Dec 8, 2018
test
.editorconfig ESLint auto-fixes (replaced single quotes with double quotes) Dec 8, 2018
.eslintrc.yml Cleaned-up the CI scripts for cross-platform and cross-browser testing Dec 8, 2018
.gitignore exclude code-coverage files from git Oct 6, 2018
.travis.yml Added a deployment job to publish tagged releases to npm Dec 17, 2018
404.md setup github pages Oct 11, 2018
CHANGELOG.md updated URLs Oct 4, 2018
LICENSE testing git Jul 31, 2015
README.md fixed a broken link Feb 14, 2019
_config.yml setup github pages Oct 11, 2018
banner.txt moved the banner comment to banner.txt Jan 10, 2017
karma.conf.js Added a deployment job to publish tagged releases to npm Dec 17, 2018
package-lock.json
package.json Added the ".spec.js" extension to the typescript tests, to be consistent Dec 17, 2018

README.md

ono (Oh No!)

Throw better errors.

Build Status Coverage Status

npm Dependencies License

OS and Browser Compatibility

Features

  • Formatted error messages, using Node's util.format() or your own custom formatter
  • Wrap and re-throw an error without losing the original error's message, stack trace, and properties
  • Add custom properties to your errors — great for error codes, support numbers, help URLs, etc.
  • Errors can be serialized as JSON, including all native and custom properties
  • Tested on Node.js and all modern web browsers on Mac, Windows, Linux, iOS, and Android

Example

// Throw an error with formatted message
throw ono("%s is invalid. Must be at least %d characters.", username, minLength);

// Wrap and re-throw an error without losing the original error's message and stack
throw ono(err, "An error occurred while saving your changes");

// Throw an error with custom properties (even a custom method!)
throw ono({code: 413, status: "Invalid data", retry: function() {...}});

// Add custom properties to an existing Error
throw ono(err, {code: 413, status: "Invalid data", retry: function() {...}})

// Any of the above can throw a specific Error subtype instead
throw ono.range(...);       // RangeError
throw ono.syntax(...);      // SyntaxError
throw ono.reference(...);   // ReferenceError

Installation

Node

Install using npm:

npm install ono

Then require it in your code:

var ono = require("ono");

Web Browsers

Reference ono.js or ono.min.js in your HTML:

<script src="https://cdn.rawgit.com/JS-DevTools/ono/master/dist/ono.js"></script>
<script>
    var timestamp = new Date().toISOString();
    throw ono('This error was thrown at %s', timestamp);
</script>

API

ono([err], [props], [message, ...])

Creates an Error object with the given properties.

  • err - (optional) An existing error object. This error's message, stack trace, and properties will be appended to the new error.

  • props - (optional) An object whose properties will be added to the new error. Properties can be anything, including objects and functions.

  • message - (optional) The error message string. If it contains placeholders, then pass each placeholder's value as an additional parameter. See ono.formatter for more info.

Specific error types

The default ono() function always creates Error objects, but you can use any of the following methods to explicitly create the corresponding Error subclass. The method signatures are exactly the same as above.

Method Error type
ono.error() Error (this is just an alternate syntax)
ono.eval() EvalError
ono.range() RangeError
ono.reference() ReferenceError
ono.syntax() SyntaxError
ono.type() TypeError
ono.uri() URIError

ono.formatter

By default, Node's util.format() function is used (even in browsers) to format error messages and substitute placeholders with their corresponding values. You can set ono.formatter to a third-party formatter or even your own custom implementation, like this:

ono.formatter = function(message) {
    var params = Array.prototype.slice.call(arguments, 1);
    return params.reduce(function(message, param, index) {
        return message.replace("$" + index, param);
    }, message);
}

throw ono("$0 must be greater than $1", 4, 10);

Contributing

Contributions, enhancements, and bug-fixes are welcome! File an issue on GitHub and submit a pull request.

Building/Testing

To build/test the project locally on your computer:

  1. Clone this repo
    git clone https://github.com/JS-DevTools/ono.git

  2. Install dependencies
    npm install

  3. Run the build script
    npm run build

  4. Run the tests
    npm test

License

Ono is 100% free and open-source, under the MIT license. Use it however you want.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤

Travis CI SauceLabs Coveralls