Monadic-progress

A tiny library designed to simplify common progress tracking tasks (i.e. worker-based background processing, http polling) and assure value safety by 'swallowing' unsafe values and automating comparisons across subsequent chain calls. Makes heavy use of Ramda and Ramda-adjunct, written in a (mostly) functional manner.

Installation:

npm i -s monadic-progress

Example usage:

Import one of the default factories

const { array: Progress } = require('monadic-progress')
const progress = Progress.of([42])
//or
const { value: Progress } = require('monadic-progress')
const progress = Progress.of(42)

or the basic Progress factory function (keep in mind, that unlike factories, this one requires some configuration):

const Progress = require('monadic-progress/src/Progress')
const progress = Progress.({ options }, 42)

The Default array factory expects chain (aka bind) and map input to be wrapped in an array (non-array types are considered unsafe and ignored). This is because it runs Ramda's 'difference' against last two values. The following code will evaluate to 'None' for that reason:

const progress = Progress.of(["initial state"])
  .chain(prev => Progress.of(prev, ["some other state"]))
  .chain(() => undefined)
  .chain(() => Progress.of(["some other state"]))
  .chain(() => Progress.of(null)
  .chain(() => Progress.of(["different state"]))
  .chain(() => 5))

console.log(progress.flatten()) //prints 'None {}'

This snippet will print '[42]' though:

const progress = Progress.of(["initial state"])
  .chain(prev => Progress.of(prev, ["some other state"]))
  .chain(() => undefined)
  .chain(() => Progress.of(["some other state"]))
  .chain(() => Progress.of(null)
  .chain(() => Progress.of(["different state"]))
  .chain(() => [42]))

console.log(progress.flatten()) //prints [42]

This behaviour is configurable via opts argument of the Progress factory function. Default factories preconfigure it with a set of 3 functions, the process of customising the configuration is as simple as defining a new set and passing it to the aforementioned Progress factory function.

Expected functions are:

valueSafe -> boolean Run against all the values known to Progress instance. Comparison (flatten / join) will return 'None' if any value evaluates to false. Defaults to 'F'. Array factory uses 'isArray' and value factory defaults to 'isNotNil'.

compare -> any Run against last two values in reversed order, defaults to 'None', Array factory uses 'difference' and value factory defaults to negated 'equals'.

differs -> boolean Run against comparison result to determine whether it should be considered a match, 'None' is returned in other case. Defaults to false. Array factory uses 'isNotEmpty' and value factory defaults to 'isNotNil'.

Check 'demo' for alternative configuration examples.

Build

Powered by 'Rollup' and 'Runjs'

Run npx run build or use the command defined under the build task in 'runfile.js'.

By default, Rollup will build umd, Commonjs and ES6 compatible bundles, adjustment can be achieved by changing the contents of 'formats' array inside the rollup.config.js file.

Test

Run npx run test or use the command defined under the 'test' task in the 'runfile.js'.

Demo

Run npx run demo for an example of Progress run against a fake http server with array factory. Accepts two arguments --method=[pull|push] (defaults to 'push') and --type=[default|int-equals|int-subtract] (surprisingly, defaults to default). The type argument is used by the demo artifacts to build the require path for the subfolder where data and options files are kept.

API

To create an instance of Progress monad run:

const { array: Progress } = require('monadic-progress')
const progress = Progress.of([value])

or

const Progress = require('monadic-progress/src/Progress')
const progress = Progress({ options }, 42)

Functor-like mapping:

const { array: Progress } = require('monadic-progress')

const progress = Progress.of([42]).map(x => [...x, 5])
console.log(progress.join()) //prints [5] 

Flat mapping ( aka bind / chain ):

const { array: Progress } = require('monadic-progress')

//implicit value lift
const progress = Progress.of([42]).fmap(x => [...x, 5])
console.log(progress.join()) //prints [5]

//explicit value lift
const progress = Progress.of([42]).fmap(x => Progress.of(x, [5]))
console.log(progress.join()) //prints [5]

Flatten (aka join / value):

const { array: Progress } = require('monadic-progress')

const progress = Progress.of([42]).fmap(x => Progress.of(x, [5]))
const value = progress.join()
console.log(value) //prints [5]

Peek (aka log):

const { array: Progress } = require('monadic-progress')

const progress = Progress.of([42]).fmap(x => Progress.of(x, [5]))
const entries = progress.peek()
console.log(entries) //prints [[42],[5]]

The None type

The default value returned by the join / flatten method if no difference is found across subsequent calls or one of the last two values evaluates to unsafe. Exposes static spec method for convenience.