# brilliant-errors

> A set of configurators to help your Apps and Libraries build brilliant error classes

Latest version **0.7.3** (published 2022-12-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install brilliant-errors
pnpm add brilliant-errors
yarn add brilliant-errors
bun add brilliant-errors
```

## Health

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

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.7.3 |
| Published | 2022-12-09 |
| First published | 2020-08-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=14.0.0 |
| Dependencies | 4 |
| Unpacked size | 17.6 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Ken Snyder |
| Maintainers | ksnyde |
| Keywords | error-management |

## Links

- npm: https://www.npmjs.com/package/brilliant-errors
- Repository: https://github.com/inocan-group/brilliant-errors
- Homepage: https://github.com/inocan-group/brilliant-errors#readme
- Issues: https://github.com/inocan-group/brilliant-errors/issues
- npm.io page: https://npm.io/package/brilliant-errors

## Dependencies (4)

- [bumpp](https://npm.io/package/bumpp.md) ^8.2.1
- [vitest](https://npm.io/package/vitest.md) ^0.25.6
- [callsites](https://npm.io/package/callsites.md) ^4.0.0
- [inferred-types](https://npm.io/package/inferred-types.md) ^0.37.2

## 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.7.3 (latest) — 2022-12-09
- 0.7.2 — 2022-12-09
- 0.7.1 — 2022-12-05
- 0.7.0 — 2022-12-05
- 0.6.1 — 2022-11-17
- 0.6.0 — 2022-07-27
- 0.5.6 — 2022-01-11
- 0.5.5 — 2021-12-27
- 0.5.4 — 2021-12-27
- 0.5.3 — 2021-12-25
- 0.5.2 — 2021-12-25
- 0.5.1 — 2021-12-21
- 0.5.0 — 2021-12-20
- 0.4.3 — 2021-11-22
- 0.4.2 — 2021-11-22
- … 5 more at https://npm.io/package/brilliant-errors/versions

## README

# Brilliant Errors

> **Note:** the version 6.x of this library had moved to newer dependencies wand the `callsites` library  _only_ support the ESM module system these days but because we were packaging up in both ESM and CJS it was causing errors. I had intended to keep CJS around for a while longer but in most cases you really should be preferring ESM anyway. In version **7.x** and going forward we are only publishing version ESM. If you still need CJS you can use the latest `0.5.x` release.

The base errors you get from Javascript leave a lot to be desired and this library attempts to provide a _consistent_ way to provide solid meta information on errors raised in Typescript/Javascript projects.

This library provides two _configurators_ for errors:

1. `createError` - the default error type provides an Error with strongly typed classification but does not require an HTTP status code for errors (you _are_ allowed to add the HTTP status code)

    ```ts
    type ErrorType = "not-allowed" | "unexpected" | "missing-info";
    const MyError = createError<ErrorType>(e => e.name("MyError").origin("my-app"));

    // instantiation
    const error = new MyError("I've fallen and I can't get up", "unexpected/old-age");
    
    // static initializers for edge cases
    const error = MyError.withUnderlying(err, "No really, I can't get up", "unexpected/fer-fucks-sake");
    const error = MyError.withHttpCode(500, "Not worth repeating", "unexpected/web-fall");

    // options hash (means you can get to everything if you need it)
    const error = new MyError("Just stop it", "not-allowed/shit-happens", { underlying: err, httpStatus: 500 });
    ```

2. `createHttpError` - an HTTP error produces errors which are guarenteed to have an HTTP status code as part of their payload but they also follow the Type/Subtype conventions in the base error.

    ```ts
    const HttpError = createHttpError<ErrorType, SubType>(e => 
        e.name("HttpError")
         .origin("my-network-app")
         .defaultType("missing-info")
    );

    // instantiotion
    const error = new HttpError(403, "couldn't find member's id", "no-membership-id");

All errors have the following attributes:

- `kind` - a string literal type for the error family the error originates from
- `name` - a string literal type for the error name
- `origin` - a string literal type for the application/service which originated this error
- `classification` - strongly typed Type/Subtype system
- `httpStatus` - a numeric HTTP status code that can (and in some cases must) be set
- `underlying` - all errors _can_ store an underlying error and the wrapper error requires it

They also have brilliant `.toJSON()` and `message` outputs which shine above the plain old vanilla JS error.

For a repo which wants to use these configurators, you will create a file in your repo for the new error and then configure it something like this:

`src/error/MyError.ts`:

```ts
export default MyError = createLibraryError('MyError', { ... });
```

All options in the configurators are strongly typed which includes full documentatory information so rather than try to repeat that here we emplore you to use the _built-in_ Typescript documentation within your code editor of choice.

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