README
Perfective Maybe
@perfective/maybe
package provides an Option type implementation.
It is inspired by the Haskell
Maybe
monad,
and is following the monad laws
as close as possible given the limitations of JavaScript and TypeScript
(exceptions and solutions are described in the
usage documentation).
Types and unit functions
Maybe<T>
isJust<T>
orNothing<T>
(corresponds toT | null | undefined
):maybe<T>(value: T | null | undefined): Maybe<T>
just<T>(value: T): Just<T>
nothing<T>(): Nothing<T>
— returnsNothing
withundefined
value.naught<T>(): Nothing<T>
— returnsNothing
withnull
value.
Nullable<T>
isSolum<T>
orNil<T>
(corresponds toT | null
):nullable<T>(value: T | null): Nullable<T>
solum<T>(value: T): Solum<T>
nil<T>(): Nil<T>
Optional<T>
isSome<T>
orNone<T>
(corresponds toT | undefined
):optional<T>(value: T | undefined): Optional<T>
some<T>(value: T): Some<T>
none<T>(): None<T>
Methods
Both Nullable
and Optional
have the same methods as Maybe
,
but for their corresponding types Solum
/Nil
and Some
/None
.
These references are omitted for brevity.
Maybe.onto<U>(flatMap: (value: T) => Maybe<Present<U>>): Maybe<Present<U>>
— when a value is present, apply the provided function and return its result; otherwise return an emptyMaybe
.Just.onto<U>(flatMap: (value: T) => Just<Present<U>>): Just<Present<U>>
Just.onto<U>(flatMap: (value: T) => Just<Present<U>>): Just<Present<U>>
Just.onto<U>(flatMap: (value: T) => Maybe<Present<U>>): Maybe<Present<U>>
Nothing.onto<U>(flatMap: (value: T) => Maybe<Present<U>>): Nothing<Present<U>>
Maybe.to<U>(map: (value: T) => U | null | undefined): Maybe<U>
— when a value is present, apply the provided function and return its result wrapped intoMaybe
; otherwise returnNothing
.Just.to<U>(map: (value: T) => Present<U>): Just<U>
Just.to<U>(map: (value: T) => null | undefined): Nothing<U>
Just.to<U>(map: (value: T) => U | null | undefined): Maybe<U>
Nothing.to<U>(map: (value: T) => (U | null | undefined)): Nothing<U>
Maybe.pick<K extends keyof T>(property: Value<K>): Maybe<Present<T[K]>>
— when a value is present, return the value of the given property wrapped inMaybe
; otherwise return an emptyMaybe
.Just.pick<K extends keyof T>(property: Value<K>): T[K] extends Present<T[K]> ? Just<T[K]> : Maybe<Present<T[K]>>
— when the property is required, returnJust
property value.Nothing.pick<K extends keyof T>(property: Value<K>): Nothing<Present<T[K]>>
Maybe.that(filter: Predicate<T>): Maybe<T>
— when a value is present, and the value matches the given predicate, return the currentMaybe
; otherwise return an emptyMaybe
.Nothing.that(filter: Predicate<T>): Nothing<T>
Maybe.which<U extends T>(filter: TypeGuard<T, U>): Maybe<U>
— when a value is present, and the value matches the given type guard, return the current value as aMaybe
of the type guarded type; otherwise return an emptyMaybe
.Nothing.which<U extends T>(filter: TypeGuard<T, U>): Nothing<U>
Maybe.when(condition: Proposition): Maybe<T>
— when a value is present, and the given proposition istrue
, return the currentMaybe
; otherwise return an emptyMaybe
.Nothing.when(condition: Proposition): Nothing<T>
Maybe.otherwise(fallback: Value<T | null | undefined>): Maybe<T>
— when a value is present, return the value; otherwise if the given fallback is a function, return the result of the fallback function wrapped inMaybe
; otherwise return the fallback wrapped inMaybe
.Maybe.otherwise(fallback: Value<T>): Just<T>
— when the given fallback returns a present value, return aJust
.Just.otherwise(fallback: Value<T | null | undefined>): Just<T>
Nothing.otherwise(fallback: Value<T>): Just<T>
Nothing.otherwise(fallback: Value<null | undefined>): Nothing<T>
Nothing.otherwise(fallback: Value<T | null | undefined>): Maybe<T>
Maybe.or(fallback: Value<T | null | undefined>): T | null | undefined
— when a value is present, return the value; otherwise, if the given fallback is a function, return the result of the fallback function; otherwise, return the fallback value.Maybe.or(fallback: Value<T>): T
Maybe.or(fallback: Value<T | null>): T | null
Maybe.or(fallback: Value<T | undefined>): T | undefined
Just.or(fallback: Value<T | null | undefined>): T
Nothing.or(fallback: Value<T>): T
Nothing.or(fallback: Value<null>): null
Nothing.or(fallback: Value<undefined>): undefined
Nothing.or(fallback: Value<T | null>): T | null
Nothing.or(fallback: Value<T | undefined>): T | undefined
Nothing.or(fallback: Value<T | null | undefined>): T | null | undefined
Maybe.run(procedure: (value: T) => void): Maybe<T>
— when a value is present, run the procedure with the value. Always return the originalMaybe
.Just.run(procedure: (value: T) => void): Just<T>
— if the value is known be inJust
, return the originalJust
.Nothing.run(procedure: (value: T) => void): Nothing<T>
Maybe.lift<U>(map: (value: T | null | undefined) => U | null | undefined): Maybe<U>
— apply the given mapping function regardless if value is present or absent, return the result wrapped in a newMaybe
.Just.lift<U>(map: (value: T) => U | null | undefined): Maybe<U>
— allows to pass a function that accepts only a present argument.Nothing.lift<U>(map: (value: null | undefined) => U | null | undefined): Maybe<U>
Mapping functions
Each method has a corresponding mapping function that can be used in the Array.prototype.map
(or any other mapping method or operator).
onto<T, U>(flatMap: (value: T) => Maybe<Present<U>>): Unary<Maybe<T>, Maybe<Present<U>>>
to<T, U>(map: (value: T) => U | null | undefined): Unary<Maybe<T>, Maybe<U>>
pick<T, K extends keyof T>(property: Value<K>): Unary<Maybe<T>, Maybe<Present<T[K]>>>
that<T>(filter: Predicate<T>): Unary<Maybe<T>, Maybe<T>>
which<T, U extends T>(filter: TypeGuard<T, U>): Unary<Maybe<T>, Maybe<U>>
when<T>(condition: Proposition): Unary<Maybe<T>, Maybe<T>>
otherwise<T>(fallback: Value<T | null | undefined>): Unary<Maybe<T>, Maybe<T>>
otherwise<T>(fallback: Value<T>): Unary<Maybe<T>, Just<T>>
or<T>(fallback: Value<T | null | undefined>): Unary<Maybe<T>, T | null | undefined>
or<T>(fallback: Value<T>): Unary<Maybe<T>, T>
run<T>(procedure: (value: T) => void): Unary<Maybe<T>, Maybe<T>>
lift<T, U>(map: (value: T | null | undefined) => U | null | undefined): Unary<Maybe<T>, Maybe<U>>
Read the usage documentation in the repository.