exceptionally

KO | EN

gitlite — search

#python #hacktoberfest #llm #android #rust #deep-learning #macos #java #windows #awesome #kubernetes #awesome-list #mcp #open-source

(★ 56)

A fully type-safe and lightweight way of using exceptions instead of throwing errors

File Explorer

Download Latest Version (.zip)

- config.json
- README.md
- - lint.yml
  - pr-title-check.yml
  - release.yml
  - size-limit.yml
  - test.yml
- post-checkout
- post-merge
- pre-commit
- extensions.json
- launch.json
- settings.json
- tasks.json
- fetching-data.ts
- input-validation.ts
- - assertException.test.ts
  - assertException.test.types.ts
  - assertExceptionAndUnwrap.test.ts
  - assertExceptionAndUnwrap.test.types.ts
  - assertExceptionsHandled.test.ts
  - assertSuccess.AndUnwrap.test.ts
  - assertSuccess.test.ts
  - assertSuccess.test.types.ts
  - assertSuccessAndUnwrap.test.types.ts
  - guardException.test.types.ts
  - guardExceptionsHandled.test.types.ts
  - guardSuccess.test.types.ts
  - index.ts
- - exception.test.ts
  - exception.test.types.ts
  - index.ts
  - success.test.ts
  - success.test.types.ts
  - utils.test.types.ts
- - index.ts
  - processInParallel.test.ts
  - processInParallel.test.types.ts
  - processInParallel.ts
  - tryCatch.test.ts
  - tryCatch.test.types.ts
  - tryCatch.ts
- index.ts
- legacy.ts
- utils.ts
- test.utils.ts
.dprint.json
.eslintignore
.eslintrc.cjs
.gitignore
.lintstagedrc.cjs
.size-limit.cjs
CHANGELOG.md
package.json
pnpm-lock.yaml
README.md
tsconfig.eslint.json
tsconfig.json
tsup-legacy.config.ts
tsup.config.ts

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# :shield: exceptionally

**A fully type-safe and lightweight way of using exceptions instead of throwing errors**

:safety_vest: fully typesafe\
:baby_chick: lightweight core library (132 bytes)\
:gear: useful utility functions\
:running: almost no runtime overhead\
:ok_hand: easy to use syntax\
:handshake: works everywhere (browser, node, cjs, esm, etc.)\
:warning: can warn you about unhandled exceptions\
:no_entry: no external dependencies

## Table of contents

- [Problem Description](#problem-description)
- [Solution](#solution)
- [Basics](#basics)
- [Examples](#examples)
- [API](#api)
- [Best Practices](#best-practices)
- [Comparisons](#comparisons)
- [Glossary](#glossary)

## Problem Description

Code can fail. Especially when you are accessing multiple services. The common way to handle errors is to throw them. But you won't really know what function could potentially throw an error in your application code.

Well written applications can differentiate between [errors](#error) and [exceptions](#exception). They crash on errors and can recover from exceptions.

Wrapping everything into `try-catch` blocks is not a good approach since it requires you to know the implementation of the function you are calling, adds a indentation level, alters the program flow and is easy to forget if you are not paying attention.

The exceptions you get in the `catch` block are typed as `unknown`, so you don't really know what happened and you need to account for different kind of exceptions (e.g. retry sending a request makes only sense if you got a network exception and will probably not make sense if you pass invalid payload to a service).

While it requires just a little of effort to look into a function to see what kind of exceptions get thrown, you probably can handle it manually. But in bigger applications you will probably have a lot of nesting and conditional logic where it is not so easy to spot all different outcomes of a function acll. It is easy to forget to handle an exception case or maybe you want to handle a case that was already handled inside that function, so you'll end up with code that will never be reached.

Adding a new kind of exception deep down in the nested functions would require you to take a look at all the code parts that call that function and check whether they should handle the exception or pass it to the next level.

## Solution

**Don't throw errors and exceptions, return them instead. That's it!**

No, there is a little bit more to it.

First of all, we need to make sure that in each part of the code we know what the outcome of a specific function call will be, without looking at the implementation. To do that, we always need to return data as well as exceptions. If we return everything, TypeScript can infer all types and we know what we get back when calling a function.

But now we also need a way to distinguish between a successful result and a result that contains an exception, so we need to wrap the value we return into an object. A by-product of this is that we need to unwrap the actual value at a later point, where we want to access it. This should be made as easiest as possible.

Because we don't throw exceptions, we don't use `try-catch` blocks. We need to use `if` statements to check whether or result contains a successful response or an exception.

Little helper functions, that are fully typed will greatly improve the Developer Experience. Of course we want our code to be explicit enough, so the code can be read and understood fast. This means we need to come up with meaningful names for our wrapping functions.

And because this is no rocket science, we don't need hundreds of dependencies to make this all happen. The library should be kept clean and efficient.

This packages delivers a solution to all the problems described above.

## Installation

### TypeScript version 5.0 or higher

```bash
npm install exceptionally
```

### TypeScript version 4.x

```bash
npm install exceptionally@2
```

> You should also set everything to [`strict` mode](https://www.typescriptlang.org/tsconfig#strict) in your `tsconfig.json` to get the most out of this package.

## Basics

```ts
import { success, exception } from 'exceptionally'

const doSomething = () => {
  const value = Math.random()
  // whenever you usually throw, return an `exception` instead
  // you can pass additional payload if you want
  if (value < 0.1) return exception('please try again')

// if a function can return an `exception`, you should wrap the returned element with `success`
  return success(value)
}

const result = doSomething()
// instead of having to use `try-catch`, you simply check if the result is an exception
if (result.isException) {
  // you can unwrap the exception, and the result will be typed as `string`
  console.error(result().toUppercase()) => 'PLEASE TRY AGAIN'
  return
}

// because we have handled the exception above, we are left with the `success` object
// unwrap it and it will be typed as a `number`
console.info(result().toPrecision(2)) // => e.g. '0.57'
```

## Examples

> You need to clone this repository locally and open it in your IDE (VS Code) to see typesafety in action. [StackBlitz](https://stackblitz.com/) and [github.dev](https://github.dev/github/dev) won't show TypeScript errors. Also the [TypeScript Playground](https://www.typescriptlang.org/play) is not able to show it correctly unless you set some specific options.

- [input validation](https://github.com/ivanhofer/exceptionally/blob/main/examples/input-validation.ts)
- [fetching data](https://github.com/ivanhofer/exceptionally/blob/main/examples/fetching-data.ts)

## API

### `exceptionally` - core functionality

All the core functionality to use in any project.

`import * from 'exceptionally'`

#### exposed functions

- **`success`**
- Wrap any value into a `Success` object.

```ts
  import { success } from 'exceptionally'

const saySomething = () => {
  	return success('hello world')
  }

const result = saySomething()

result.isSuccess // => `true`
  result.isException // => `false`
  result() // => `'hello world'`
  ```

- **`exception`**

Wrap any value into an `Exception` object.

```ts
  import { exception } from 'exceptionally'

const saySomething = () => {
  	return exception("Don't tell me what to do!")
  }

const result = saySomething()

result.isSuccess // => `false`
  result.isException // => `true`
  result() // => `"Don't tell me what to do!"`
  ```

- **`isExceptionallyResult`**

To check if any given value is a `Success` or `Exception` object.

```ts
  import { isExceptionallyResult, success } from 'exceptionally'

const result = Math.random() > 0.5 ? success(1) : 0

if (isExceptionallyResult(result)) {
  	const data = result()
  	console.info(data) // => `1`
  } else {
  	console.info(result) // => `0`
  }
  ```

#### exposed types

- **`Success`**

The type returned by `success()`.

```ts
  import { type Success, success } from 'exceptionally'

const result: Success = success(1)
  ```

- **`Exception`**

The type returned by `exception()`.

```ts
  import { type Exception, exception } from 'exceptionally'

const result: Exception = exception(1)
  ```

- **`ExceptionallyResult`**

Either a `Success` or a `Exception`.

```ts
  import { exception, type ExceptionallyResult } from 'exceptionally'

const result: ExceptionallyResult = Math.random() > 0.5 ? success(1) : exception(0)
  ```

- **`ExtractSuccess`**

Get the type of the `Success` object from a `ExceptionallyResult`.

```ts
  import { exception, type ExtractSuccess, success } from 'exceptionally'