• Introduction
• How to Use
• Avoiding Global Scope Pollution
• The TupleItError Class
• Promisable Objects
• Typescript Support
• License
• Credits

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.