aljebra

About

Aljebra provides toy implementations of the algebraic structures defined in the Fantasy Land specification, mostly borrowed from Haskell libraries.

Algebraic Structures

The following objects each implement a constructor allowing you to lift values into these base objects. Many of the other instances in this library are built on top of these base objects. As such, they implement a similar constructor pattern.

Constructor	Description
new Id(a)	A value (Identity)
new Optional() or new Optional(a)	An optional value
new (new Default(a)) or new (new Default(a))()	An optional with a default value
new Either('left', a) or new Either('right', b)	One of two types of values

Note that new Default(a) actually returns a constructor for an Optional that defaults to a. In the following sections, such constructors-for-constructors will be listed under the heading “Constructors” and all other simple constructors will be listed under “Instances”.

Semigroup

Constructors

Constructor	Description
new Semigroup(concat)	Given associative binary function concat, return a Semigroup constructor.
new Dual(s)	Given Semigroup s, flip s.concat and return a constructor for the resulting Semigroup.

Instances

Constructor	concat
new Either('left', a) or new Either('right', b)	Takes the first value labelled 'right'.
new First(a)	Takes the first a.
new Last(a)	Takes the last a.
new Max(a)	>
new Min(a)	<

This module re-exports all Monoid instances.

Monoid

Constructors

Constructor	Description
new Monoid(zero, concat)	Given value zero and binary function concat, return a Monoid constructor.
new Dual(m)	Given Monoid m, flip m.concat and return a constructor for the resulting Monoid.
new OptionalSemigroup(s)	Lift Semigroup s into Optional and return a constructor for the resulting Monoid.

Instances

Constructor	zero	concat	Notes
new All(a)	true	&&
new Any(a)	false	││
new Array(a)	[]	concat
new Endo(a)	identity function	function composition	a must be a function from values of type b to b.
new Product(a)	1	*
new Sum(a)	0	+

Functor

Instances

Instance	map(f)
new Id(a)	Apply f to the value.
new Optional(a) or new Optional()	If the value exists, apply f to it.
new Either('left', a) or new Either('right', b)	If the value is labelled 'right', apply f to it.

This module re-exports all Applicative instances.

Applicative

Instances

This module re-exports all Monad instances.

Monad

Instances

Constructor	of	chain
new Id(a)	new Id(a)
new Optional(a)	new Optional(a)	A missing value short-circuits the chain.
new Either('left', a) or new Either('right', b)	new Either('right', a)	A 'left' vale short-circuits the chain.

Safety

• All of the algebraic operations defined above are pure.
• Each constructor freezes its resulting object.
• Source code includes 'use strict', so attempting to mutate any of the structures throws a type error.
• Most argument calls are annotated with helpers from ./lib/common.js. These throw errors, for example, when arguments are of the wrong type or wrong number are provided.

Testing

Note: the test suite itself could be better tested!

The test suite attempts to verify that the instances of algebraic structures defined in this library satisfy the laws defined in the Fantasy Land specification. Additionally, it includes a number of noninstance "sanity checks".

Before running, make sure you have installed the package with npm install, as the test suite relies on Mocha.

$ make about-testing
Testing
  make test               # Run all instance tests
  make test-instances     # Run all instance tests
  make test-noninstances  # Run all noninstance tests
  make test-all           # Run all tests
  make test-all-verbose   # Run all tests in verbose mode
  make testing            # Run all tests continuosly

Instance Tests

Example

  Id:
    ✓ Identity (Functor) 
    ✓ Composition (Functor) 
    ✓ Identity (Applicative) 
    ✓ Composition (Applicative) 
    ✓ Homomorphism (Applicative) 
    ✓ Interchange (Applicative) 
    ✓ Associativity (Chain) 
    ✓ Left Identity (Monad) 
    ✓ Right Identity (Monad) 

Noninstance Tests

Example

  Difference:
    ✓ is not a Semigroup 

  Rock, Paper, Scissors:
    ✓ is not a Semigroup