@safareli/free/README.md

Combination of a free applicative functor and free monad

# Free [![Build Status][build-image]][build] [![npm Version][version-image]][version] [![Code Coverage][coverage-image]][coverage] [![Code Climate][climate-image]][climate] [![License][license-image]][license]

> Combination of a Free applicative functor and Free monad.


## API

Free implements [Functor](https://github.com/fantasyland/fantasy-land#functor), [Applicative](https://github.com/fantasyland/fantasy-land#applicative), [ChainRec](https://github.com/fantasyland/fantasy-land#chainrec) and [Monad](https://github.com/fantasyland/fantasy-land#monad) specifications.

### Functor, Applicative, ChainRec and Monad functions:

- Free.prototype.`map :: Free i a -> (a -> b) -> Free i b`
- Free.prototype.`ap :: Free i a -> Free i (a -> b) -> Free i b`
- Free.prototype.`chain :: Free i a -> (a -> Free i b) -> Free i b`
- Free.`chainRec :: ((a -> c, b -> c, a) -> Free i c, a) -> Free i b`
- Free.`of :: a -> Free i a`


### Free structure functions:

- Free.prototype.`hoist :: Free i a -> (i -> z) -> Free z a`
- Free.`liftF :: i -> Free i a`
- Free.prototype.`retract :: (ChainRec m, Monad m) => Free m a -> TypeRep m -> m a`
- Free.prototype.`graft :: Free i a -> (i -> Free z a) -> Free z a`
- Free.prototype.`foldMap :: (ChainRec m, Monad m) => Free i a -> (i -> m a) -> TypeRep m -> m a`

### Free structure function equivalencies:

- `graft(f) ≡ foldMap(f, Free)`
- `hoist(f) ≡ foldMap(compose(liftF, f), Free)`
- `retract(M) ≡ foldMap(id, M)`
- `foldMap(f, M) ≡ compose(retract(M), hoist(f))`

---

This module was started as port of [srijs/haskell-free-concurrent][haskell-free-concurrent] to JavaScript.


[build-image]: https://img.shields.io/travis/safareli/free/master.svg
[build]: https://travis-ci.org/safareli/free

[version-image]: https://img.shields.io/npm/v/@safareli/free.svg
[version]: https://www.npmjs.com/package/@safareli/free

[coverage-image]: https://img.shields.io/codecov/c/github/safareli/free/master.svg
[coverage]: https://codecov.io/gh/safareli/free/branch/master

[climate-image]: https://img.shields.io/codeclimate/github/safareli/free.svg
[climate]: https://codeclimate.com/github/safareli/free

[license-image]: https://img.shields.io/github/license/safareli/free.svg
[license]: https://github.com/safareli/free/blob/master/LICENSE

[haskell-free-concurrent]: https://github.com/srijs/haskell-free-concurrent/blob/1a56280e8d63e037cf8f9e57aa17ac6a8ac817a5/src/Control/Concurrent/Free.hs