≡ ▶ Freer ·

This is an experimental JavaScript library that implements a Free (or Freer) monad with composable effect handlers.

WARNING: This library is not yet ready for production use.

≡ ▶ Contents

• Examples
  • Getting started
  • Running sum of leaves
• Reference
  • Free monad
    • F.Free ~> monad
  • Free combinators
    • F.map(value => value, free) ~> free
    • F.of(value) ~> free
    • F.ap(free, free) ~> free
    • F.chain(value => free, free) ~> free
  • Identity handler
    • F.run(free) ~> value
    • F.runAsync(free) ~> promise
  • Do notation
    • F.from(async $ => { ... await $(free) ... }) ~> free
    • F.toAsync(free) ~> free
  • Defining new handlers
    • F.handler((value, any) => free, (effect, continuation, any) => free) ~> (free, any) ~> free
  • Handlers à la carte
    • F.Exception([{concat[, empty]}]) ~> {raise, handle[, zero], alt, alts, run}
    • F.Reader() ~> {ask, local, run}
    • F.State() ~> {get, put, modify, run}
• Related work

≡ ▶ Examples

≡ ▶ Getting started

First we create some handlers and free operations:

var aReader = F.Reader()
var aState = F.State()

Then we define an ad-hoc operation that uses the previously defined free operations:

var addReaderToState = F.from(async $ => {
  const v = await $(aReader.ask)
  return $(aState.modify(R.add(v)))
})

The above uses a do notation approximation provided by this library. One could also define the above operation using just the basic monadic combinators.

Then we compose a runner that handles the operations we used:

var aRunner = R.compose(F.runAsync, aState.run(1), aReader.run(2), F.toAsync)

Finally we run the operation and log the result:

aRunner(addReaderToState).then(console.log)
// Promise 3

≡ ▶ Running sum of leaves

Here is an example using traverse from Partial Lenses to compute a running sum of the leaves of a nested data structure:

R.compose(F.run, aState.run(0))(
  L.traverse(
    F.Free,
    x => aState.modify(R.add(x)),
    L.leafs,
    [{x: 3, y: [1]}, {z: [4, 1]}]
  )
)
// [{x: 3, y: [4]}, {z: [8, 9]}]

≡ ▶ Reference

The combinators provided by this library are provided as named exports. Typically one just imports this library as:

import * as F from 'freer'

The examples also make use of the Partial Lenses and Ramda libraries imported as:

import * as L from 'partial.lenses'
import * as R from 'ramda'

Neither of those libraries is required in order to use this library.

≡ ▶ Free monad

≡ ▶ F.Free ~> monad

F.Free is the Static Land compatible Monad definition for the monad provided by this library.

≡ ▶ Free combinators

≡ ▶ F.map(value => value, free) ~> free

F.map is the Static Land compatible map combinator of the monad provided by this library.

≡ ▶ F.of(value) ~> free

F.of is the Static Land compatible of combinator of the monad provided by this library.

≡ ▶ F.ap(free, free) ~> free

F.ap is the Static Land compatible ap combinator of the monad provided by this library.

≡ ▶ F.chain(value => free, free) ~> free

F.chain is the Static Land compatible chain combinator of the monad provided by this library.

≡ ▶ Identity handler

≡ ▶ F.run(free) ~> value

F.run is the identity handler for the free monad. It doesn't handle any effects per se, it just extracts the result of the computation.

≡ ▶ F.runAsync(free) ~> promise

F.runAsync is the asynchronous identity handler for the free monad. It only handles promises.

≡ ▶ Do notation

≡ ▶ F.from(async $ => { ... await $(free) ... }) ~> free

F.from is used to wrap an async $ => { ... } function that await $( ... )s for effects, reminescent of a do notation, as a free operation to be handled by F.toAsync.

≡ ▶ F.toAsync(free) ~> free

F.toAsync is the handler for the operations produced by F.from and converts those effects to promises. This handler must be before handlers for effects used in the operations produced by F.from and the promises need to be handled by F.runAsync. In other words, the handler composition should look like R.compose(F.runAsync, ..., F.toAsync).

≡ ▶ Defining new handlers

≡ ▶ F.handler((value, any) => free, (effect, continuation, any) => free) ~> (free[, any]) ~> free

F.handler defines a handler for some effects. The first argument is the handler for the final result. The second argument is the handler for some effects. It is given an effect, which the handler may or many not know how to handle, and the continuation and it must then return a free operation.

≡ ▶ Handlers à la carte

≡ ▶ F.Exception([{concat[, empty]}]) ~> {raise, handle[, zero], alt, alts, run}

F.Exception is a factory for Exception handling effects. The optional argument is a semigroup or monoid used for combining exception values in alt and alts. In case the argument is just a semigroup, alts requires at least one operation and there will be no zero. The default argument is a semigroup that uses the last exception value.

Given const Ex = F.Exception(),

• Ex.raise(any) ~> free raises the given value to the closest enclosing Ex.handler or to the top of the handler stack,
• Ex.handle(any => free, free) ~> free handles values raised from the given operation,
• Ex.zero ~> free is equivalent to Ex.raise(empty()) when the argument to F.Exception is a monoid,
• Ex.alts(...free) ~> free tries the given operations in turn and returns the result of the first operation that completes without raising or raises the values accumulated from all the operations that raised,
• Ex.alt(free, free) ~> free is a curried binary version of Ex.alts, and
• Ex.run is the handler for the operations.

For example:

const Ex = F.Exception()

R.compose(F.run, Ex.run)(
  Ex.alt(
    Ex.raise(`You'll never see me!`),
    Ex.handle(
      e => Ex.raise(`Nor me!`),
      F.of(`This is what you'll get!`)
    )
  )
)
// 'This is what you'll get!'

≡ ▶ F.Reader() ~> {ask, local, run}

F.Reader is a factory for Reader effects.

Given const Rd = F.Reader(),

• Rd.ask ~> free is an operation whose result is the value from the reader,
• Rd.local(value => value, free) ~> free returns an operation that runs the given operation with the value of the reader modified with the given function, and
• Rd.run(value, free) is the handler for the operations.

For example:

const Rd = F.Reader()

R.compose(F.run, Rd.run(1))(
  F.ap(Rd.local(R.inc, F.map(R.add, Rd.ask)), Rd.ask)
)
// 3

≡ ▶ F.State() ~> {get, put, modify, run}

F.State is a factory for State effects.

Given const St = F.State(),

• St.get ~> free is an operation whose result is the current state,
• St.put(value) ~> free is an operation that replaces the state with the given value,
• St.modify(value => value) ~> free is operation that updates the state with the given function and whose result is the new state, and
• St.run is the handler for the operations.

For example:

const St = F.State()

R.compose(F.run, St.run(undefined))(
  L.traverse(
    F.Free,
    it => F.chain(
      prev => (it === prev ? F.of(undefined) : St.modify(R.always(it))),
      St.get
    ),
    L.elems,
    [1, 2, 2, 1, 1, 3]
  )
)
// [1, 2, 1, 3]

≡ ▶ Related work

The core of this library is based on ideas from Extensible Effects: an alternative to Monad Transformers.