tuple-it
TypeScript icon, indicating that this package has built-in type declarations

1.1.0 • Public • Published
License Bundlephobia Codecov Downloads Bundlephobia Last commit Stars

Tuple it!

A simple Promise to [error, data] catcher.



Introduction

TupleIt is a handy utility designed to simplify error handling with async/await operations in JavaScript.

It wraps the await statement in a [error, data] tuple, allowing you to easily discern whether a promise was rejected or resolved without resorting to nested try/catch blocks.

This not only enhances code readability but also mitigates one of the most common mistakes in JavaScript development - mishandling promise rejections.


How to Use

[!CAUTION] Extending the Promise prototype in a library is considered a horrible practice.

TupleIt provides an import tuple-it/register to extend the Promise prototype:

import 'tuple-it/register'

Now, you can use the .tuple() method on any Promise object:

async function work(promise: Promise<WorkData>) {
  const [error, data] = await promise.tuple()

  if (error) {
    console.log('Operation failed!')
    return false
  }

  console.log('Operation succeeded!')
  return true
}

Avoiding Global Scope Pollution

If you're developing a library, it's advised not to pollute the global scope. Instead, you can import the t function directly (an alias for tuple):

import { t } from 'tuple-it'

const [error, data] = await t(someAsyncFunction())

The TupleItError Class

Occasionally, promises might reject with non-error objects, which is a poor practice but still happens. TupleIt will wrap any non-Error object into a TupleItError object if it's not an instance of Error:

import { TupleItError } from 'tuple-it'

async function someAsyncFunction() {
  throw 'Please avoid throwing strings!'
}

const [error, data] = await someAsyncFunction().tuple()

if (error instanceof TupleItError) {
  console.error(error.error) // Logs the original object that was thrown.
}

Promisable Objects

In some cases, functions may return either values or promises for performance optimization. TupleIt handles this scenario seamlessly:

import { t } from 'tuple-it'

function someFunction() {
  if (Math.random() > 0.5) {
    return 'Hello, World!'
  } else {
    return Promise.resolve('Hello, World!')
  }
}

// Works the same way!
const [error, data] = await t(someFunction())

Typescript Support

Typescript is fully supported:

import 'tuple-it/register'
import { t } from 'tuple-it'

// Custom error type (Defaults to Error)
const [customError, data] = await promise.then<CustomError>()

// Custom data type
const [error, customData] = await t<CustomData>(promise)

// Custom data and error types
const [customError, customData] = await t<CustomError, CustomData>(promise)

License

This project is licensed under the MIT License. See the LICENSE file for details.


Credits

TupleIt draws heavy inspiration from await-to-js.


Package Sidebar

Install

npm i tuple-it

Weekly Downloads

133

Version

1.1.0

License

MIT

Unpacked Size

10.5 kB

Total Files

7

Last publish

Collaborators

  • hazork