ishod

ishod is a really small (<0.5kb gzipped) and simple utility library for working with promises and results.

It helps you handle errors uniformly and safely across sync and async code.

The motivational blog post can be found here: https://josip.igr.ec/blog/building-result-in-typescript/

Installation

Using your package manager of choice:

npm install @allynet/ishod
Copy

yarn add @allynet/ishod
Copy

pnpm install @allynet/ishod
Copy

bun install @allynet/ishod
Copy

Examples

import { $result } from "@allynet/ishod";

// Do an unsafe operation safely
const gamble = $result.try$(() => {
  if (Math.random() > 0.5) {
    return 5;
  }

  throw new Error("error");
});

// And process the result safely
const doubled = $result.map(gamble, (x) => x * 2);

// Or log the error if it happens
$result.tapErr(gamble, (error) => {
  console.error(error);
});

// without having to check everything yourself
// or creating a bunch of `let val = null` variables
Copy

import { $result } from "@allynet/ishod";

const requestJson = (url: string) =>
  $result
    .try$(fetch(url))
    .then((x) => $result.map(x, (res) => res.json()))
    .then((x) => $result.tapErr(x, (error) => console.error(error)));

const response = await requestJson("https://api.example.com/data");

if ($result.isOk(response)) {
  const data = $result.unwrap(response);
  console.log(`Got the response data right here: ${data}`);
}
Copy

import { $result } from "@allynet/ishod";

const divide = (a: number, b: number) => {
  if (b === 0) {
    return $result.err("division by zero");
  }

  if (a === b) {
    return $result.err("division by itself");
  }

  return $result.ok(a / b);
};

const result = divide(1, 0);
//    ^? Result<number, "division by zero" | "division by itself">

const resultDoubled = $result.map(result, (x) => x * 2);
//    ^? Result<number, "division by zero" | "division by itself">
Copy

Docs overview

The full documentation is available at https://allynet.github.io/ishod/.

The following is a quick overview of the API.

Result

ishod provides a Result type that can be used to represent the result of an operation.

It boils down to the following:

type Result<T, E> = Ok<T> | Err<E>;

type Ok<T> = { ok: true; data: T };
type Err<E> = { ok: false; error: E };
Copy

You can use the ok and err functions to create results:

const result: Ok<number> = ok(1);
Copy

const result: Err<string> = err("error");
Copy

You can use the isOk and isErr functions to check the type of a result:

const isOkOk: true = isOk(ok(1));
const isErrOk: false = isErr(ok(1));
const isErrErr: true = isErr(err("error"));
const isOkErr: false = isOk(err("error"));
Copy

If you need to get the value from the result, you can use the unwrap function:

const data = unwrap(ok(1));
assert.equal(data, 1);
Copy

If you need to get the error from the result, you can use the unwrapErr function:

const error = unwrapErr(err("error"));
assert.equal(error, "error");
Copy

You can use the unwrapForced function to force get the data from the result. It will return the data on OK results, and on Err results it will return undefined.

const data = unwrapForced(ok(1));
assert.equal(data, 1);

const otherData = unwrapForced(err("error"));
assert.equal(otherData, undefined); // !!
Copy

You can use the unwrapOr function to get the value of a result or a default value:

const data = unwrapOr(ok(1), 0);
assert.equal(data, 1);

const otherData = unwrapOr(err("error"), 0);
assert.equal(otherData, 0);
Copy

Tapping

You can use the tap function to run a function on a result if it's ok:

const result = ok(1);
const data = tap(result, (data) => {
  console.log(data);
});
assert.ok(data === result);
Copy

The tap function won't modify the result.

You can use the tapErr function to run a function on an error:

const result = err("error");
const error = tapErr(result, (error) => {
  console.log(error);
});
assert.ok(error === result);
Copy

The tapErr function won't modify the result.

Mapping

You can use the map function to map a result value:

const result = ok(1);
const data = map(result, (data) => data * 2);
assert.deepEqual(data, ok(2));
Copy

You can use the mapErr function to map an error:

const result = err("error");
const error = mapErr(result, (error) => error.toUpperCase());
assert.deepEqual(error, err("ERROR"));
Copy