fix(maybe): complete instance of applicative (#116)

In order to complete the instance of Applicative, a method "apply" must
be added to the type. Technically, a Monad does not require an instance
of Applicative, but most modern functional languages and libraries
enforce this constraint due to the benefits derived when implementing
instances of other Categories. Particularly in the case of Maybe, this
instance is desirable due to the behavior of Maybes which wrap a
function. Because applying an undefined function to a value results in
an error, rather than undefined or null, mapping a function wrapped by
Maybe demands that the function be unwrapped and coerced to some
default before it can be used, or checking to see if it is defined. The
"apply" method allows a value wrapped by Maybe to be applied to a
function wrapped by Maybe.

Author: williamareynolds

src/interfaces/maybe.interface.ts

@@ -98,4 +98,9 @@ export interface IMaybe<T> extends IMonad<T> {
    * otherwise return an empty Maybe
    */
   filter(fn: (t: T) => boolean): IMaybe<T>
-}
+
+  /**
+   * Apply a function wrapped in Maybe
+   */
+  apply<R>(fab: IMaybe<(t: T) => R>): IMaybe<R>
+}

src/monads/maybe.ts

@@ -14,6 +14,7 @@ const tapSome = <T>(value?: T) => (fn: (val: NonNullable<T>) => void) => isNotEm
 const match = <T>(value?: T) => <R>(pattern: IMaybePattern<T, R>) => isEmpty(value) ? pattern.none() : pattern.some(value as NonNullable<T>)
 const map = <T>(value?: T) => <R>(fn: (t: NonNullable<T>) => R) => isEmpty(value) ? maybe<R>() : maybe<R>(fn(value as NonNullable<T>))
 const flatMap = <T>(value?: T) => <R>(fn: (d: NonNullable<T>) => IMaybe<R>) => isEmpty(value) ? maybe<R>() : fn(value as NonNullable<T>)
+const apply = <T>(value?: T) => <R>(maybeFn: IMaybe<(t: T) => R>) => maybeFn.flatMap(f => map(value)(f))
 const flatMapAuto = <T>(value?: T) => <R>(fn: (d: NonNullable<T>) => R) => isEmpty(value) ? maybe<R>() : maybe<R>(fn(value as NonNullable<T>))
 const valueOrThrow = <T>(value?: T) => (msg?: string) => isEmpty(value) ? (() => { throw Error(msg) })() : value as NonNullable<T>
 
@@ -42,7 +43,8 @@ export const maybe = <T>(value?: T): IMaybe<NonNullable<T>> => {
     map: map(value),
     flatMap: flatMap(value),
     flatMapAuto: flatMapAuto(value),
-    filter: filter(value)
+    filter: filter(value),
+    apply: apply(value)
   }
 }
 

test/monads/maybe.spec.ts

@@ -495,4 +495,23 @@ describe('Maybe', () => {
         .catch(error => expect(error).toEqual('err'))
     })
   })
+
+  describe('apply', () => {
+    it('should return none in nullish cases', () => {
+      const thisNone = maybe<number>()
+      const fnNone = maybe<(n: number) => number>()
+      const thisSome = maybe(5)
+      const fnSome = maybe((a: number) => a * 2)
+
+      expect(thisNone.apply(fnNone).isNone()).toBe(true)
+      expect(thisNone.apply(fnSome).isNone()).toBe(true)
+      expect(thisSome.apply(fnNone).isNone()).toBe(true)
+    })
+
+    it('should apply the function in a maybe in someish cases', () => {
+      const a = maybe(5)
+      const f = maybe((a: number) => a * 2)
+      expect(a.apply(f).valueOrThrow()).toBe(10)
+    })
+  })
 })