Add Alt, Plus and Alternative specs

README.md

@@ -15,11 +15,17 @@ structures:
 * [Functor](#functor)
 * [Apply](#apply)
 * [Applicative](#applicative)
+* [Alt](#alt)
+* [Plus](#plus)
+* [Alternative](#alternative)
 * [Foldable](#foldable)
 * [Traversable](#traversable)
 * [Chain](#chain)
 * [ChainRec](#chainrec)
 * [Monad](#monad)
+* [MonadZero](#monadzero)
+* [MonadPlus](#monadplus)
+* [MonadOr](#monador)
 * [Extend](#extend)
 * [Comonad](#comonad)
 * [Bifunctor](#bifunctor)
@@ -243,6 +249,69 @@ Given a value `f`, one can access its type representative via the
 
     1. No parts of `a` should be checked
 
+### Alt
+
+A value that implements the Alt specification must also implement
+the [Functor](#functor) specification.
+
+1. `a.alt(b).alt(c)` is equivalent to `a.alt(b.alt(c))` (associativity)
+2. `a.alt(b).map(f)` is equivalent to `a.map(f).alt(b.map(f))` (distributivity)
+
+#### `alt` method
+
+```hs
+alt :: Alt f => f a ~> f a -> f a
+```
+
+A value which has a Alt must provide a `alt` method. The
+`alt` method takes one argument:
+
+    a.alt(b)
+
+1. `b` must be a value of the same Alt
+
+    1. If `b` is not the same Alt, behaviour of `alt` is
+       unspecified.
+    2. `a` and `b` can contain any value of same type.
+    3. No parts of `a`'s and `b`'s containing value should be checked.
+
+2. `alt` must return a value of the same Alt.
+
+### Plus
+
+A value that implements the Plus specification must also implement
+the [Alt](#alt) specification.
+
+1. `x.alt(A.zero())` is equivalent to `x` (right identity)
+2. `A.zero().alt(x)` is equivalent to `x` (left identity)
+2. `A.zero().map(f)` is equivalent to `A.zero()` (annihilation)
+
+#### `zero` method
+
+```hs
+zero :: Plus x => () -> x
+```
+
+A value which has a Plus must provide an `zero` function on its
+[type representative](#type-representatives):
+
+    M.zero()
+
+Given a value `x`, one can access its type representative via the
+`constructor` property:
+
+    x.constructor.zero()
+
+1. `zero` must return a value of the same Plus
+
+### Alternative
+
+A value that implements the Alternative specification must also implement
+the [Applicative](#applicative) and [Plus](#plus) specifications.
+
+1. `x.ap(f.alt(g))` is equivalent to `x.ap(f).alt(x.ap(g))` (distributivity)
+1. `x.ap(M.zero())` is equivalent to `M.zero()` (annihilation)
+
 ### Foldable
 
 1. `u.reduce` is equivalent to `u.reduce((acc, x) => acc.concat([x]), []).reduce`
@@ -389,6 +458,27 @@ the [Applicative](#applicative) and [Chain](#chain) specifications.
 1. `M.of(a).chain(f)` is equivalent to `f(a)` (left identity)
 2. `m.chain(M.of)` is equivalent to `m` (right identity)
 
+### MonadZero
+
+A value that implements the MonadZero specification must also implement
+the [Monad](#monad) and [Alternative](#alternative) specifications.
+
+1. `M.zero().chain(f)` is equivalent to `M.zero()` (annihilation)
+
+### MonadPlus
+
+A value that implements the MonadPlus specification must also implement
+the [MonadZero](#monadzero) specification.
+
+1. `x.alt(y).chain(f)` is equivalent to `x.chain(f).alt(y.chain(f))` (distributivity)
+
+### MonadOr
+
+A value that implements the MonadOr specification must also implement
+the [MonadZero](#monadzero) specification.
+
+1. `M.of(a).alt(b)` is equivalent to `M.of(a)` (left catch)
+
 ### Extend
 
 1. `w.extend(g).extend(f)` is equivalent to `w.extend(_w => f(_w.extend(g)))`

bower.json

@@ -29,7 +29,7 @@
     "/node_modules/",
     "/.*",
     "/id.js",
-    "/id_test.js",
+    "/test.js",
     "/implementations.md",
     "/logo.png",
     "/package.json"

figures/dependencies.dot

@@ -2,6 +2,8 @@ digraph {
   node [shape=plaintext]
 
   # Algebras
+  Alt;
+  Alternative;
   Applicative;
   Apply;
   Bifunctor;
@@ -12,24 +14,36 @@ digraph {
   Foldable;
   Functor;
   Monad;
+  MonadOr;
+  MonadPlus;
+  MonadZero;
   Monoid;
+  Plus;
   Profunctor;
   Semigroup;
   Setoid;
   Traversable;
 
   # Dependencies
+  Alt -> Plus;
+  Applicative -> Alternative;
   Applicative -> Monad;
+  Alternative -> MonadZero;
   Apply -> Applicative;
   Apply -> Chain;
   Chain -> ChainRec;
   Chain -> Monad;
   Extend -> Comonad;
   Foldable -> Traversable;
+  Functor -> Alt;
   Functor -> Apply;
   Functor -> Bifunctor;
   Functor -> Extend;
   Functor -> Profunctor;
   Functor -> Traversable;
+  Monad -> MonadZero;
+  MonadZero -> MonadOr;
+  MonadZero -> MonadPlus;
+  Plus -> Alternative;
   Semigroup -> Monoid;
 }

index.js

@@ -12,6 +12,8 @@
     map: 'fantasy-land/map',
     ap: 'fantasy-land/ap',
     of: 'fantasy-land/of',
+    alt: 'fantasy-land/alt',
+    zero: 'fantasy-land/zero',
     reduce: 'fantasy-land/reduce',
     traverse: 'fantasy-land/traverse',
     chain: 'fantasy-land/chain',

internal/compose.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const {tagged} = require('daggy');
+
+const fl = require('..');
+const {equality} = require('./func');
+
+const Compose = module.exports = tagged('c');
+Compose[fl.of] = Compose;
+Compose.prototype[fl.ap] = function(f) {
+  return Compose(this.c[fl.ap](f.c[fl.map](u => y => y[fl.ap](u))));
+};
+Compose.prototype[fl.map] = function(f) {
+  return Compose(this.c[fl.map](y => y[fl.map](f)));
+};
+Compose.prototype[fl.equals] = function(x) {
+  return equality(this.c, x.c);
+};

internal/func.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const fl = require('../');
+const equality = (x, y) => typeof x[fl.equals] === 'function' ? x[fl.equals](y) : x === y;
+
+module.exports = {
+  equality,
+};

id.js → internal/id.js

@@ -1,14 +1,15 @@
 'use strict';
 
-const fl = require('./');
+const fl = require('../');
+const {equality} = require('./func');
 
-const Id = function Id(a) {
-  this.value = a;
-};
+const {tagged} = require('daggy');
+
+const Id = module.exports = tagged('value');
 
 // Setoid
 Id.prototype[fl.equals] = function(b) {
-  return typeof this.value[fl.equals] === 'function' ? this.value[fl.equals](b.value) : this.value === b.value;
+  return equality(this.value, b.value);
 };
 
 // Semigroup (value must also be a Semigroup)
@@ -73,5 +74,3 @@ Id[fl.of] = function(a) {
 Id.prototype[fl.extract] = function() {
   return this.value;
 };
-
-module.exports = Id;

internal/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const patch = require('./patch');
+const Maybe = require('./maybe');
+const Id = require('./id');
+const Sum = require('./string_sum');
+const Compose = require('./compose');
+const {equality} = require('./func');
+
+module.exports = {
+  Maybe,
+  Id,
+  Sum,
+  Compose,
+  equality,
+  patch,
+};