laws
v0.2.1
Published
Verifications for Monad laws according to fantasy-land.
Downloads
280
Maintainers
Readme
Laws
Claire properties for verifying Monad and other algebraic structures' laws, conforming to the Fantasy Land specification.
Example
var Maybe = require('monads.maybe')
var laws = require('laws')
laws.functors.identity(Maybe.Just).asTest({ verbose: true, times: 100 })()
// + OK passed 100 tests.
Installing
The easiest way is to grab it from NPM. If you're running in a Browser environment, you can use Browserify
$ npm install laws
Using with CommonJS
If you're not using NPM, Download the latest release, and require
the folktale.laws.umd.js
file:
var laws = require('laws')
Using with AMD
Download the latest release, and require the folktale.laws.umd.js
file:
require(['folktale.laws'], function(laws) {
...
})
Using without modules
Download the latest release, and load the folktale.laws.umd.js
file. The properties are exposed in the global Laws
object:
<script src="/path/to/folktale.laws.umd.js"></script>
Compiling from source
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.
Getting Started
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:
class Eq a where
-- | True if both structures are equivalent
isEqual :: a -> a -> Bool
Here's an example of such implementation, for a Maybe(a)
monad:
var Maybe = {
/* (...) */
isEqual: function(b) {
return this.isNothing? b.isNothing
: this.isJust? this.value === b.value
}
/* (...) */
}
The Laws
- Applicatives
- Identity
- Composition
- Homomorphism
- Interchange
- Chains
- Associativity
- Functors
- Identity
- Composition
- Monads
- Left identity
- Right identity
- Monoids
- Left identity
- Right identity
- Semigroups
Associativity
Using the laws
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:
// :: a -> Id a
function makeId(a) {
return new Id(a)
}
laws.semigroup.associativity(makeId).asTest({ verbose: true })()
// + OK passed 100 tests
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.
class Configuration where
verbose :: Bool -- * whether to output a detailed report or not
times :: Int -- * number of random tests to perform
Do note that if verbose
is false, no message will be printed to the standard
output by default.
Platform support
This library assumes an ES5 environment, but can be easily supported in ES3 platforms by the use of shims. Just include es5-shim :)
Licence
Copyright (c) 2013 Quildreen Motta.
Released under the MIT licence.