Table of Contents

• About the Project
• Getting Started
• Usage
• Statements Types
• Fantasy Land
• License
• Contact
• Related and similar projects

About The Project

Haskell Do-Notation is a great feature too works with monads.

There are different attempts to bring it Javascript world, that I can resume in these types:

• Generator based: Use generator functions and yield instruction as Haskell bind operator. This would be a great solution but with a very heavy drawback.

• Language Extension: Extend Javascript language to desugar your do code to vanilla javascript. This requires to precompile your code or use eval to dynamic evaluate your "just in time" desugared code (what about debugging? IDE?).

• Emulate by Data structure: The case of this library. We use a vanilla javascript data structure that will be interpreted as Do notation. This brings:

  • 😄 Vannilla javascript. No pre-compilation / eval.

  • 😄 Support non-deterministic Monads.

  • 😄 Computationally Efficient

  • 😔 Non as clean to write/read as generators or language extension.

Getting Started

Add to your project

yarn add yado-js

Usage

You write your Do block as an array of statements.

Every statement is a Javascript object or a function.

We have three types of objects: bind, returns, and to.

You can write these objects directly or using a utility function.

Do keep all declared vars in an object that we call scope (it's like the javascript local scope in the case of the generator function). So every statement can act and change the vars in the scope (see the section about function to discover more).

Let's discover by samples:

Burrido version

import BurridoModule from 'burrido'
const Burrido = BurridoModule.default

const ArrayDo = Burrido({
    pure: x => [x],
    bind: (xs, f) => xs.map(f).reduce((a, b) => a.concat(b)
}).Do

ArrayDo(function * () {
    const x = yield [1, 2]
    const y = yield [3, 4]
    return x * y
}) // [3, 4, 6, 8]

Yado version (no utility function)

import { Do } from 'yado-js'

const ArrayDo = Do({
    pure: x => [x],
    bind: xs => f => xs.map(f).reduce((a, b) => a.concat(b)
})

ArrayDo([
    { x: [1, 2] },
    { y: [3, 4] },
    {return: s => s.x * s.y}
]) // [3, 4, 6, 8]

Yado version (using utility function)

import {Do, bind, returns} from 'yado-js'

const ArrayDo = Do({
    pure: x => [x],
    bind: xs => f => xs.map(f).reduce((a, b) => a.concat(b)
})

ArrayDo([
    bind('x')([1, 2]),
    bind('y')([3, 4]),
    returns(s => s.x * s.y)
]) // [3, 4, 6, 8]

Scope init

By default Do start the computation with an empty scope {}. It's possibile to start computation with an initial scope using Exe.

import {Exe, bind, returns} from 'yado-js'

const ArrayDo = Exe({
    pure: x => [x],
    bind: xs => f => xs.map(f).reduce((a, b) => a.concat(b)
})

ArrayDo([
    bind('x')([1, 2]),
    bind('y')([3, 4]),
    returns(s => s.x * s.y + s.k)
])({k: 1}) // [4, 5, 7, 9]

See below for more example and use cases

Statements Types

Every element of the array passed to Do function is can be a plain object or a function and interpreted as described below.

Objects

• bind
• return
• to

Function

• Statement Returning
• Scope Returning

Objects

bind

Every plain object with keys that are not javascript reserver words (not this to be clear {return: 0})

Example:

import { Do } from 'yado-js'

const ArrayDo = Do({
    pure: x => [x],
    bind: xs => f => xs.map(f).reduce((a, b) => a.concat(b), [])
})

ArrayDo([
    { x: [1, 2] },
    { y: [3, 4] },
    { return: s => s.x * s.y } // [3, 4, 6, 8]
])

In the example the object { x: [1, 2] } is desugared to as we call bind on the argument and assign result to x.

bind([1, 2])(x => bind([3, 4])(y => pure(x * y)))

Is possible to group many binds in the same statement object:

// see up for ArrayDo init
ArrayDo([
    { x: [1, 2], y: [3, 4] },
    { return: s => s.x * s.y } // [3, 4, 6, 8]
])

Instead of directly set a monad instance as argument we can pass a function that takes as input the scope and return a monad instance.

// see up for ArrayDo init
ArrayDo([
    { x: [1, 2] },
    { y: s => [s.x + 1, s.x + 4] },
    { return: s => s.x * s.y }
])

same as:

bind([1, 2])(x => bind([x + 3, x + 4])(y => pure(x * y)))

return

Statement used to return and the Do block. Take as argument a function from scope to a value to be returned or directly a value.

We can have many return statements, look at this sample:

// see up for ArrayDo init
ArrayDo([
    { x: [1, 2] },
    { y: [3, 4] },
    s => (s.x === 2 && s.y === 3 ? [{ return: 0 }] : []),
    { return: s => s.x * s.y }
]) // [ 3, 4, 0, 8 ]

We can write it with utility functions:

// see up for ArrayDo init
ArrayDo([
    bind('x')([1, 2]),
    bind('y')([3, 4]),
    s => (s.x === 2 && s.y === 3 ? [returns(0)] : []),
    returns(s => s.x * s.y)
]) // [ 3, 4, 0, 8 ]

N.B. The utility function is named returns for obvious reason.

to

Shortcut to set a value into the scope.

// see up for ArrayDo init
ArrayDo([
    bind('x')([1, 2]),
    bind('y')([3, 4]),
    to('z')(s => s.x === 2 && s.y === 3)
    s => (s.z ? [returns(0)] : []),
    returns(s => s.x * s.y)
]) // [ 3, 4, 0, 8 ]

The above is like.

// see up for ArrayDo init
ArrayDo([
    { x: [1, 2] },
    { y: [3, 4] },
    s => ({ ...s, z: s.x === 2 && s.y === 3 }),
    s => (s.z ? [{ return: 0 }] : []),
    { return: s => s.x * s.y }
]) // [ 3, 4, 0, 8 ]

functions

When the statement is a function will be executed taking the scope as argument. The function can return two types: Array or Object.

scope => []

Function that returns an array of additional statements that will be interpreted before continue.

// see up for ArrayDo init
ArrayDo([
    bind('x')([1, 2]),
    bind('y')([3, 4]),
    s => (s.x === 2 && s.y === 3 ? [returns(0)] : []),
    returns(s => s.x * s.y)
]) // [ 3, 4, 0, 8 ]

scope => {}

A function that returns an object. The object will replace the block scope.

// see up for ArrayDo init
ArrayDo([
    bind('x')([1, 2]),
    bind('y')([3, 4]),
    s => ({ ...s, z: 1 }),
    returns(s => s.x * s.y)
]) // [ 4, 5, 7, 9 ]

Fantasy Land

The Do function recognize fantasy land compliant monads

import { Do } from 'yado-js'
import S from 'sanctuary'

const MaybeDo = Do(S.Maybe)

MaybeDo([
    { x: S.Just(3) },
    { y: S.Nothing },
    { return: s => s.x + s.y }
]) // null

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Fabiano Taioli - [email protected]

Project Link: https://github.com/FbN/yado-js

Related and similar projects

Some library found looking around. In no any special order.

• Burrido: Based on generator functions. Must re-run computation for every value. Pure and bind must be side-effect free. Inefficient, requiring O(n^2).
• Fantasy Do: Same as Burrido but target Fantasy land compliant monads. Same pro/contro.
• Monadic: Javascript language expansion. Compiled or by code eval.
• @masaeedu/do: Similar to this project. You must declare binded vars at start. Lack features (many return points).
• monadicjs:
• monio: Use generator and promises. Do not support non deterministic monads.