Specification for interoperability of common algebraic structures in JavaScript
(aka "Algebraic JavaScript Specification")
This project specifies interoperability of common algebraic structures:
An algebra is a set of values, a set of operators that it is closed under and some laws it must obey.
Each Fantasy Land algebra is a separate specification. An algebra may have dependencies on other algebras which must be implemented.
In order for a data type to be compatible with Fantasy Land, its values must
have certain properties. These properties are all prefixed by fantasy-land/
.
For example:
// MyType#fantasy-land/map :: MyType a ~> (a -> b) -> MyType b MyTypeprototype'fantasy-land/map' = ...
Further in this document unprefixed names are used just to reduce noise.
For convenience you can use fantasy-land
package:
var fl = // ... MyTypeprototypeflmap = ... // ... var foo = barflmap x + 1
Certain behaviours are defined from the perspective of a member of a type.
Other behaviours do not require a member. Thus certain algebras require a
type to provide a value-level representative (with certain properties). The
Identity type, for example, could provide Id
as its type representative:
Id :: TypeRep Identity
.
If a type provides a type representative, each member of the type must have
a constructor
property which is a reference to the type representative.
a.equals(a) === true
(reflexivity)a.equals(b) === b.equals(a)
(symmetry)a.equals(b)
and b.equals(c)
, then a.equals(c)
(transitivity)equals
methodequals :: Setoid a => a ~> a -> Boolean
A value which has a Setoid must provide an equals
method. The
equals
method takes one argument:
a.equals(b)
b
must be a value of the same Setoid
b
is not the same Setoid, behaviour of equals
is
unspecified (returning false
is recommended).equals
must return a boolean (true
or false
).
a.concat(b).concat(c)
is equivalent to a.concat(b.concat(c))
(associativity)concat
methodconcat :: Semigroup a => a ~> a -> a
A value which has a Semigroup must provide a concat
method. The
concat
method takes one argument:
s.concat(b)
b
must be a value of the same Semigroup
b
is not the same semigroup, behaviour of concat
is
unspecified.concat
must return a value of the same Semigroup.
A value that implements the Monoid specification must also implement the Semigroup specification.
m.concat(M.empty())
is equivalent to m
(right identity)M.empty().concat(m)
is equivalent to m
(left identity)empty
methodempty :: Monoid m => () -> m
A value which has a Monoid must provide an empty
function on its
type representative:
M.empty()
Given a value m
, one can access its type representative via the
constructor
property:
m.constructor.empty()
empty
must return a value of the same Monoidu.map(a => a)
is equivalent to u
(identity)u.map(x => f(g(x)))
is equivalent to u.map(g).map(f)
(composition)map
methodmap :: Functor f => f a ~> (a -> b) -> f b
A value which has a Functor must provide a map
method. The map
method takes one argument:
u.map(f)
f
must be a function,
f
is not a function, the behaviour of map
is
unspecified.f
can return any value.f
's return value should be checked.map
must return a value of the same Functor
A value that implements the Apply specification must also implement the Functor specification.
v.ap(u.ap(a.map(f => g => x => f(g(x)))))
is equivalent to v.ap(u).ap(a)
(composition)ap
methodap :: Apply f => f a ~> f (a -> b) -> f b
A value which has an Apply must provide an ap
method. The ap
method takes one argument:
a.ap(b)
b
must be an Apply of a function,
b
does not represent a function, the behaviour of ap
is
unspecified.a
must be an Apply of any value
ap
must apply the function in Apply b
to the value in
Apply a
A value that implements the Applicative specification must also implement the Apply specification.
v.ap(A.of(x => x))
is equivalent to v
(identity)A.of(x).ap(A.of(f))
is equivalent to A.of(f(x))
(homomorphism)A.of(y).ap(u)
is equivalent to u.ap(A.of(f => f(y)))
(interchange)of
methodof :: Applicative f => a -> f a
A value which has an Applicative must provide an of
function on its
type representative. The of
function takes
one argument:
F.of(a)
Given a value f
, one can access its type representative via the
constructor
property:
f.constructor.of(a)
of
must provide a value of the same Applicative
a
should be checkedA value that implements the Alt specification must also implement the Functor specification.
a.alt(b).alt(c)
is equivalent to a.alt(b.alt(c))
(associativity)a.alt(b).map(f)
is equivalent to a.map(f).alt(b.map(f))
(distributivity)alt
methodalt :: 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)
b
must be a value of the same Alt
b
is not the same Alt, behaviour of alt
is
unspecified.a
and b
can contain any value of same type.a
's and b
's containing value should be checked.alt
must return a value of the same Alt.
A value that implements the Plus specification must also implement the Alt specification.
x.alt(A.zero())
is equivalent to x
(right identity)A.zero().alt(x)
is equivalent to x
(left identity)A.zero().map(f)
is equivalent to A.zero()
(annihilation)zero
methodzero :: Plus f => () -> f a
A value which has a Plus must provide an zero
function on its
type representative:
A.zero()
Given a value x
, one can access its type representative via the
constructor
property:
x.constructor.zero()
zero
must return a value of the same PlusA value that implements the Alternative specification must also implement the Applicative and Plus specifications.
x.ap(f.alt(g))
is equivalent to x.ap(f).alt(x.ap(g))
(distributivity)x.ap(A.zero())
is equivalent to A.zero()
(annihilation)u.reduce
is equivalent to u.reduce((acc, x) => acc.concat([x]), []).reduce
reduce
methodreduce :: Foldable f => f a ~> ((b, a) -> b, b) -> b
A value which has a Foldable must provide a reduce
method. The reduce
method takes two arguments:
u.reduce(f, x)
f
must be a binary function
f
is not a function, the behaviour of reduce
is unspecified.f
must be the same type as x
.f
must return a value of the same type as x
.f
's return value should be checked.x
is the initial accumulator value for the reduction
x
should be checked.A value that implements the Traversable specification must also implement the Functor and Foldable specifications.
t(u.traverse(x => x, F.of))
is equivalent to u.traverse(t, G.of)
for any t
such that t(a).map(f)
is equivalent to t(a.map(f))
(naturality)
u.traverse(F.of, F.of)
is equivalent to F.of(u)
for any Applicative F
(identity)
u.traverse(x => new Compose(x), Compose.of)
is equivalent to
new Compose(u.traverse(x => x, F.of).map(x => x.traverse(x => x, G.of)))
for Compose
defined below and any Applicatives F
and G
(composition)
var { thisc = c;}; Compose { return F;}; Composeprototype { return thisc;}; Composeprototype { return thisc;};
traverse
methodtraverse :: Apply f, Traversable t => t a ~> (a -> f b, c -> f c) -> f (t b)
A value which has a Traversable must provide a traverse
method. The traverse
method takes two arguments:
u.traverse(f, of)
f
must be a function which returns a value
f
is not a function, the behaviour of traverse
is
unspecified.f
must return a value of an Applicativeof
must be the of
method of the Applicative that f
returns
traverse
must return a value of the same Applicative that f
returns
A value that implements the Chain specification must also implement the Apply specification.
m.chain(f).chain(g)
is equivalent to m.chain(x => f(x).chain(g))
(associativity)chain
methodchain :: Chain m => m a ~> (a -> m b) -> m b
A value which has a Chain must provide a chain
method. The chain
method takes one argument:
m.chain(f)
f
must be a function which returns a value
f
is not a function, the behaviour of chain
is
unspecified.f
must return a value of the same Chainchain
must return a value of the same Chain
A value that implements the ChainRec specification must also implement the Chain specification.
M.chainRec((next, done, v) => p(v) ? d(v).map(done) : n(v).map(next), i)
is equivalent to
(function step(v) { return p(v) ? d(v) : n(v).chain(step); }(i))
(equivalence)M.chainRec(f, i)
must be at most a constant multiple of the stack usage of f
itself.chainRec
methodchainRec :: ChainRec m => ((a -> c, b -> c, a) -> m c, a) -> m b
A Type which has a ChainRec must provide a chainRec
function on its
type representative. The chainRec
function
takes two arguments:
M.chainRec(f, i)
Given a value m
, one can access its type representative via the
constructor
property:
m.constructor.chainRec(f, i)
f
must be a function which returns a value
f
is not a function, the behaviour of chainRec
is unspecified.f
takes three arguments next
, done
, value
next
is a function which takes one argument of same type as i
and can return any valuedone
is a function which takes one argument and returns the same type as the return value of next
value
is some value of the same type as i
f
must return a value of the same ChainRec which contains a value returned from either done
or next
chainRec
must return a value of the same ChainRec which contains a value of same type as argument of done
A value that implements the Monad specification must also implement the Applicative and Chain specifications.
M.of(a).chain(f)
is equivalent to f(a)
(left identity)m.chain(M.of)
is equivalent to m
(right identity)w.extend(g).extend(f)
is equivalent to w.extend(_w => f(_w.extend(g)))
extend
methodextend :: Extend w => w a ~> (w a -> b) -> w b
An Extend must provide an extend
method. The extend
method takes one argument:
w.extend(f)
f
must be a function which returns a value
f
is not a function, the behaviour of extend
is
unspecified.f
must return a value of type v
, for some variable v
contained in w
.f
's return value should be checked.extend
must return a value of the same Extend.
A value that implements the Comonad specification must also implement the Functor and Extend specifications.
w.extend(_w => _w.extract())
is equivalent to w
w.extend(f).extract()
is equivalent to f(w)
w.extend(f)
is equivalent to w.extend(x => x).map(f)
extract
methodextract :: Comonad w => w a ~> () -> a
A value which has a Comonad must provide an extract
method on itself.
The extract
method takes no arguments:
c.extract()
extract
must return a value of type v
, for some variable v
contained in w
.
v
must have the same type that f
returns in extend
.A value that implements the Bifunctor specification must also implement the Functor specification.
p.bimap(a => a, b => b)
is equivalent to p
(identity)p.bimap(a => f(g(a)), b => h(i(b))
is equivalent to p.bimap(g, i).bimap(f, h)
(composition)bimap
methodbimap :: Bifunctor f => f a c ~> (a -> b, c -> d) -> f b d
A value which has a Bifunctor must provide a bimap
method. The bimap
method takes two arguments:
c.bimap(f, g)
f
must be a function which returns a value
f
is not a function, the behaviour of bimap
is unspecified.f
can return any value.f
's return value should be checked.g
must be a function which returns a value
g
is not a function, the behaviour of bimap
is unspecified.g
can return any value.g
's return value should be checked.bimap
must return a value of the same Bifunctor.
A value that implements the Profunctor specification must also implement the Functor specification.
p.promap(a => a, b => b)
is equivalent to p
(identity)p.promap(a => f(g(a)), b => h(i(b)))
is equivalent to p.promap(f, i).promap(g, h)
(composition)promap
methodpromap :: Profunctor p => p b c ~> (a -> b, c -> d) -> p a d
A value which has a Profunctor must provide a promap
method.
The profunctor
method takes two arguments:
c.promap(f, g)
f
must be a function which returns a value
f
is not a function, the behaviour of promap
is unspecified.f
can return any value.f
's return value should be checked.g
must be a function which returns a value
g
is not a function, the behaviour of promap
is unspecified.g
can return any value.g
's return value should be checked.promap
must return a value of the same Profunctor
When creating data types which satisfy multiple algebras, authors may choose to implement certain methods then derive the remaining methods. Derivations:
map
may be derived from ap
and of
:
{ return this; }
map
may be derived from chain
and of
:
{ return this; }
map
may be derived from bimap
:
{ return this; }
map
may be derived from promap
:
{ return this; }
{ return m; }
reduce
may be derived as follows:
{ { thisvalue = value; } Const { return acc; }; Constprototype { return this; }; Constprototype { return ; }; return thisvalue;}
map
may be derived as follows:
{ { thisvalue = value; }; Id { return x; }; Idprototype { return ; }; Idprototype { return thisvaluebvalue; }; return thisvalue;}
If a data type provides a method which could be derived, its behaviour must be equivalent to that of the derivation (or derivations).
Id
container which implements many of the methods is provided in
internal/id.js
.There also exists Static Land Specification with the exactly same ideas as Fantasy Land but based on static methods instead of instance methods.