- Introduction
- How to Use
- Avoiding Global Scope Pollution
- The
TupleItError
Class - Promisable Objects
- Typescript Support
- License
- Credits
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.
[!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
}
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())
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.
}
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 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)
This project is licensed under the MIT License. See the LICENSE file for details.
TupleIt draws heavy inspiration from await-to-js
.