Class Attempt<T>

Typed error handling for calling functions

import { Attempt } from "@testingrequired/attempted";

let attempt: Attempt<number> = Attempt.of(fnMightThrow, ...fnArgs);

// Returns true if function didn't throw or returned a failed attempt
attempt.isSuccessful();

// Returns true if function throws or returned a failed attempt
attempt.isFailure();

// You can conditionally run functions on successful or failed attempts
attempt.ifSuccessful((value) => {});
attempt.ifFailure((error) => {});
attempt.ifElse(
  (value) => {},
  (error) => {}
);

// Map over successful attempts
// This will not run on a failed attempt
attempt = attempt.map((n) => n * 2);

// Assert over successful attempts
// Failed assertions will return a failed attempt
// This will not run on a failed attempt
attempt = attempt.assert(
  (value) => value > 100,
  (value) => `Value ${value} was less than 100`
);

// Returns value on successful attempts
// Throws on failed attempts
attempt.get();

// Returns error on failed attempts
// Throws on successful attempts
attempt.getError();

// Get value on successful attempts or a default value.
attempt.orElse(defaultValue);

// Get value or throw provided error
attempt.orThrow(new Error("Something went wrong"));
attempt.orThrow("Something went wrong");

// You can pass function to access a failed attempt's error
attempt.orThrow((error) => new Error(`Something went wrong: ${e}`));
attempt.orThrow((error) => `Something went wrong`);

It also works with async functions!

import { Attempt } from "@testingrequired/attempted";

// Await the attempt the same as you would await the function call
let attempt: Attempt<number> = await Attempt.of(asyncFnMightThrow, ...fnArgs);

// You can use async functions to map as well
attempt = await attempt.map(async (n) => n * 2);

// Returns the attempts value
attempt.get();

You can also wrap a function to be called later

const attemptFnMightThrow = Attempt.wrap(fnMightThrow);
const attempt: Attempt<number> = attemptFnMightThrow(...fnArgs);

Type Parameters

T

The successful value type

Hierarchy

Attempt

Index

Constructors

`Private` constructor

new Attempt<T>(value, error): Attempt<T>
Type Parameters
- T
Parameters
- value: undefined | T
- error: unknown
Returns Attempt<T>
- Defined in src/attempt.ts:89

Properties

`Private` `Readonly` #error

#error: unknown

Error when the attempt failed

`Private` `Readonly` #value

#value: undefined | T

Value when the attempt was successful

Methods

assert

assert(assertionFn, errorFn): Attempt<T>

Assert against a successful attempt's value

Attempt.ofValue(123)
  .assert(value => value > 100, (value) => new Error("Number isn't greater than 100"))
  .get() // 123

Attempt.ofValue(123)
  .assert(value => value < 100, (value) =>  new Error(`Number $(value) isn't less than 100`))
  .getError() // Error("Number 123 isn't less than 100")

Attempt.ofError<number>("Something went wrong")
  .assert(value => value > 100, (value) => new Error("Number isn't greater than 100"))
  .getError() // Error("Something went wrong")

Parameters

assertionFn: ((value) => boolean)

Assertion function to run
- - (value): boolean
  - Parameters
    - value: T
    Returns boolean
errorFn: ((value) => unknown)

Function that returns an error if the assertion fails
- - (value): unknown
  - Parameters
    - value: T
    Returns unknown

Returns Attempt<T>

Either success/failed attempt from the assertion or the failed attempt it was called on

get

get(): T
Get value from successful attempt. Throws if failed attempt.
```
Attempt.ofValue(123).get() // 123
Attempt.ofError("...").get() // Throws
```
Returns T
Value from a success attempt
- Defined in src/attempt.ts:257

getError

getError(): unknown
Get error from failed attempt. Throws if successful attempt.
```
Attempt.ofError("...").getError() // "..."
Attempt.ofError("...").getError() // Throws
```
Returns unknown
Error from a failed attempt
- Defined in src/attempt.ts:275

ifElse

ifElse(successFn, failureFn): void
Run success or failure function based on attempt
```
Attempt.ofValue(123)
  .ifElse(
    value => console.log(`It worked! ${value}`),
    error => console.log(`It failed! ${error}`)
  )
```
Parameters
- successFn: ((value) => any)
  
  Function to run on successful attempt
  - - (value): any
    - Parameters
      
      value: T
      
      Returns any
- failureFn: ((error) => any)
  
  Function to run on failed attempt
  - - (error): any
    - Parameters
      
      error: unknown
      
      Returns any
Returns void
- Defined in src/attempt.ts:442

ifFailure

ifFailure(fn): void
Run function is attempt failed
```
Attempt.ofError("...").ifFailure(error => {}) // Runs
Attempt.ofValue(123).ifFailure(error => {}) // Doesn't run
```
Parameters
- fn: ((error) => any)
  
  Fucntion to run
  - - (error): any
    - Parameters
      
      error: unknown
      
      Returns any
Returns void
- Defined in src/attempt.ts:460

ifSuccess

ifSuccess(fn): void
Run function if attempt was successful
```
Attempt.ofValue(123).ifSuccess(value => {}) // Runs
Attempt.ofError("...").ifSuccess(value => {}) // Doesn't run
```
Parameters
- fn: ((value) => any)
  
  Function to run
  - - (value): any
    - Parameters
      
      value: T
      
      Returns any
Returns void
- Defined in src/attempt.ts:422

isFailure

isFailure(): boolean

Get if attempt failed

Attempt.ofError("...").isFailure() // true
Attempt.ofValue(123).isFailure() // false

Returns boolean

Boolean if attempt failed

isSuccess

isSuccess(): boolean
Get if attempt was successful
```
Attempt.ofValue(123).isSuccess() // true
Attempt.ofError("...").isSuccess() // false
```
Returns boolean
Boolean if attempt was successful
- Defined in src/attempt.ts:386

map

map<Fn>(fn): IfExtends<ReturnType<Fn>, Promise<any>, IfExtends<Awaited<ReturnType<Fn>>, Attempt<any>, Awaited<ReturnType<Fn>>, Promise<Attempt<Awaited<ReturnType<Fn>>>>>, IfExtends<ReturnType<Fn>, Attempt<any>, ReturnType<Fn>, Attempt<ReturnType<Fn>>>>
Map a success attempt or return the current failed attempt
```
Attempt.ofValue(123).map(value => value * 2).get() // 456

Attempt.ofValue(123)
  .map(value => {
   throw new Error("Something went wrong");
   return value;
  })
  .map(value => value * 2)
  .getError() // Error("Something went wrong")
```
Type Parameters
- Fn extends ((value) => any)
  
  Mapping function
Parameters
- fn: Fn
  
  Function to map over attempt
Returns IfExtends<ReturnType<Fn>, Promise<any>, IfExtends<Awaited<ReturnType<Fn>>, Attempt<any>, Awaited<ReturnType<Fn>>, Promise<Attempt<Awaited<ReturnType<Fn>>>>>, IfExtends<ReturnType<Fn>, Attempt<any>, ReturnType<Fn>, Attempt<ReturnType<Fn>>>>
Either mapped success attempt or the current failed attempt
- Defined in src/attempt.ts:361

orElse

orElse(defaultValue): T
Get value from successful attempt or a default value on a failed attempt
```
Attempt.ofValue(123).orElse(456) // 123
Attempt<number>.ofError("...").orElse(456) // 456
```
Parameters
- defaultValue: T
Returns T
Successful attempt value or default value
- Defined in src/attempt.ts:293

orThrow

orThrow<ErrorToThrow>(errorToThrow): T
Get value from successful attempt or a throw error
```
Attempt.ofValue(123).orThrow(456) // 123
Attempt<number>.ofError("...").orThrow("Something went wrong") // Error("Something went wrong")
```
You can also get the error from a failed attempt
```
Attempt<number>.ofError("...").orThrow((e) => "Something went wrong: ${e}") // Error("Something went wrong: ...")
```
Type Parameters
- ErrorToThrow extends Error = Error
Parameters
- errorToThrow: string | ErrorToThrow | ((error) => string | ErrorToThrow)
Returns T
Successful attempt value
- Defined in src/attempt.ts:317

`Static` of

of<Fn>(fn, ...fnArgs): IfExtends<ReturnType<Fn>, Promise<any>, IfExtends<Awaited<ReturnType<Fn>>, Attempt<any>, Awaited<ReturnType<Fn>>, Promise<Attempt<Awaited<ReturnType<Fn>>>>>, IfExtends<ReturnType<Fn>, Attempt<any>, ReturnType<Fn>, Attempt<ReturnType<Fn>>>>
Create an attempt from a function.
```
// Attempt<ReturnType<typeof fnThatMightThrow>>
const attempt = Attempt.of(fnThatMightThrow, fnArg1, fnArg2, ...);
```
Async works too!
```
// Promise<Attempt<ReturnType<typeof fnThatMightThrow>>>
const attemptPromise = Attempt.of(asyncFnThatMightThrow, fnArg1, fnArg2, ...);
// Attempt<ReturnType<typeof fnThatMightThrow>>
const attempt = await attemptPromise;
```
This also works with functions that return an Attempt
```
const value = 123;
const attemptA = Attempt.ofValue(value);
const attemptB = Attempt.of(() => attemptA); // Attempt<number>

attemptB.get(); // 123
```
Type Parameters
- Fn extends ((...args) => any)
  
  Function to be called
Parameters
- fn: Fn
  
  Function to run
- Rest ...fnArgs: Parameters<Fn>
  
  Arguments to pass when calling function
Returns IfExtends<ReturnType<Fn>, Promise<any>, IfExtends<Awaited<ReturnType<Fn>>, Attempt<any>, Awaited<ReturnType<Fn>>, Promise<Attempt<Awaited<ReturnType<Fn>>>>>, IfExtends<ReturnType<Fn>, Attempt<any>, ReturnType<Fn>, Attempt<ReturnType<Fn>>>>
Either a successful or failing attempt
- Defined in src/attempt.ts:127

`Static` ofError

ofError<T, E>(error): E extends Attempt<U>
? Attempt<U>
: Attempt<T>
Create a failed attempt result from an error
```
// Attempt<unknown>
const failedAttemptWithError = Attempt.ofError(new Error("Something went wrong"));

// Attempt<unknown>
const failedAttemptWithString = Attempt.ofError("Something went wrong");
```
Type Parameters
- T = unknown
  
  Value type if attempt had succeeded
- E = unknown
Parameters
- error: E
  
  Error for the failed attempt
Returns E extends Attempt<U>
? Attempt<U>
: Attempt<T>
Attempt with failure error
- Defined in src/attempt.ts:229

`Static` ofValue

ofValue<T>(value): T extends Attempt<any>
? T
: Attempt<T>
Create a successful attempt from a value
```
// Attempt<number>
const attempt = Attempt.ofValue(123);
```
Type Parameters
- T
  
  Value for the successful attempt
Parameters
- value: T
  
  Value of successful attempt
Returns T extends Attempt<any>
? T
: Attempt<T>
Attempt with a success value
- Defined in src/attempt.ts:197

`Static` wrap

wrap<Fn>(fn): ((...args) => IfExtends<ReturnType<Fn>, Promise<any>, IfExtends<Awaited<ReturnType<Fn>>, Attempt<any>, Awaited<ReturnType<Fn>>, Promise<Attempt<Awaited<ReturnType<Fn>>>>>, IfExtends<ReturnType<Fn>, Attempt<any>, ReturnType<Fn>, Attempt<ReturnType<Fn>>>>)
Wrap the underlying function to be called as an attempt
```
function sum(...args: number[]): number {
  return args.reduce((acc, curr) => acc + curr, 0);
}

const attemptToSum = Attempt.wrap(sum);

const sumValue = attemptToSum(1, 2, 3)
  .orThrow(e => `Unable to sum: {e}`); // 6
```
Type Parameters
- Fn extends ((...args) => any)
Parameters
- fn: Fn
  
  Function to wrap
Returns ((...args) => IfExtends<ReturnType<Fn>, Promise<any>, IfExtends<Awaited<ReturnType<Fn>>, Attempt<any>, Awaited<ReturnType<Fn>>, Promise<Attempt<Awaited<ReturnType<Fn>>>>>, IfExtends<ReturnType<Fn>, Attempt<any>, ReturnType<Fn>, Attempt<ReturnType<Fn>>>>)
A function that calls the underlying function
- - (...args): IfExtends<ReturnType<Fn>, Promise<any>, IfExtends<Awaited<ReturnType<Fn>>, Attempt<any>, Awaited<ReturnType<Fn>>, Promise<Attempt<Awaited<ReturnType<Fn>>>>>, IfExtends<ReturnType<Fn>, Attempt<any>, ReturnType<Fn>, Attempt<ReturnType<Fn>>>>
  - Wrap the underlying function to be called as an attempt
```
function sum(...args: number[]): number {
  return args.reduce((acc, curr) => acc + curr, 0);
}

const attemptToSum = Attempt.wrap(sum);

const sumValue = attemptToSum(1, 2, 3)
  .orThrow(e => `Unable to sum: {e}`); // 6
```
    Parameters
    - Rest ...args: Parameters<Fn>
    Returns IfExtends<ReturnType<Fn>, Promise<any>, IfExtends<Awaited<ReturnType<Fn>>, Attempt<any>, Awaited<ReturnType<Fn>>, Promise<Attempt<Awaited<ReturnType<Fn>>>>>, IfExtends<ReturnType<Fn>, Attempt<any>, ReturnType<Fn>, Attempt<ReturnType<Fn>>>>
    A function that calls the underlying function
- Defined in src/attempt.ts:177

Class Attempt<T>

Type Parameters

T

Hierarchy

Index

Constructors

Properties

Methods

Constructors

Private constructor

Type Parameters

T

Parameters

value: undefined | T

error: unknown

Returns Attempt<T>

Properties

Private Readonly #error

Private Readonly #value

Methods

assert

Parameters

assertionFn: ((value) => boolean)

Parameters

value: T

Returns boolean

errorFn: ((value) => unknown)

Parameters

value: T

Returns unknown

Returns Attempt<T>

get

Returns T

getError

Returns unknown

ifElse

Parameters

successFn: ((value) => any)

Parameters

value: T

Returns any

failureFn: ((error) => any)

Parameters

error: unknown

Returns any

Returns void

ifFailure

Parameters

fn: ((error) => any)

Parameters

error: unknown

Returns any

Returns void

ifSuccess

Parameters

fn: ((value) => any)

Parameters

value: T

Returns any

Returns void

isFailure

Returns boolean

isSuccess

Returns boolean

map

Type Parameters

Fn extends ((value) => any)

Parameters

fn: Fn

Returns IfExtends<ReturnType<Fn>, Promise<any>, IfExtends<Awaited<ReturnType<Fn>>, Attempt<any>, Awaited<ReturnType<Fn>>, Promise<Attempt<Awaited<ReturnType<Fn>>>>>, IfExtends<ReturnType<Fn>, Attempt<any>, ReturnType<Fn>, Attempt<ReturnType<Fn>>>>

orElse

Parameters

defaultValue: T

Returns T

orThrow

Type Parameters

ErrorToThrow extends Error = Error

Parameters

errorToThrow: string | ErrorToThrow | ((error) => string | ErrorToThrow)

Returns T

`Private` constructor

`Private` `Readonly` #error

`Private` `Readonly` #value

`Static` of

`Rest` ...fnArgs: Parameters<Fn>

`Static` ofError

Returns E extends Attempt<U>
? Attempt<U>
: Attempt<T>

`Static` ofValue

Returns T extends Attempt<any>
? T
: Attempt<T>

`Static` wrap

`Rest` ...args: Parameters<Fn>