# @jakubmazanec/error

> Collection of utilities for creating and handling errors.

Latest version **3.0.18** (published 2026-08-05) · LGPL-3.0-only license · 0 weekly downloads

## Install

```sh
npm install @jakubmazanec/error
pnpm add @jakubmazanec/error
yarn add @jakubmazanec/error
bun add @jakubmazanec/error
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 3.0.18 |
| Published | 2026-08-05 |
| First published | 2022-10-18 |
| Weekly downloads | 0 |
| License | LGPL-3.0-only |
| TypeScript types | none |
| Module format | ESM |
| Node | ^24.3.0 |
| Dependencies | 1 |
| Unpacked size | 70.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Author | Jakub Mazanec |
| Maintainers | jakubmazanec |

## Links

- npm: https://www.npmjs.com/package/@jakubmazanec/error
- Repository: https://github.com/jakubmazanec/tools
- Homepage: https://github.com/jakubmazanec/tools#readme
- Issues: https://github.com/jakubmazanec/tools/issues
- npm.io page: https://npm.io/package/@jakubmazanec/error

## Dependencies (1)

- [zod](https://npm.io/package/zod.md) ^4.4.3

## Recent versions

- 3.0.18 (latest) — 2026-08-05
- 3.0.19-unstable.72f063e3 (unstable) — 2026-08-13
- 3.0.18-next.c37a15f9 (next) — 2026-08-05
- 3.0.18-unstable.1ba662ab — 2026-08-05
- 3.0.18-next.1031336f — 2026-08-04
- 3.0.18-unstable.3883579b — 2026-08-04
- 3.0.18-unstable.8731a3c6 — 2026-08-04
- 3.0.18-unstable.0b259717 — 2026-08-04
- 3.0.18-unstable.b78aa229 — 2026-08-04
- 3.0.18-next.e190aac1 — 2026-08-03
- 3.0.18-unstable.c0c3b2d0 — 2026-08-03
- 3.0.18-next.9c9a8b78 — 2026-08-03
- 3.0.18-next.e659d093 — 2026-08-02
- 3.0.18-unstable.f507ff42 — 2026-08-02
- 3.0.18-unstable.f50b9d9c — 2026-08-02
- … 265 more at https://npm.io/package/@jakubmazanec/error/versions

## README

<!-- header -->
<div align="center">

# @jakubmazanec/error

Collection of utilities for creating and handling errors.
</div>
<!-- header -->

## Installation

```sh
npm install @jakubmazanec/error
```

⚠️ This is an [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) package!
It cannot be required from a CommonJS module.

<!-- prerequisites -->

#### Prerequisites

- Node.js 24 or later
- TypeScript 6 or later

<!-- prerequisites -->

## Usage

Create custom error classes to distinguish between errors and to ensure consistent error messages:

```TypeScript
import {createCustomError} from '@jakubmazanec/error';

let FoobarError = createCustomError('FoobarError', {
  FOOBAR_NOT_FOUND: 'Foobar was not found!',
});

try {
  throw new FoobarError('FOOBAR_NOT_FOUND');
} catch (error: unknown) {
  console.log(error instanceof FoobarError); // -> true
  console.log(error.message); // -> 'Foobar was not found!'
  console.log(error.code); // -> 'FOOBAR_NOT_FOUND'
}
```

You can also have arbitrary data attached:

```TypeScript
import {createCustomErrorWithData} from '@jakubmazanec/error';
import {z} from 'zod';

let FoobarError = createCustomErrorWithData(
  'FoobarError',
  {FOOBAR_FAILED: 'Foobar failed with exit code "{0}" and message "{1}"!'},
  z.object({
    cwd: z.string(),
  })
);

function runFoobar() {
  let foobarOptions = {
    cwd: '/foobar',
  };

  try {
    foobar(foobarOptions);
  } catch (error: unknown) {
    if (error instanceof Error) {
      throw new FoobarError('FOOBAR_FAILED', {
        messageParameters: [42, 'Oops :('],
        data: foobarOptions,
        cause: error,
      });
    }
  }
}

try {
  runFoobar();
} catch (error: unknown) {
  console.log(error instanceof FoobarError); // -> true
  console.log(error.message); // -> 'Foobar failed with exit code "42" and message "Oops :("!'
  console.log(error.code); // -> 'FOOBAR_FAILED'
  console.log(error.data); // -> { cwd: '/foobar' }
  console.log(error.cause); // -> Error
}
```

## Documentation

See [API reference](./docs) for auto-generated documentation.

## Contributing

If you want to contribute, see [CONTRIBUTING](./CONTRIBUTING.md) for details.

## License

This package is licensed under the GNU Lesser General Public License v3. See [LICENSE](./LICENSE.md)
for details.

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