unres v0.2.1

unres

unres is a streamlined utility library that simplifies error handling by wrapping promises or functions and returning an object or tuple with data and error properties. This eliminates the necessity of using try/catch blocks, enhancing the readability and maintainability of your code:

let result

try {
  result = await client.getItems()
}
catch (error) {
  console.error(error)
}

import { guardedInvoke } from 'unres'

const { data, error } = await guardedInvoke(client.getItems())

if (error)
  console.error(error)

If you prefer to use tuples instead of objects, you can also destructure the return value of guardedInvoke as a tuple:

import { guardedInvoke } from 'unres'

// Destructuring a tuple is also supported
const [data, error] = await guardedInvoke(client.getItems())

Key Features

• 💆‍♂️ Returns an object or tuple with data and error properties
• 📼 Functions can be synchronous or asynchronous
• 🛠️ Supports custom rejected Promise error types
• 🦾 Strongly typed

Installation

Installing unres is as simple as running the following command:

pnpm add unres

# Or with npm
npm install unres

# Or with yarn
yarn add unres

Usage

Once installed, you can import the guardedInvoke function from unres and use it to wrap promises or functions in your code. Below are some usage examples that illustrate the key functionalities of unres:

Handling Errors in Async Functions

unres simplifies error handling in asynchronous functions using the guardedInvoke function. If an error occurs, it is assigned to the error property and can be handled accordingly.

import { guardedInvoke } from 'unres'

const { data, error } = await guardedInvoke(client.getItems())

if (error)
  console.error(error)

Handling Errors in Synchronous Functions

The guardedInvoke function can also be used with synchronous functions.

import { guardedInvoke } from 'unres'

const { data, error } = guardedInvoke(() => {
  throw new Error('Something went wrong')
})

if (error)
  console.error(error)

Using Tuples

In addition to returning objects, guardedInvoke can also return a tuple containing data and error values. This provides a neat, organized structure for error management:

import { guardedInvoke } from 'unres'

const [data, error] = await guardedInvoke(client.getItems())

if (error)
  console.error(error)

Guarded Functions

With guardedInvokeFn you can create a function that can be called with the same arguments, but guarded. This is useful when you want to guard a function that you don't own, like JSON.parse:

import { guardedInvokeFn } from 'unres'

const safeJSONParse = guardedInvokeFn(JSON.parse)

let result = safeJSONParse('{ "test": 1 }')
console.log(result.data) // { test: 1 }

result = safeJSONParse('{ missing the other one')
console.log(result.error) // SyntaxError: Unexpected character 'm'

Custom Error Handling

unres offers the flexibility to implement custom error handling strategies by overriding the default error type. This can be done by passing a custom error type as the second argument to the guardedInvoke function:

import { guardedInvoke } from 'unres'

class CustomError extends Error {}

const [data, error] = guardedInvoke(() => {
  throw new CustomError('Something went wrong')
}, CustomError)

// The `error` variable will properly be typed as `CustomError`
if (error) {
  console.log(error instanceof CustomError) // `true`
  console.error(error)
}

Credits

• Henrique Cunha for his resguard library, which inspired this project.
• Anthony Fu for his post on destructuring with object or array.

License

MIT License © 2023-PRESENT Johann Schopplich