# exceptions

> Syntactic sugar for referencing and throwing common named and custom errors/exceptions

Latest version **0.1.1** (published 2012-02-28) · 0 weekly downloads

## Install

```sh
npm install exceptions
pnpm add exceptions
yarn add exceptions
bun add exceptions
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2012-02-28 |
| First published | 2012-01-28 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | * |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Allan Boyd |
| Maintainers | allanmboyd |
| Keywords | exception, error |

## Links

- npm: https://www.npmjs.com/package/exceptions
- Repository: https://github.com/allanmboyd/exceptions
- Issues: http://github.com/allanmboyd/exceptions/issues
- npm.io page: https://npm.io/package/exceptions

## Dependencies (1)

- [formaterrors](https://npm.io/package/formaterrors.md) 0.1.1

## Alternatives

- [@sentry/react-native](https://npm.io/package/@sentry/react-native.md) — 2.6M weekly downloads
- [@ardatan/aggregate-error](https://npm.io/package/@ardatan/aggregate-error.md) — 708.1K weekly downloads
- [custom-error-generator](https://npm.io/package/custom-error-generator.md) — 2.0K weekly downloads
- [@technik-sde/prosemirror-recreate-transform](https://npm.io/package/@technik-sde/prosemirror-recreate-transform.md) — 1.5K weekly downloads
- [@suchipi/error-utils](https://npm.io/package/@suchipi/error-utils.md) — 78 weekly downloads

## Recent versions

- 0.1.1 (latest) — 2012-02-28
- 0.1.0 — 2012-01-28

## README

Exceptions
==========

Trivial API and associated static instances of Exception that make it slightly simpler to throw common and
custom exceptions that are not already available in Javascript. Using static instances for Exceptions also
helps to maintain consistency between exception names both when throwing and catching (and reduces the likelihood
of typos in name literal strings causing bugs).

In a language like Java there are checked and unchecked exceptions. In Javascript (probably fortunately) there
are no checked exceptions. There are only Errors. Much of the time I am not really interested in throwing or
catching Errors because usually they are highlighting a bug that needs to be fixed. However, there are times when it is
useful to throw and catch Errors for instance if my application depends upon an external resource (like a datastore or
web service) that suddenly stops responding or changes behaviour in an unexpected way. Often in such cases I would
rather have my application log the details and continue to operate or take some mitigating action instead of merely
terminating or returning null etc. These are the situations for which Exceptions is designed.

The idea is that this works with the current Javascript Error mechanism as a complement to it. Exceptions and Errors
are meant to co-exist - in fact all Exceptions really do is throw Errors and provide a well defined means to compare
Errors within a catch block (for example).

Exceptions uses [formatErrors](https://github.com/allanmboyd/formaterrors) to remove itself from the stacktrace of
thrown errors.

Hopefully the list of static common Exception instances will grow over time.


Installation
------------

    $npm install exceptions

Alternatively include as a dependency within your *package.json* and:

    $npm link


Usage
-----

The API is very trivial. An Exception object has a `name` and a `thro` function. The name is used for identification
and the function is used to throw an Error with that name along with a message passed into the `thro` function. Here is
an example that throws an IllegalStateException with a message of "Bad state"; it catches it and logs the message:

    var exceptions = require("exceptions");
    try {
        exceptions.ILLEGAL_STATE.thro("Bad state");
    } catch (error) {
        if (error.name === exceptions.ILLEGAL_STATE.name) {
            console.log("Got an IllegalStateException: " + error.message);
        }
    }

Custom exceptions can easily be created as needed:

    var exceptions = require("exceptions");
    var myException = new exceptions.Exception("CustomException");
    try {
        myException.thro("my exception");
    } catch (error) {
        if (error.name === myException.name) {
            console.log("Caught my exception");
        }
    }

And thrown exceptions can optionally be given a cause (i.e. another Error that is to blame) that is included in the
stack trace:

    var exceptions = require("exceptions");
    var cause = new Error("I caused it. I'm sorry. It was an accident");
    try {
        exceptions.ILLEGAL_STATE.thro("Bad state with cause", cause);
    } catch (error) {
        console.log(error.stack);
    }

See test/testExceptions.js for some more examples.

API
---

Types
-----

###Exception###
*Constructor:* new Exception(name)

An Exception. This does not extend or replace the Javascript Error type. Rather its purpose is to make throwing
and catching non-standard Javascript Errors simpler and less prone to .... errors.


Variables
---------

###ILLEGAL_ARGUMENT###

An IllegalArgumentException instance of Exception.


###ILLEGAL_STATE###

An IllegalStateException instance of Exception.


###IO###

An IOException instance of Exception.


Testing
-------

Tests utilise [nodeunit](https://github.com/caolan/nodeunit). In addition jshint is run against both lib and test
javascript files.

First install the dependencies:

    $ npm link

Then to run the tests:

    $ npm test



Contributing
------------

Contributions are welcome. Please create tests for any updates and ensure jshint is run on any new files. Currently
npm test will run jshint on all lib and test javascript as well as running all the tests.


Bugs & Feature Suggestions
--------------------------

https://github.com/allanmboyd/exceptions/issues

---
_Source: https://npm.io/package/exceptions · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._