git clone https://mtsweb@dev.azure.com/mtsweb/oss/_git/attempt

Installation

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

``bash
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.

$3

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

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

$3

`typescript
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.

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

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

$3

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.

`typescript
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.

`typescript
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
``