freer

≡ ▶ 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.Reader() ~> {ask, local, run}
    • F.State() ~> {get, put, modify, run}
• Related work

≡ ▶ Examples

≡ ▶ Getting started

First we create some handlers and free operations:

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

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

const 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 combitors.

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

const 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 the 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 the 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 to 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.Reader() ~> {ask, local, run}

F.Reader is a factory for Reader effects.

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

F.State is a factory for State effects.

≡ ▶ Related work

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