# laws

Verifications for Monad laws according to fantasy-land.

# Laws

Claire properties for verifying Monad and other algebraic structures' laws, conforming to the Fantasy Land specification.

The easiest way is to grab it from NPM. If you're running in a Browser environment, you can use Browserify

``````\$ npm install laws
``````

If you're not using NPM, Download the latest release, and require the `folktale.laws.umd.js` file:

Download the latest release, and require the `folktale.laws.umd.js` file:

Download the latest release, and load the `folktale.laws.umd.js` file. The properties are exposed in the global `Laws` object:

If you want to compile this library from the source, you'll need Git, Make, Node.js, and run the following commands:

``````\$ git clone git://github.com/folktale/laws.git
\$ cd laws
\$ npm install
\$ make bundle
``````

This will generate the `dist/folktale.laws.umd.js` file, which you can load in any JavaScript environment.

This library provides properties for verifying the correctness of an implementation of algebraic structures according to the Fantasy Land specification. They do so by generating random inputs and checking if the algebraic laws holds for your structure.

In order to use these properties, your algebraic library needs to implement the `Eq` typeclass, defined as:

Here's an example of such implementation, for a `Maybe(a)` monad:

• Applicatives
1. Identity
2. Composition
3. Homomorphism
4. Interchange
• Chains
1. Associativity
• Functors
1. Identity
2. Composition
1. Left identity
2. Right identity
• Monoids
1. Left identity
2. Right identity
• Semigroups
1. Associativity

To verify if a data structure conforms to the laws, you need to partially apply the law to a function that constructs a structure holding a single value. For example, if you have an `Identity` container and want to check if it conforms to the Semigroup's law of associativity:

Note that applying the law to the constructor function gives you back a Claire property. There are different ways of using this object, but the easiest one is to use the `asTest(configuration)` method to return a test function. When invoked (with no parameters), this test function will repeatedly generate random inputs to test if your implementation behaves correctly according to the laws.

If any of the inputs invalidates the property, an error is thrown with detailed information about why the property was invalidated. You can control both the amount of details in the reports, and the number of random tests that are performed by passing a configuration object to the `asTest` method. By default the reports are concise and only 100 random tests are performed.

Do note that if `verbose` is false, no message will be printed to the standard output by default.

This library assumes an ES5 environment, but can be easily supported in ES3 platforms by the use of shims. Just include es5-shim :)