@sniptt/monads

Option, Result, and Either types for TypeScript

Inspired by Rust

Install

Node.js and the browser

npm install @sniptt/monads

⚠️ NOTE: The project is configured to target ES2020 and the library uses commonjs module resolution. Read more in the Node version support section.

Deno

import { Some } from "https://deno.land/x/monads/mod.ts"

const air = Some("air").unwrapOr("baloon")

console.log(air) // "air"

Usage

Option<T>

See full documentation

import { Option, Some, None } from "@hqoss/monads"

function divide(numerator: number, denominator: number): Option<number> {
  if (denominator === 0) {
    return None
  } else {
    return Some(numerator / denominator)
  }
};

// The return value of the function is an option
const result = divide(2.0, 3.0)

// Pattern match to retrieve the value
const message = result.match({
  some: res => `Result: ${res}`,
  none: "Cannot divide by 0",
})

console.log(message) // "Result: 0.6666666666666666"

Result<T, E>

See full documentation

import { Result, Ok, Err } from "@hqoss/monads"

function getIndex(values: string[], value: string): Result<number, string> {
  const index = values.indexOf(value)

  switch (index) {
    case -1:
      return Err("Value not found")
  default:
    return Ok(index)
  }
}

console.log(getIndex(["a", "b", "c"], "b")) // Ok(1)
console.log(getIndex(["a", "b", "c"], "z")) // Err("Value not found")

Either<L, R>

See full documentation

import { Either } from "@hqoss/monads"

function getLabel(uncertainDate: Either<Date, string>) {
  return uncertainDate.match({
    left: date => date.toLocaleDateString(),
    right: text => `<abbr title="${text}">an uncertain date</abbr>`,
  })
}

API Docs

See full API Documentation here.

Node version support

The project is configured to target ES2020. In practice, this means consumers should run on Node 14 or higher, unless additional compilation/transpilation steps are in place to ensure compatibility with the target runtime.

Please see https://node.green/#ES2020 for reference.

TODO

A quick and dirty tech debt tracker before we move to Issues.

• [ ] Write a Contributing guide
• [ ] Complete testing section, add best practices
• [ ] Describe scripts and usage, add best practices
• [ ] Describe security best practices, e.g. npm doctor, npm audit, npm outdated, ignore-scripts in .npmrc, etc.
• [ ] Add "Why should I use this" section