Merge pull request #244 from monet/release/v0.9.2_m

.travis.yml

@@ -1,6 +1,6 @@
 language: node_js
 node_js:
-  - "8"
+  - "14"
 
 branches:
   only:

docs/EITHER.md

@@ -103,6 +103,12 @@ Either[E,A].ap(v: Either[E,A=>B]): Either[E,B]
 
 This takes an either that has a function on the right side of the either and then applies it to the right side of itself. This implements the applicative functor pattern.
 
+### apTo
+```scala
+Either[E,A=>B].apTo(v: Either[E,A]): Either[E,B]
+```
+This method is specific for Either with function in the right side. Takes another Either with value and applies function inside itself to value inside argument.
+
 ### cata
 **Alias:** `fold`
 

docs/FREE.md

@@ -70,3 +70,5 @@ Runs the computation to the end, returning the final result, using the supplied
 - join
 - takeLeft
 - takeRight
+- ap
+- apTo

docs/IO.md

@@ -75,6 +75,7 @@ Evaluates the effect inside the `IO` monad. This can only be run once in your pr
 - takeLeft
 - takeRight
 - ap
+- apTo
 
 ## Examples
 Say we have a function to read from the DOM and a function to write to the DOM. *This example uses jQuery.*

docs/LIST.md

@@ -97,6 +97,44 @@ List.fromArray([1,2,3]).head()
 // => 1
 ```
 
+### lookup
+
+```scala
+List[A].lookup(i: Integer): Maybe[A]
+```
+
+Safely read a value at a particular index. For example:
+
+```javascript
+List.fromArray([1, 2, 3]).lookup(0)
+// => Just(1)
+
+List.fromArray([1, 2, 3]).lookup(3)
+// => None()
+
+List.fromArray([1, 2, 3, undefined]).lookup(3)
+// => None()
+```
+
+### nth
+
+```scala
+List[A].nth(i: Integer): A | undefined
+```
+
+Unsafe version of `lookup`. For example:
+
+```javascript
+List.fromArray([1, 2, 3]).nth(0)
+// => 1
+
+List.fromArray([1, 2, 3]).nth(3)
+// => undefined
+
+List.fromArray([1, 2, 3, undefined]).lookup(3)
+// => undefined
+```
+
 ### headMaybe
 
 ```scala
@@ -369,6 +407,7 @@ List[A].to(Iterable[A] => B): B
 - takeLeft
 - takeRight
 - ap
+- apTo
 - snoc
 - isNEL
 - size

docs/MAYBE.md

@@ -312,6 +312,45 @@ const personString = Some('Dulwich, London')
 
 For further reading see [this excellent article](http://learnyouahaskell.com/functors-applicative-functors-and-monoids).
 
+### apTo
+
+Common usage of Applicative Functors is applying curried n-argument function to some values:
+```haskell
+pure (+) <*> Just 3 <*> Just 5
+> 8
+```
+But(what a pity), JS has no infix operations and we cannot use `.ap`(`<*>`) in haskell style.
+`.apTo` is just alias for `.ap` with swapped arguments, for more convenient usage:
+```ecmascript 6
+const f3 = x => y => z => x + y + z
+const applicative = Maybe.of(f3)
+
+applicative
+    .apTo(Maybe.of(1)) // Maybe with partially applied f3 with 1 instead of x 
+    .apTo(Maybe.of(2)) // Maybe with 1 instead of x and 2 instead of y
+    .apTo(Maybe.of(3)) // Maybe with f3 result (6)
+
+/* Code below is equivalent of code upper. But ap cannot be chained. */
+Maybe.of(3).ap(Maybe.of(2).ap(Maybe.of(1).ap(applicative)))
+```
+When applicative itself of some argument is `Nothing` - `Nothing` returned.
+```ecmascript 6
+applicative
+    .apTo(Maybe.of(1))
+    .apTo(Maybe.of(2))
+    .apTo(Maybe.of(3)) // Just 6
+
+Maybe.Nothing()
+    .apTo(Maybe.of(1))
+    .apTo(Maybe.of(2))
+    .apTo(Maybe.of(3)) // Nothing
+
+applicative
+    .apTo(Maybe.of(1))
+    .apTo(Maybe.of(2))
+    .apTo(Maybe.Nothing()) // Nothing
+```  
+
 ### every
 
 **Alias:** `forall`

docs/NEL.md

@@ -91,6 +91,44 @@ NEL[A].head(): A
 
 Returns the head of the NonEmptyList. Also known as `copure` or `extract` this is part of the comonad pattern.
 
+### lookup
+
+```scala
+NEL[A].lookup(i: Integer): Maybe[A]
+```
+
+Safely read a value at a particular index. For example:
+
+```javascript
+NEL(1, List.fromArray([2, 3])).lookup(0)
+// => Just(1)
+
+NEL(1, List.fromArray([2, 3]))).lookup(3)
+// => None()
+
+NEL(1, List.fromArray([2, 3, undefined])).lookup(3)
+// => None()
+```
+
+### nth
+
+```scala
+List[A].nth(i: Integer): A | undefined
+```
+
+Unsafe version of `lookup`. For example:
+
+```javascript
+NEL(1, List.fromArray([2, 3])).nth(0)
+// => 1
+
+NEL(1, List.fromArray([2, 3]))).nth(3)
+// => undefined
+
+NEL(1, List.fromArray([2, 3, undefined])).nth(3)
+// => undefined
+```
+
 ### tail
 
 ```scala
@@ -274,6 +312,7 @@ List[A].to(Iterable[A] => B): B
 - takeLeft
 - takeRight
 - ap
+- apTo
 - isNEL
 - size
 - join

docs/READER.md

@@ -86,6 +86,11 @@ Reader[E, A].ap(a: Reader[E, A=>B]): Reader[E, B]
 
 Applies the function inside the supplied `Reader` to the value `A` in the outer `Reader`. Applicative Functor pattern.
 
+### apTo
+```scala
+Reader[E, A=>B].apTo(a: Reader[E, A]): Reader[E, B]
+```
+Just an alias for ap with swapped this & argument. 
 ### run
 
 ```scala

docs/VALIDATION.md

@@ -147,6 +147,28 @@ Fail(['no address'])
 // => Fail(["no address", "no surname"])
 ```
 
+### apTo
+`.ap` alias with swapped this and argument. See rewriten `ap` example with usage of `apTo`
+
+```javascript
+const person = forename => surname => address =>
+  `${forename} ${surname} lives at ${address}`;
+
+const validateAddress = Success('Dulwich, London')
+const validateSurname = Success('Baker')
+const validateForename = Success('Tom')
+
+Success(person)
+    .apTo(validateForename)
+    .apTo(validateSurname)
+    .apTo(validateAddress) // => Success("Tom Baker lives at Dulwich, London")
+
+Success(person)
+    .apTo(validateForename)
+    .apTo(Fail(['no surname']))
+    .apTo(Fail(['no address'])) // => Fail(["no address", "no surname"])
+```
+
 ### cata
 **Alias:** `fold`