@visisoft/staticland v2.0.0-alpha.3

Support programming in functional pipelines by exposing a familiar set of operations on asynchronous, optional and faulty data.

Operations (Transforming, Lensing, Combination, etc.) on Algebraic Data Types (ADT) (Either, Maybe, Promise, CancelableComputation) provided as sets free static functions.

Motivation

For the motivation I'd like to refer to James Sinclair's post on StaticLand.

Data Types

Each set of these free static functions expect a particular data-holding type. @visisoft/staticland is very un-opinionated about the data type. E.g. the operations on non-cancelable computations simply expect a Promise as data type. This makes crossing the boundary into and out of @visisoft/staticland especially easy.

Each data type represents a particular computational feature or aspect of programming. For instance an optional value is a Maybe, and a CancelableComputation represents just that. @visisoft/staticland does not "provide" data types e.g. as classes for these computational features. It is not productive to find the best implementation of a data type. The function sets of @visisoft/staticland choose to operate on just the simplest JavaScript objects – Array, Function or (as already mentioned) Promise. In Functional Programming (FP) factory and consumption functions are provided to interface with external code.

Sets of Operations

To its particular data type, each set of operations permit the transforming, the combining, the iterating or the focusing on an item of the data structure. Thus, the sets of operations have a lot in common – e.g. each have the functions map, and chain.

Admittedly, this brings an inflation to the api surface when working with different data types. Also, since each use of e.g. map or chain is targeted to a particular data type, the operations must be carefully placed, so that with nested data types the sequence of operations reflects the structure of the nested data exactly.

On the other hand,

the current data type can be derived by looking at the code,
using the TypeScript signatures, the code inspector can deduce the type correctness, and
third-party data types can be integrated in this concept without altering or augmenting their provided data type, but by simply writing another set of operations.

FantasyLand

It is worth mentioning the competing concept of FantasyLand. It features a unified set of operations which operate on all compatible data types. Technically, it does so be enforcing compatible data types to implement a particular protocol – i.e. carefully named object methods. The benefits are clear:

Each common function (e.g. map) has to be imported only in it's FantasyLand version to work with all applicable data types (e.g. Functor).
Calling a free static common function with a wrong data type is no longer possible.

The free static functions of FantasyLand are just a shell which delegates to the operation implemented in the particular method of the data object. One prominent provider of such shell functions is the FP toolkit Ramda. Like Ramda @visisoft/staticland/fantasyland also provides these common functions, with the exception that they also support Promise.

Behind the promising advantage of having a unified set of operations, FantasyLand has drawbacks. Even among Ramda users its adoption is not 100% which this comment illustrates.

Library authors need to be convinced to understand the FantasyLand protocol and implement it in their data types.
Often libraries already provide free static functions like map and chain tailored to their data type. These integrate nicely with the StaticLand concept.
The FantasyLand specification has several versions, allowing for a possible mismatch between FP toolkit and the data type library.

In the search to overcome these drawbacks the concept of StaticLand was discovered. Both concepts are compared in an article by James Sinclair.

Homepage and Documentation

Hello @visisoft/staticland

Installation

When developing for Node.js

npm install @visisoft/staticland

When developing for the browser

npm install --no-optional @visisoft/staticland

Hello Earth

Greeting with a 0.5 sec 2-way delay.

Usage in an ES module

import {chain, map} from '@visisoft/staticland/fantasyland';
import {mapRej as mapRej_p} from '@visisoft/staticland/promise';
import {fromThrowable} from '@visisoft/staticland/either';
import {fromNilable, getOrElse} from '@visisoft/staticland/maybe';
import {eitherToPromise } from "@visisoft/staticland/transformations";
import {curry, pipe} from 'ramda'; // or pipe from 'crocks' or any other composition function

const 
   // :: String -> {k: String} -> Maybe String
   getProperty = curry((property, object) => fromNilable(object[property])),
   // :: a -> Promise any a
   delay = x => new Promise(resolve => setTimeout(resolve, 500, x)),
   // :: any -> Either Error String
   safeGreet = fromThrowable(x => "Hello " + x.toString() + "!"),
   // :: any -> Promise (Maybe String) String
   getAnswer = pipe(
      delay,                            // Promise any             any
      map(safeGreet),                 // Promise any             (Either Error String)
      chain(delay),                   // Promise any             (Either Error String)
      chain(eitherToPromise),         // Promise (any|Error)     String
      mapRej_p(getProperty('message'))  // Promise (Maybe String)  String
   );

getAnswer("Earth")
.then(console.log, me => console.warn(getOrElse("unknown error", me)));
// -> "Hello Earth!"

getAnswer(null)
.then(console.log, me => console.warn(getOrElse("unknown error", me)));
// -> "Cannot read property 'toString' of null"

Usage in a CommonJS module

const 
   {chain: chain_p} = require('@visisoft/staticland/promise'),
   delay = t => x => new Promise(resolve => setTimeout(resolve, t, x));

chain(delay(500), Promise.resolve("foo")).then(console.log);

Design

Most functions comply with Static-Land`s algebraic laws. Where this is not possible (e.g. nesting of resolved Promises) a few reasonable paradigms have to be followed when using this library.

At the expense of complete algebraic lawfulness the data wrapping remains transparent and light-weight.

The functions are designed to support the usual functional programming style in JavaScript as it is the design philosophy for many libraries for example Ramda's:

Emphasise a purer functional style. Immutability and side-effect free functions help to write simple yet elegant code.
Automatic currying. This allows you to easily build up new functions from old ones simply by not supplying the final parameters.
Parameter order supports convenient currying. The data to be operated on is generally supplied last, so that it's easy to create functional pipelines by composing functions.

Ramda-Fantasy is very well documented, but sadly no longer maintained. Crocks is an exemplary implementation of common data types.

Dependencies

As FP utility library Ramda is used.

closed over

A closure is the combination of a function and the lexical environment within which that function was declared.