dethrown 🃏

Try-free result handling for TypeScript

Installation

Usage

dethrown helps you handle errors in TypeScript projects without relying on
try/catch. It provides helpers ok and err for representing success and
failure. It also includes a chain help that allows for lightweight functional
handling of results.

``typescript
import { err, ok, chain } from "dethrown";

function divide(numerator: number, denominator: number) {
if (denominator === 0) {
return err("Divide by zero error");
}

return ok(numerator / denominator);
}

const finalValue = chain(divide(12, 3))
.inspect(console.log)
.ifOK((value) => divide(value, 2))
.ifErr((error) => err(Something went wrong: ${error}))
.unwrap();

console.log(finalValue);
`

API Docs

- ok
- err
- unwrap
- tryCatch
- tryCatchAsync
- chain
- chain.inspect
- chain.inspectAsync
- chain.map
- chain.mapAsync
- chain.mapErr
- chain.mapErrAsync
- chain.ifOK
- chain.ifOKAsync
- chain.ifErr
- chain.ifErrAsync
- chain.result
- chain.unwrap

$3

`typescript
export function ok(t: T): OK
`

Creates an OK value representing a successful result.

#### Example

`typescript
import { ok } from "dethrown";

const result = ok(12);
console.log(result.ok); // true
console.log(result.value); // 12
`

$3

`typescript
export function err(error: E): Err
`

Creates an Err value respresenting a failure.

Err will often be used to wrap exceptions, but it's not required.

#### Example

`typescript
import { err } from "dethrown";

const result = err("It broke");
console.log(result.ok); // false
console.log(result.err); // It broke
`

$3

`typescript
export function unwrap(result: Result): T
`

Returns a value of type T or throws an error.

#### Example

`typescript
import { ok, err, unwrap } from "dethrown";

const good = ok("Good");
console.log(unwrap(good)); // Good

const bad = err("So bad");

// will throw
console.log(unwrap(bad));
`

$3

`typescript
export function tryCatch(fn: () => T): Result
`

tryCatch takes in a function, calls it, and returns a result containing the
return value of the function or any exceptions thrown.

#### Example

`typescript
import { tryCatch } from "dethrown";


const result = tryCatch(() => {
return mightThrow();
});
`

$3

`typescript
export async function tryCatch(fn: () => Promise): Promise>
`

tryCatchAsync takes in an async function, calls it, and returns a result
containing the return value of the function or any exceptions thrown.

#### Example

`typescript
import { tryCatchAsync } from "dethrown";


const result = tryCatchAsync(async() => {
return await mightThrow();
});
`

$3

`typescript
export function chain(r: T | Result): ResultChain)
`

Chain takes a value or a result and allows for chained calls against it.
Chain itself always returns a ResultChain, but chained calls may return a
ResultChain or AsyncResultChain depending on if the chained function is
async or not. Once an async function is called, the remaining calls always
return an AsyncResultChain.

#### Example

`typescript
const chainResult = chain("Frank")
.map((name) => Hello ${name}!)
.map((message) => ${message} How are you?)
.result();

const chainResult = chain(ok("Frank"))
.map((name) => Hello ${name}!)
.map((message) => ${message} How are you?)
.result();

const asyncChainResult = await chain(ok("Frank"))
.mapAsync((name) => find(name))
.mapAsync((user) => updateUser({ name: "Frank Smith" }))
.result();
`

$3

`typescript
chain.inspect(fn: (r: Result) => void): ResultChain
asyncChain.inspect(fn: (r: Result) => void): AsyncResultChain
`

inspect calls the given function on the current result in the chain and
returns a chain with the same Result. It's useful for cases like logging a
value in a chain.

#### Example

`typescript
chain("Frank")
.map((firstName) => ${name} Smith)
.inspect((fullName) => console.log(fullName))
.result();
`

$3

`typescript
chain.inspectAsync(fn: (r: Result) => Promise): AsyncResultChain;
asyncChain.inspectAsync(fn: (r: Result) => Promise): AsyncResultChain;
`

inspectAsync is identical to inspect except that it takes an async function
and results in an AsyncResultChain.


#### Example

`typescript
await chain("Frank")
.map((firstName) => ${firstName} Smith)
.inspectAsync(async (fullName) => await auditLog(fullName))
.result();
`

$3

`typescript
chain.map(fn: (t: T) => U): ResultChain;
asyncChain.map(fn: (t: T) => U): AsyncResultChain;
`

map converts one type of OK value into another. If the current result in
the chain is OK, calls fn with the current result value as an argument.
Otherwise, passes the current result along the chain.

#### Example

`typescript
chain("Frank")
.map((firstName) => ${name} Smith)
result();
`

$3

`typescript
chain.mapAsync(fn: (t: T) => Promise): AsyncResultChain;
asyncChain.mapAsync(fn: (t: T) => Promise): AsyncResultChain;
`

mapAsync converts one type of OK value into another, just like map, but
allows the conversion function to be async. If the current result in the chain
is OK, calls the given async fn with the current result value as an argument.
Otherwise, passes the current result along the chain.

#### Example

`typescript
await chain(username)
.mapAsync(async (username) => await loadUser(username))
.result();
`

$3

`typescript
chain.mapErr(fn: (e: E) => S): ResultChain;
asyncChain.mapErr(fn: (e: E) => S): AsyncResultChain;
`

mapErr converts one type of Err value into another. If the current result
in the chain is Err, calls the given fn with the current error value as an
argument. Otherwise, passes the current result along the chain.

#### Example

`typescript
chain(err("It broke"))
.mapErr((error) => Cause: ${error})
.result();
`

$3

`typescript
chain.mapErrAsync(fn: (e: E) => Promise): AsyncResultChain;
asyncChain.mapErrAsync(fn: (e: E) => Promise): AsyncResultChain;
`

mapErrAsync converts one type of Err value into another, just like mapErr,
but allows the conversion function to be async. If the current result in the
chain is Err, calls the given async fn with the current error value as an
argument. Otherwise, passes the current result along the chain.

#### Example

`typescript
await chain(username)
.ifOKAsync((value) => await loadUserByUsername(value))
.mapErrAsync(async (error) => await loadUserByEmail(r.value))
.result();
`

$3

`typescript
chain.ifOK(fn: (r: T) => Result): ResultChain;
asyncChain.ifOK(fn: (r: T) => Result): ResultChain;
`

If the current result in the chain is OK, calls the given fn with the
current value as an argument. Otherwise, passes the current result along the
chain.

#### Example

`typescript
chain(username)
.ifOK((value) => validateUsername(value))
.result();
`

$3

`typescript
chain.ifOKAsync(fn: (r: T) => Promise>): AsyncResultChain;
asyncChain.ifOKAsync(fn: (r: T) => Promise>): AsyncResultChain;
`

If the current result in the chain is OK, calls the given async fn with the
current value as an argument. Otherwise, passes the current result along the
chain.

#### Example

`typescript
await chain(username)
.ifOKAsync((value) => await loadUser(value))
.result();
`

$3

`typescript
chain.ifErr(fn: (r: E) => Result): ResultChain;
asyncChain.ifErr(fn: (r: E) => Result): AsyncResultChain;
`

If the current result in the chain is Err, calls the given fn with the
current error value as an argument. Otherwise, passes the current result along
the chain.

#### Example

`typescript
chain(divisor)
.ifOK((value) => divide(12, value))
.ifErr((error) => ok(0))
.result();
`

$3

`typescript
chain.ifErrAsync(fn: (r: E) => Promise>): AsyncResultChain;
asyncChain.ifErrAsync(fn: (r: E) => Promise>): AsyncResultChain;
`

If the current result in the chain is Err, calls the given async fn with
the current error value as an argument. Otherwise, passes the current result
along the chain.

#### Example

`typescript
await chain(newPlan)
.ifOKAsync((r) => await setPlan(r.value))
.ifErrAsync((r) => {
return err({
message: r.err.message,
planOptions: await listPlans()
});
})
.result();
`

$3

`typescript
chain.result(): Result;
asyncChain.result: Promise>;
`

Returns the last result value on the chain. If it's an async chain, returns
a promise that will resolve to the last result once all promises in the chain
have completed.

#### Example

`typescript
// returns a Result
chain(userId)
.map(loadUser)
.result();
`

$3

`typescript
chain.unwrap(): T;
asyncChain.unwrap(): Promise;
`

Like unwrap, either returns the success value or throws the error
value for the last result on the chain.

#### Example

`typescript
// returns the user or throws if the user wasn't found
chain(userId)
.map(loadUser)
.unwrap();
``

License

MIT. See LICENSE for details.