# catch-unknown

> Utility functions for writing type-safe catch blocks

Latest version **2.0.0** (published 2023-08-26) · ISC license · 0 weekly downloads

## Install

```sh
npm install catch-unknown
pnpm add catch-unknown
yarn add catch-unknown
bun add catch-unknown
```

## Health

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

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

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2023-08-26 |
| First published | 2022-03-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 6.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Trevor Robinson |
| Maintainers | trevorr |
| Keywords | base62, id, random, uuid |

## Links

- npm: https://www.npmjs.com/package/catch-unknown
- Repository: https://github.com/trevorr/catch-unknown
- Homepage: https://github.com/trevorr/catch-unknown#readme
- Issues: https://github.com/trevorr/catch-unknown/issues
- npm.io page: https://npm.io/package/catch-unknown

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2023-08-26
- 1.0.0 — 2022-03-12

## README

# catch-unknown: Utility functions for writing type-safe JavaScript catch blocks

[![npm](https://img.shields.io/npm/v/catch-unknown)](https://www.npmjs.com/package/catch-unknown)
[![CircleCI](https://img.shields.io/circleci/build/github/trevorr/catch-unknown)](https://circleci.com/gh/trevorr/catch-unknown)

While exceptions thrown in JavaScript are usually objects of class `Error`, they can actually be values of any type.
This is particularly relevant in TypeScript, which in version 4.4 starting [defaulting `catch` variables to `unknown`
type](https://devblogs.microsoft.com/typescript/announcing-typescript-4-4/#use-unknown-catch-variables) (instead of `any`).
This small library provides two functions to make writing type-safe catch blocks easier: `isError` returns whether a
value conforms to the `Error` interface, and `asError` will convert any value to an object conforming to `Error` if necessary:

```ts
interface Error {
  name: string;
  message: string;
  stack?: string;
  cause?: unknown;
}

export declare function isError(err: unknown): err is Error;
export declare function asError(err: unknown): Error;
```

This library has no runtime dependencies, compiles to ES6 for wide compatibility, and has a package size of 2.9 kB.

## Installation

```sh
npm install catch-unknown
```

## Usage

Typical usage might look something like this:

```ts
import { asError } from 'catch-unknown';

try {
  // stuff
} catch (err) {
  logger.warn(`Stuff failed due to ${asError(err).message}`);
  throw err;
}
```

## Examples

Hopefully you never see a non-`Error` thrown, but if you do, nothing else will break:

```ts
import { asError, isError } from 'catch-unknown';

try {
  throw new Error('Something is wrong');
} catch (err) {
  console.log(isError(err)); // true
  console.log(asError(err)); // Error: Something is wrong
}

try {
  throw { message: 'An odd thing to throw' };
} catch (err) {
  console.log(isError(err)); // false
  console.log(asError(err)); // Object: An odd thing to throw
}

try {
  throw { x: 12, y: 5 };
} catch (err) {
  console.log(isError(err)); // false
  console.log(asError(err)); // Object: {"x":12,"y":5}
}

try {
  throw new Date(0);
} catch (err) {
  console.log(isError(err)); // false
  console.log(asError(err)); // Date: Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time)
}

try {
  throw 42;
} catch (err) {
  console.log(isError(err)); // false
  console.log(asError(err)); // number: 42
}
```

## License

`catch-unknown` is available under the [ISC license](LICENSE).

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