Awesome

Space-monad

Option and Result monads for TypeScript.

Option

Option()
Option.all()
Option.isOption
None
map
flatMap
filter
fold
orElse
isDefined
get
getOrElse
forEach
contains
exists
toArray

Creating an Option

Option(x)

Creates an Option from a value. If the value is null or undefined, it will create a None, else a Some.

const some = Option(33) // some === Some(33)
const none = Option(null) // none === None

If you already know the value is defined for sure (not nullable) or not, you can create a Some or None directly:

const some = Some(33) // Some(null | undefined) wouldn't compile.
const none = None

Option.all([...optionsOrValues])

Creates a new Option holding the tuple of all the values contained in the passed array if they were all Some or non null/undefined values, else returns None

const some = Option.all([
  Option(10),
  20,
  Option(5)
])
// some === Some([10, 20, 5])

const none = Option.all([
  Option(10),
  None,
  Option(5),
  null
])
// none === None

Option.isOption

Returns whether the passed instance in an Option, and refines its type

import { Option, Some } from 'space-monad'
Option.isOption(Some(33)) // true

None

The Option constant representing no value.

import { None } from 'space-monad'

Transforming an Option

map

Maps the value contained in this Some, else returns None. Depending on the map function return value, a Some could be tranformed into a None, as a Some is guaranteed to never contain a null or undefined value.

const some = Option(33).map(x => x * 2)
// some === Some(66)

flatMap

Maps the value contained in this Some to a new Option, else returns None.

const some = Option(33).flatMap(_ => Option(44))
// some === Some(44)

filter

If this Option is a Some and the predicate returns true, keep that Some. In all other cases, return None.

const some = Option(33).filter(x => x > 32)
// some === Some(33)

fold

Applies the first function if this is a None, else applies the second function. Note: Since this method creates 2 functions everytime it runs, don't use in tight loops; use isDefined() instead.

const count = Option(10).fold(
  () => 100, // None
  count => count * 10 // Some
)

toArray

Transforms this option into an Array or either 1 or 0 element.

orElse

Returns this Option unless it's a None, in which case the provided alternative is returned.

const some = Option(null).orElse(() => Option(33))
// some === Some(33)

Misc

get

Some instances return their value, whereas None always return undefined. This method never throws.

const value = Some(33).get()
// value === 33

isDefined

Returns whether this Option has a defined value (i.e, it's a Some(value)) Note: this refines the type of the Option to be a Some so it's guaranteed its value is not null/undefined.

getOrElse

Returns this Option's value if it's a Some, else return the provided alternative

const value = Option(undefined).getOrElse(33)

// value === 33

forEach

Applies the given procedure to the option's value, if it is non empty.

Option(33).forEach(x => console.log(x))

contains

Returns whether this option is a Some that contain a specific value, using ===

Option(30).contains(30) // true

exists

Returns whether this option is a Some with a value satisfying the predicate.

Option(30).exists(n => n > 10) // true

A Result is the result of a computation that may fail. An Ok represents a successful computation, while an Err represent the error case.

Importing Result

Here's everything that can be imported to use Results:

import { Result, Ok, Err } from 'space-monad'

const ok = Ok(10)
const err = Err('oops')

Result.isResult

Returns whether this instance is a Result (either an Ok or a Err) and refines its type

import { Result, Ok } from 'space-monad'

Result.isResult(Ok(10)) // true

Result.all

Creates a new Ok Result holding the tuple of all the values contained in the passed array if they were all Ok, else returns the first encountered Err.

import { Result, Ok, Err } from 'space-monad'

const result = Result.all([
  Ok(20),
  Err('nooo'),
  Ok(200),
  Err('oops')
]) // Err('nooo')

isOk

Returns whether this is an instance of Ok

import { Result, Ok, Err } from 'space-monad'

Ok(10).isOk() // true

map

Maps the value contained in this Result if it's an Ok, else propagates the Error.

import { Result, Ok, Err } from 'space-monad'

Ok(10).map(x => x * 2) // Ok(20)
Err(10).map(x => x * 2) // Err(10)

mapError

Maps the Error contained in this Result if it's an Err, else propagates the Ok.

import { Result, Ok, Err } from 'space-monad'

Ok(10).mapError(x => x * 2) // Ok(10)
Err(10).mapError(x => x * 2) // Err(20)

flatMap

Maps the value contained in this Result with another Result if it's an Ok, else propagates the Error. Note: It is allowed to return a Result with a different Error type.

import { Result, Ok, Err } from 'space-monad'

Ok(10).flatMap(x => Ok(x * 2)) // Ok(20)
Ok(10).flatMap(x => Err(x * 2)) // Err(20)

fold

Applies the first function if this is an Err, else applies the second function. Note: Don't use in tight loops; use isOk() instead.

import { Result, Ok, Err } from 'space-monad'

Ok(10).fold(
  err => console.error(err),
  num => num * 2
) // 20