# erreur

> Type safe custom errors

Latest version **3.0.4** (published 2023-06-21) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

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

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 3.0.4 |
| Published | 2023-06-21 |
| First published | 2022-08-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 21.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Etienne Dldc |
| Maintainers | etienne-dldc |
| Keywords | error, ts, typescript |

## Links

- npm: https://www.npmjs.com/package/erreur
- Repository: https://github.com/etienne-dldc/erreur
- Homepage: https://github.com/etienne-dldc/erreur#readme
- Issues: https://github.com/etienne-dldc/erreur/issues
- npm.io page: https://npm.io/package/erreur

## Dependencies (1)

- [staack](https://npm.io/package/staack.md) ^3.0.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

- 3.0.4 (latest) — 2023-06-21
- 3.0.0-13 (next) — 2023-06-20
- 3.0.3 — 2023-06-21
- 3.0.2 — 2023-06-20
- 3.0.1 — 2023-06-20
- 3.0.0 — 2023-06-20
- 3.0.0-12 — 2023-06-20
- 3.0.0-11 — 2023-06-20
- 3.0.0-10 — 2023-06-20
- 3.0.0-9 — 2023-06-20
- 3.0.0-8 — 2023-06-20
- 3.0.0-7 — 2023-06-19
- 3.0.0-6 — 2023-06-12
- 3.0.0-5 — 2023-06-11
- 3.0.0-4 — 2023-06-09
- … 24 more at https://npm.io/package/erreur/versions

## README

# 🛑 Erreur

> Type safe custom errors

## Type safe custom errors ?

This librairy expose a way to define and manipulate custom errors in a type safe way.

To acheive this, it uses a class called `Erreur` (error in french) that extends the native `Error` class. This class can contain data but in order to ensure type safety, you cannot access this data directly. Instead, you must use a declaration that can be created using the `createKey`.

Internally, the `Erreur` class uses [`etienne-dldc/staack`](https://github.com/etienne-dldc/staack) to store the data.

Here is a simple example:

```ts
import { ErreurType, Erreur } from 'erreur';

// Create a new type
const HttpErrorType = ErreurType.define<number>('StatusCode');

// Create a new Erreur
const err = Erreur.create('Something went wrong');

// Add data to the Erreur
const errWithStatusCode = HttpErrorType.extends(err, 500);

// Get data from the Erreur
const statusCode = errWithStatusCode.get(HttpErrorType.Consumer);

expect(statusCode).toBe(500);
```

## API

### `Erreur.create`

Create a new `Erreur` instance. You can optionally pass a message:

```ts
const err1 = Erreur.create();
const err2 = Erreur.create('Something went wrong');
```

### `erreur.with(...providers)`

Use the `with` method to add data to an `Erreur` instance. This method accepts any number of `Provider` declaration and returns a new `Erreur` instance:

```ts
const MyKey = createKey<string>({ name: 'MyKey' });

const err1 = Erreur.create().with(MyKey.Provider('Hello'));
```

### `erreur.get(consumer)`

### `erreur.getOrFail(consumer)`

### `erreur.has(consumer)`

### `Erreur.is`

Check if a value is an `Erreur` instance:

```ts
const err = Erreur.create();
const isErr = Erreur.is(err); // true
```

_Note: this is the same as using `instanceof Erreur`_

### `Erreur.wrap` and `Erreur.wrapAsync`

Wrap a function to make sure it either returns a value or throws an `Erreur` instance. Not that this function does not care about what is inside the `Erreur` instance, it only checks that it is an instance of `Erreur`.

### `Erreur.resolve` and `Erreur.resolveAsync`

Same as `Erreur.wrap` and `Erreur.wrapAsync` but returns the `Erreur` instance instead of throwing it.

### Overriding the message

You can override the message of an `Erreur` using the `Erreur.MessageKey` key:

```ts
const err1 = Erreur.create('Something went wrong');
const err2 = err1.with(Erreur.MessageKey.Provider('Something went really wrong'));
// A shortcut is also available
const err3 = err2.withMessage('Something went really wrong');
```

## Recipes

### Using Union types

You can handle many errors with a single key using union types:

```ts
type FetchError =
  | { type: 'NetworkError'; error: any }
  | { type: 'ParseError'; content: string }
  | { type: 'ResponseNotOk'; response: any };

const FetchErrorType = createErrorType<FetchError>({ name: 'FetchError' });
```

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