do-try-tuple    

Catches errors and rejected promises, returns tuple with error and value.

- Installation
- Usage
- Async Usage
- API
- doTry function
- safe promise wrapper
- Failure type
- Success type
- ErrValueTuple type
- failure and success factory functions
- isFailure and isSuccess type guards
- Using doTry().then()

Installation

``bash
npm install do-try-tuple
`

Usage

`typescript
import doTry from 'do-try-tuple';

function div(a: number, b: number): number {
if (b !== 0) return a / b;
if (a !== 0) throw new Error(Division by Zero);
throw new Error('Indeterminate Form');
}

const [isDivOk, errX, x] = doTry(() => div(4, 2));

if (isDivOk) {
const doubleX = x * 2;
console.log('doubleX:', doubleX);
}
`

Async Usage

`typescript
import doTry from 'do-try-tuple';

const [areUsersFetched, error, users] = await doTry(() => fetchUsers());

if (!areUsersFetched) {
console.error('Failed to fetch users:', error);
} else {
console.log('Users:', users);
}
`

or

`typescript
import { safe } from 'do-try-tuple';

const [areUsersFetched, error, users] = await safe(fetchUsers());

if (!areUsersFetched) {
console.error('Failed to fetch users:', error);
} else {
console.log('Users:', users);
}
`

API

The library exports:

- doTry function (default export)
- safe promise wrapper to make it resolving to ErrValueTuple
- Failure, Success and ErrValueTuple types
- failure and success factory functions
- isFailure and isSuccess type guards

$3

takes a function that may throw an error or return a promise that may be rejected.

`typescript
function (fn: () => never): readonly [false, unknown, never];
function (fn: () => Promise): Promise;
function (fn: () => Promise): Promise>;
function (fn: () => T): ErrValueTuple;
`

$3

is a function that wraps a promise and makes it resolving to ErrValueTuple:

`typescript
function safe(promise: Promise): Promise>;
`

It could be useful when you need to handle the promise rejection synchronously:

`typescript
import { safe } from 'do-try-tuple';

const [areUsersFatched, error, users] = await safe(fetchUsers());
`

$3

is a tuple representing the error case:

`typescript
export type Failure = readonly [ok: false, error: E, value: undefined];
`

The library respects the same motivation as caused introduction
useUnknownInCatchVariables
compiler option in TypeScript:

$3

is a tuple representing the success case:

`typescript
export type Success = readonly [ok: true, error: undefined, value: T];
`

$3

is a union of Failure and Success.

`typescript
export type ErrValueTuple = Failure | Success;
`

$3

These functions allow to create ErrValueTuple instances:

`typescript
export function failure(error: E): Failure;
export function success(value: T): Success;
`

It could be useful in tests:

`typescript
import { success, failure } from 'do-try-tuple';

test('div', () => {
expect(doTry(() => div(4, 2))).toEqual(success(2));
expect(doTry(() => div(4, 0))).toEqual(failure(new Error('Division by Zero')));
expect(doTry(() => div(0, 0))).toEqual(failure(new Error('Indeterminate Form')));
});
`

$3

These functions allow to check if the value is Failure or Success:

`typescript
export function isFailure(value: ErrValueTuple): value is Failure;
export function isSuccess(value: ErrValueTuple): value is Success;
`

It allows to check the result and narrow the type without destructuring:

`typescript

class DivError extends Error {
constructor(message: string) {
super(message);
this.name = 'DivError';
}
}

function divWithTypeError(a: number, b: number): ErrValueTuple {
const result = doTry(() => div(a, b));

if (isSuccess(result)) return result;
return failure(new DivError('Failed to divide'));
}
`

Using doTry().then()

You can map the result of doTry applied to function returning a promise using then method:

`typescript
import doTry from 'do-try-tuple';

const [error, users] = await doTry(() => fetchUsers()).then(
([err, users]) => [err && new SomeCustomError(err), users] as const,
);
`

However, consider that functions returning promises can throw error synchronously:

`typescript
const fetchUsers = (): Promise => {
if (Math.random() < 0.5) throw new Error('Failed to fetch users');
return Promise.resolve(['Alice', 'Bob', 'Charlie']);
};
`

So, the doTry in this case returns an ErrValueTuple synchronously, and the
attempt to call then method on it will throw an error:
TypeError: doTry(...).then is not a function.

To handle this case, just add async keyword before fn argument:

`typescript
const [error, users] = await doTry(async () => fetchUsers()).then(
([err, users]) => [err && new SomeCustomError(err), users] as const,
);
`

So, use

`typescript
// CORRECT _____
const [err, value] = await doTry(async () => someFn(...))
.then(([err, value]) => {
// handle err and value
});
`

instead of

`typescript
// WRONG ___________
const [err, value] = await doTry(/ async /() => someFn(...))
.then(([err, value]) => {
// handle err and value
});
`

The same is relevant for any other method of Promise class, like catch, finally`, etc.