Installation

This package is distributed via npm. You can install it as a dependency in your project by running:

yarn add @micheldever/attempt

Usage

You can use either the synchronous or asynchronous method to remove any regular try-catch calls within your codebase. Both method return a tuple containing an error object and a result. If the asserted callback does not throw an error then the error index will be null. Equally, if an error is thrown then the result index will be null instead.

Synchronous

import { attempt } from '@micheldever/attempt';

const [error, result] = attempt(() => myThrowableMethod());

Asynchronous

import { attemptAsync } from '@micheldever/attempt';

const [error, result] = await attemptAsync(() => myAsyncThrowableMethod());

Custom Error Handler

Both methods can also take an optional error handler as a second parameter. This handler will only be called if the asserted callback throws an error.

function customErrorHandler(error: Error) {
  console.log(error);
}

const [error, result] = attempt(() => myThrowableMethod(), customErrorHandler);
const [error, result] = await attemptAsync(() => myAsyncThrowableMethod(), customErrorHandler);

Using Confirm

If you need to assert that a condition is true, and throw and error if it is not, you can use the confirm utility function to do so. This accepts a boolean condition as its first parameter and either a basic string error message, or a custom error object as its second.

When providing just a basic error message the resulting error will be thrown as a TypeError.

import { confirm } from '@micheldever/attempt';

const creature = {
  name: 'dragon',
  type: 'fire',
};

confirm(creature.name === 'dragon', 'creature must be a dragon');
confirm(creature.name === 'dragon', new MyCustomError('creature must be a dragon'));

When using the confirm method in a TypeScript environment, it also provides the additional benefit of automatically narrowing the type of a given variable.

const value: string | number = await fetchSomeDynamicValue();
// TypeScript thinks `value` could be either a string or a number

confirm(typeof value === 'string', 'value must be a string');
// TypeScript knows `value` must be a string