# async-unwrap

> Simple tool to avoid try-catch blocks

Latest version **1.1.0** (published 2020-02-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install async-unwrap
pnpm add async-unwrap
yarn add async-unwrap
bun add async-unwrap
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2020-02-15 |
| First published | 2018-09-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 6.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Ben Snow |
| Maintainers | b3nsn0w |
| Keywords | async, promise, unwrap |

## Links

- npm: https://www.npmjs.com/package/async-unwrap
- Repository: https://github.com/b3nsn0w/async-unwrap
- Homepage: https://github.com/b3nsn0w/async-unwrap#readme
- Issues: https://github.com/b3nsn0w/async-unwrap/issues
- npm.io page: https://npm.io/package/async-unwrap

## Alternatives

- [promise-throttle](https://npm.io/package/promise-throttle.md) — 44.2K weekly downloads
- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2020-02-15
- 1.0.2 — 2019-06-06
- 1.0.1 — 2018-09-14
- 1.0.0 — 2018-09-14

## README

Async-await can help you write some amazing-looking and very readable code, but [if you're anything like me](https://xkcd.com/1567/), you probably hate burying it into try-catch blocks. With `async-unwrap`, you can go from this:

```javascript
async () => {
  try {
    await someAsyncOperation()
  } catch (err) {
    doSomething(err)
  }
}
```

to this:

```javascript
async () => {
  const [err, result] = await someAsyncOperation()[unwrap]
  if (err) return doSomething(err)
}
```

# But how?

First, you need to say the magic word:

```javascript
const unwrap = require('async-unwrap')
// or if the above is way too old for you:
import unwrap from 'async-unwrap'
```

This gives you a symbol that's attached to the prototype of every promise (or other thenable), which turns that promise into another one. The "unwrapped" promise will resolve to a ~~tuple~~ two-element array of `[null, result]` if the base promise is resolved and `[err, null]` if it's rejected. This allows you to handle your errors in a slightly different way, without breaking the block scope.

If you're using multiple async calls in a function, I'd recommend structuring your code in the following way:

```javascript
async () => {
  const [firstError, firstResult] = await firstOperation()[unwrap]
  if (firstError) throw firstError // we'll handle it on a higher level

  const [secondError, secondResult] = await secondOperation(firstResult)[unwrap]
  if (secondError) throw sanitize(secondError) // sometimes you'll need some special treatment

  return secondResult
}
```

Exercise to the reader: try writing that without nested try-catch blocks or falling back to `let`.

# Local offensive

Before you ask, yes, that does modify global variables, specifically `Object.prototype`, which is actually the variable you should have the most caution with modifying. `async-unwrap` uses a symbol to define a non-enumerable getter, minimizing the surface for errors (it's practically invisible in normal usage), but in some exotic cases you might still run into problems with that. If you'd like to not take that chance, there is a "function" variant of the library:

```javascript
import unwrap from 'async-unwrap/func'

async () => {
  const [err, result] = await unwrap(someAsyncOperation())
  if (err) return doSomething(err)
}
```

Why is this not the default? Well, frankly because I think it's ugly, but to each their own. You can use the function variant if you'd like to, no hard feelings.

# Compatibility

Everything, theoretically. The library binds to all objects and simply checks for a `then()` method, which is the JS spec's way of deciding if something is a promise. This should enable it to work seamlessly with custom promise implementations. If you still run into any compatibility issues, please [submit a bug report](https://github.com/b3nsn0w/async-unwrap/issues/new).

# Contributing

Pull requests are welcome. As always, be respectful towards each other and maybe run or create tests, as appropriate. It's on `npm test`, as usual.

async-unwrap is available under the MIT license.

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