iron-oxide

iron-oxide offers some Rust style exception handling and rudimentary pattern matching.

The Problem

Exception handling in JavaScript and TypeScript can be notoriously cumbersome and confusing. For example, Array.prototype.find returns undefined and Array.prototype.indexOf returns -1; the return types for these exceptions don't match and thus can be confusing, especially for newer developers. JS also allows you to throw errors and catch them using try/catch blocks. The problem compounds itself even more when we start using promises and asynchronous code.

The Solution

In Rust, we have two types in the standard library Option and Result for handling exceptions. Option is used to catch failure in a part of the application where it doesn't make sense to panic, or throw in the case of JavaScript. Result is similar to Option except that it can contain the reason for the failure, allowing us to say why a function failed.

Option comes in two flavors:

Some representing success or a value
None representing failure or lack of a value

Result also comes in two flavors:

Ok representing success or a value
Err representing failure, or lack of a value, with a reason

Pattern Matching

Rust provides pattern matching through the use of the match keyword. iron-oxide attempts to replicate this by including a match function.

Installation

This project is distributed via npm which is bundled with node and should be installed as one of your project's dependencies.

$ npm install iron-oxide

ℹ️ iron-oxide is written in TypeScript and comes bundled with type declarations

Using Option

Option is used to catch errors in a uniform way, where we don't necessarily care about the failure reason. They are generic over T.

There are two variants of Option<T>:

None, to indicate failure or lack of a value
Some(value), a wrapper around of value of type T


import { Option, Some, None } from 'iron-oxide';

// Array.prototype.find returns undefined if it doesn't find a value
// let's fix that
function find<T>(
    arr: T[],
    predicate: (value: T) => boolean
): Option<T> {
    const value = arr.find(v => predicate(v));

    // if the value is undefined, we return `None`, our failure state
    if (value === undefined) {
        return None();
    }

    // otherwise, we wrap the value in `Some`
    return Some(value);
}

Methods

Option comes with some built-in methods for interacting with the wrapped value and handling what happens when the Option is None.

Interacting with the value

From our introductory example, we now have a find function with the signature

function find<T>(arr: T[], predicate: (value: T) => boolean): Option<T>;

Commonly, we use the map method to transform the value.

// we have an array of people, and want to find Tom and increment
// his age
const people = [
    {
        name: "Bob",
        age: 25
    },
    {
        name: "Sally",
        age: 26
    },
    {
        name: "Tom",
        age: 28
    }
]; 

const newTom = find(people, ({ name }) => name === "Tom")
    .map(tom => ({
        ...tom,
        age: tom.age + 1
    });

Here, we find Tom and increment his age inside of map. But what happens if we look for someone else that doesn't exist?

const newLucy = find(people, ({ name }) => name === "Lucy")
    .map(lucy => ({
        ...lucy,
        age: lucy.age + 1
    });

Nothing will actually happen. We would expect that normally this would throw a nasty exception, something on the lines of lucy is not defined. In our case, find returns None , which won't cause the rest of our code to fail. But how do we figure out if the operation failed?

Checking for failure

Option comes with a few ways to check if the value is None, such as the isNone method

if (newLucy.isNone()) {
    console.log("Oops, we couldn't find lucy!");
}

Sometimes, we would rather the application throw if we find a None. We do this with the unwrap method

try {
    newLucy.unwrap();
catch (err) {
    // Throws "Called 'Option.unwrap' on a 'None' value"
    console.err(err);
}

isSome

Option.isSome returns whether or not the Option is a Some.

Option<T>.isSome = () => boolean;