Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/arthurfiorette/tuple-it
🦋 A simple Promise to [error, data] catcher.
https://github.com/arthurfiorette/tuple-it
async await error it js promise to tuple typescript
Last synced: about 24 hours ago
JSON representation
🦋 A simple Promise to [error, data] catcher.
- Host: GitHub
- URL: https://github.com/arthurfiorette/tuple-it
- Owner: arthurfiorette
- License: mit
- Created: 2024-05-07T00:27:54.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-10-28T21:00:03.000Z (3 months ago)
- Last Synced: 2025-01-15T22:20:19.216Z (8 days ago)
- Topics: async, await, error, it, js, promise, to, tuple, typescript
- Language: JavaScript
- Homepage: https://npm.im/tuple-it
- Size: 173 KB
- Stars: 40
- Watchers: 2
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Tuple it!
A simple Promise to [error, data] catcher.
- [Introduction](#introduction)
- [How to Use](#how-to-use)
- [Avoiding Global Scope Pollution](#avoiding-global-scope-pollution)
- [The `TupleItError` Class](#the-tupleiterror-class)
- [Promisable Objects](#promisable-objects)
- [Typescript Support](#typescript-support)
- [License](#license)
- [Credits](#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:
```typescript
import 'tuple-it/register'
```
Now, you can use the `.tuple()` method on any `Promise` object:
```typescript
async function work(promise: Promise) {
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`):
```typescript
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`:
```typescript
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:
```typescript
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:
```ts
import 'tuple-it/register'
import { t } from 'tuple-it'
// Custom error type (Defaults to Error)
const [customError, data] = await promise.then()
// Custom data type
const [error, customData] = await t(promise)
// Custom data and error types
const [customError, customData] = await t(promise)
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Credits
**TupleIt** draws heavy inspiration from [`await-to-js`](https://github.com/scopsy/await-to-js).