A monadic library for easily composing React-based libraries.
npm install monadic_reactIt does so by defining a monadic interface around React components. This interface is then used to support construction of a series of useful combinators. The library is written in TypeScript, and is provided with definition files: it can be used from both plain JavaScript and TypeScript.
The net result is a painless React development experience. Complex concurrency, state machines, and intricate data flow relations between components can be modelled explicitly and easily. For example, with monadic react, the following become much simpler to define:
- data flows
- forms
- concurrency
and much more.
npm install monadic_react.C, for example:``
let my_component : C
string("view")("Hello world of monads!").ignore()
The component is then wrapped in a page for the router. Let us keep things easy and define a route which matches everything:
`
let menu_page = () : Route<{}> => ({
url: fallback_url(),
page: (_:{}) => my_component
})
The component can then be instantiated by invoking the application constructor and router:
`
{
application("edit", window.location.href, "", Promise.resolve([main_page()]))
}
By working on the definition of my_component it is possible to create much more complex applications. For example, let us
chain two components together:
`
let my_component : C
multi_selector, n =>`
string("view")(JSON.stringify(n.toArray())).ignore())
In the sample above we have used the then operator in order to feed the output of the multi-selector in the string renderer.
By focusing on the flow of data generated by react components, instead of what they do on the page and how they are rendered, we focus on how components are connected together in a large network of related functionality. This removes the need for a lot of glue code which just passes information around, while preserving useful properties such as referential transparency (components can be designed fully stateless now), and type safety (components have clearly defined and typed boundaries).
For example, the string component will produce a string which will be fed into another component, for example a component which assembles data from various input components for later upload.
in the JavaScript world;
- flatMap in the Immutablejs library;
- LINQ in C#;
- the Haskell standard library;and more. Moreover, countless tutorials are found online where people who already found out about this elegant and powerful concept try to share it with others.
At its core, a monad is a generic type
M, that is M was defined along the lines of:`type M = ...`When we define a monad in terms of
, then it means that we want to be able to instantiate, and use, instances of M without having to know anything about its structure.The simplest operation that we need to be able to perform is creating instances of
M. This is done with the unit operator, which creates an instance of M around a value of type A, no matter what type A actually was:unit : A => MGiven an
, we then want to be able to compose it with other instances of M which are dependent of it. This dependency is expressed by saying that, in order to get to the instance of M that we wish to obtain, we need a value of type A which will somehow come out of M:then : M => (A => M) => M(Note: a proper name for
would be bind, but since it is already a member of function objects, this would lead to mistakes.)After having defined
unit and then, which are the bare minimum needed in order to be able to have a working monad, we can start thinking in terms of usability of our monad as a library. This usually leads to an "onion" design, with a basic core, surrounded by primitives, surrounded by combinators, templates, etc. As long as primitives, combinators, and templates all yield instances of M, they will still be valid input for further thening or applying the other combinators yet again. This is the fundamental principle of composability: a library should make it possible to keep nesting constructs inside each other in order to be flexible and not artificially constraining.It is useful for some to first learn monads in terms of simple, concrete containers such as
Option or List, and then move on to the more abstract ones such as the present implementation.$3
The core of the library, found in file core.tsx, contains the definition of the monad itself, C. An instance of the monad is a function which takes as input a callback to signify completion, a continuation which will accept a value of type A (the data produced by the component, from now on called output of the component); finally, the monad returns a JSX.Element, which is the actually renderable component:`
type Cont = (callback:() => void) => (_:A) => void
type C = {
comp:(ctxt:() => Context) => (cont:Cont) => JSX.Element
...
}
Using the library does not require interacting with this data type directly: that is done by invoking functions
and then:`
unit = function(x:A, key?:string, dbg?:() => string) : C = ...then = function(key:string, p:C, k:((_:A)=>C), className?:string, dbg?:() => string) : C = ...
Notice that, in contrast with the definitions of
and then given above, we have some more parameters: since react expects a key in order to accelerate the reconciliation process, all generated components may specify an (optional) key. then will still work if the key is passed as undefined, even though it is not always ideal.Of course, we can also perform basic transformations on components' data, for example by applying a given transformation function to each output of an existing component. This effectively turns a component of type
C in a (related) component of type C, as long as we provide a function f:A=>B:`
let map: (key?: string, dbg?: () => string) => (f: (_: A) => B) => (_: C) => C;
Similarly, we can restrict the output of an existing component. This effectively turns a component of type
in a (related) component of type C which outputs slightly less values of type A, as long as we provide a predicate p:A=>boolean:`
filter: (key?: string, dbg?: () => string) => (p: (_: A) => boolean) => (_: C) => C;
Note that, given an instance
, we can directly call some methods on it such as: p.then(...), p.ignore(), p.never() instead of having to invoke then(p, ...).$3
Having defined the core operators is just the first step. To be able to do anything actually useful on a webpage, we have defined a series of primitives which encapsulate common HTML constructs as instances of our monad. Each primitive accepts as input the mode ("view" | "edit") in order to instantiate the component as editable or just to show its contents.The primitive then returns a function with, as input, the initial value of the type it manipulates (let's call it
P) and gives as output a component of that type (that would be C).
For example, the number primitive, after we have given the mode (and optionally the key), results in a function number => C:
`
number: (mode: Mode, key?: string, dbg?: () => string) => (value: number) => C
The string primitive, after we have given the mode (and optionally the key), results in a function string => C:
`
string: (mode: Mode, type?: StringType, key?: string, dbg?: () => string) => (value: string) => C
And so on. There are further primitives for bool (bool => C), date, time, and date_time (all three Moment.Moment) => C).
. The decorator then returns a result with the same signature, that is A => C:`
label(text: string, span_before_content?: boolean, className?: string, key?: string, dbg?: () => string): (p: (_: A) => C) => ((_: A) => C)
h1(text: string, className?: string, key?: string, dbg?: () => string): (p: (_: A) => C) => ((_: A) => C)
h2(text: string, className?: string, key?: string, dbg?: () => string): (p: (_: A) => C) => ((_: A) => C)
div(className?: string, key?: string, dbg?: () => string): (ps: Array<(_: A) => C>) => (p: (_: A) => C) => ((_: A) => C)
overlay(key?: string, dbg?: () => string): (ps: Array<(_: A) => C>) => (p: (_: A) => C) => ((_: A) => C)
form(className?: string, key?: string, dbg?: () => string): (p: (_: A) => C) => ((_: A) => C)
Buttons (and anchors) are slightly simpler in signature. The button, after receiving the configuration parameters, returns a function
. This function is "interrupted" by the button: before the returned component C will return the value of A that came in as input, the button must be clicked:`
button: (label: string, disabled?: boolean, key?: string, className?: string, dbg?: () => string) => (x: A) => C
a: (label: string, disabled?: boolean, key?: string, className?: string, dbg?: () => string) => (x: A) => C
Other html components perform an own function. The selectors take as input the candidate items for selection, a
function which tells how to draw a selectable item, and return the selected item(s):`
selector: (type: SelectorType, to_string: (_: A) => string, key?: string, dbg?: () => string) => (items: Array, selected_item?: A) => C
multi_selector: (type: MultiSelectorType, to_string: (_: A) => string, key?: string, dbg?: () => string) => (items: Array, selected_items?: Array) => C>
Finally, some html components allow the manipulation of links, files, and images (in base64).
image: (mode: Mode, key?: string, dbg?: () => string) => (src: string) => C
link: (label: string, url: string, disabled?: boolean, key?: string, dbg?: () => string) => C
file: (mode: Mode, label: string, url: string, disabled?: boolean, key?: string, dbg?: () => string) => C
A special mention goes to the rich text component, which takes as input a string containing the (serialized) json input needed by a DraftJs rich text editor:
rich_text(json_state: string, mode: Mode, key?: string, dbg?: () => string): C
$3
Combinators are the next step in the abstraction chain (the next layer in the onion). Combinators are abstract transformers which take as input one or more (functions of) components and yield new (functions of) components.The simplest combinator is
. repeat takes as input a function p:A => C, and returns as output a function A => C. The returned function, whenever it receives and input of type A, passes it through to p. The output of p is then given as output of the returned function. The output of p is also fed back into p itself (which should be smart enough to see that the input is the same, and therefore not yield another output right away):`
repeat: (key?: string, dbg?: () => string) => (p: (_: A) => C) => (_: A) => C;
by itself is not very useful. When it really shines is in combination with any. any accepts as input an array of functions ps:(A => C), and returns as output a single function A => C. The returned function passes its own input (A) to each function in ps. The first of the resulting components that yields a B as output gets its output forwarded as the output of any:`
any: (key?: string, className?: string, dbg?: () => string) => (ps: ((_: A) => C)[]) => (_: A) => C;
Sometimes we need to perform a conversion from a complex datatype (say
) into a simpler (say B). Suppose we have a series of conversion functions:
- inb:A => B to convert an A to a B;
- out:A => B => A to convert the original A and a new value of B back into B.Then we can convert a function
p:B => C into A => C:`
retract: (key?: string, dbg?: () => string) => (inb: (_: A) => B, out: (_: A) => (_: B) => A, p: (_: B) => C) => (_: A) => C;
As an example of a retraction, consider:
type Person = { Name:string, Surname:string }let person_name : (_:Person) => C = p =>
retract()(p => p.Name, p => n => ({...p, Name:n}), string("view"))
When combined with
and any, then we get a form:`
let person_form =
repeat("state_repeater")(
any("field_selector")([
person_name,
person_surname
])
).then("person_form", p =>
...do something with p...)
, similarly to any, gets as input an array of components and, when all components have yielded an output, all the outputs are passed through:`
all: (ps: C[], key?: string, dbg?: () => string) => C;
We can turn a
into a component by "lifting" it:`
lift_promise: (p: (_: A) => Promise, retry_strategy: RetryStrategy, key?: string, dbg?: () => string) => (_: A) => C;
Finally, given a component
, we can turn into a silent component of type C (that is, a component which will never output a value of type B) by applying never to it:`
never: (p: C, key?: string) => C;
$3
The library comes with routing included. The function , which instantiates a component, accepts as input a list of routes.Routes are composed of an
url and a page. The url is created by invoking make_url on an array of url elements:`
make_url: (template: UrlElement[]) => PartialRetraction
For example, we could invoke
as:
- make_url<{}, never>(["about"]), which parses url /about;
- make_url<{}, never>(["info"]), which parses url /info;
- make_url<{}, never>(["info", "team"]), which parses url /info/team.Parsing an url might also yield some data which has been extracted from the url itself, such as an id. In this case, we must define a data structure to be extracted from the url, and then construct the template so that the proper fields are identified:
`
type Id = { id:number }
make_url(["customer", { kind:"int", name:"id" }])
Note that the above is typesafe. Invalid variations will give a compiler error, for example:
-
will complain that xxx is not a field of Id;
- make_url will complain that zzz is not a field of Id.
As we have assembled an url which yields a value of type
T, we can define the page as a function T => C. Of course, if parsing has failed and we could not extract a value of type T from the url, then we cannot invoke the function and instantiate the page:`
let about : Route<{}> = {
url: make_url<{}, never>(["about"]),
page: _ => ... definition of about page ...
}
as defined above can be used as an entry in the list of routes that are given to the application function. Notice that application also accepts a base_url, which will be kept intact, and the current slug, which is used as input for the router.A component can also set its own url. This is simply achieved by getting the context and then invoking its method
set_url with a url payload (in the sample below assume variable t:T and K keys of T):`
get_context().then(s.description, c =>
c.set_url(t, make_url([...url elements...])).then(
...)
Note that a special url is
, which matches any url. It is usually used for handling errors or making sure that the homepage is accessible even if the address has been wrongly typed.$3
Based on the functionality that we have set up so far, it becomes possible to define templates. Templates usually take as input one or more components, and return themselves a component which coordinates and augments the input components:`
template : (C, C, C, ...) => C
#### Menu template
A very useful template is the
. The entries of the menu are defined as either entries or sub-menus. The sub-menus may only have entries:`
type MenuEntryValue = { kind:"item", value:A }
type MenuEntrySubMenu = { kind:"sub menu", label:string, children:Array> }
type MenuEntry = MenuEntryValue | MenuEntrySubMenu
We can easily construct menu entries by means of utility functions:
mk_submenu_entry = function(label:string, children:Array>) : MenuEntrySubMenu { return { kind:"sub menu", label:label, children:children } }
mk_menu_entry = function(v:A) : MenuEntryValue { return { kind:"item", value:v } }
The
is a template which takes as input a series of items, a default selection (and sub-selection), and a component p that works with the current selection (p:A => C). The component p is the "inner content" of the menu. The menu itself passes the output of p through, therefore the simple_menu returns a C as result:`
simple_menu = function(type:SimpleMenuType, to_string:(_:A)=>string, key?:string, dbg?:() => string) :
((items:Array>, p:(_:A)=>C, selected_item?:A, selected_sub_menu?:string) => C)
Sample usage is quite intuitive: we define a data structure which we can render, pass a list of such structures to
, and pass an appropriate renderer (in this case the renderer is just stored in the page itself, but this need not be the case):`
type MyPage = { title:string, content:C }export let menu_sample : C =
simple_menu("side menu", p => p.title,
)(
[
{ title:"About", content:string("view")("This page talks about us")},
{ title:"Content", content:string("view")("This page is full of interesting content")}
],
p => p.content
).ignore()`
#### Form templates
Other very useful templates are the form templates. The form templates take care of typical form-related tasks.
The
is the core of the form templates. It takes as input a declarative description of the attributes to show in the form, and returns a function FormData which essentially goes from an instance of the model M to populate the initial form, to a component which will yield the new value(s) of M:`
simple_inner_form = function(mode:Mode, model_name:(_:M)=>string, attributes:FormEntry[]) : (_:FormData) => C> {
The reason why we work with
instead of directly with M is that FormData contains both an instance of the model and eventual validation errors:`type FormData = { model:M } & FormErrors `The form entries declaratively represent individual elements of the form, described as a discriminated union. For each form entry, we specify the name of the attribute, the function to extract the value of the attribute from the model (
), the function to merge the new value of the attribute with the model (out:M=>string=>M), and a validation function for this attribute:`
type FormEntry =
| { kind:"string", field_name:string, in:(_:M)=>string, out:(_:M)=>(_:string)=>M, get_errors:(_:M)=>Array }
| { kind:"number", field_name:string, in:(_:M)=>number, out:(_:M)=>(_:number)=>M, get_errors:(_:M)=>Array }
| { kind:"date", field_name:string, in:(_:M)=>Moment.Moment, out:(_:M)=>(_:Moment.Moment)=>M, get_errors:(_:M)=>Array }
...
Some form entries are meant for an auto-saving form. For example,
and lazy file will directly upload the new values the moment they are changed in the form, without passing them through to a save button:`
type FormEntry =
...
| { kind:"lazy image", field_name:string, download:(c:M) => C, upload:(c:M) => (src:string) => C }
| { kind:"lazy file", field_name:string, filename:(_:M) => string, out:(_:M)=>(_:File)=>M, url:(_:M) => string, upload:(_:M) => (_:File) => C }
Of course a form also needs to save data. After building the form with
, we could simply compose it with then to a button. The button acts as a filter which propagates the data it receives (of type FormData) whenever it is clicked. The button is then further bound to a component responsible for saving. In pseudocode:`
download.then(
simple_inner_form.then(
button.map((fd:FormData) => fd.model).then(
upload)))
This strategy is so recurrent that we have provided a template for it, called
, which accepts not only the entries needed by the inner form, but also the download and upload components:`
simple_form_with_save_button = function(mode:Mode, model_name:(_:M)=>string, entries:FormEntry[], download_M:C, upload_M:(_:M)=>C) : C
Of course, the strategy above could also be implemented without adding a button, and immediately (actually we use a
to wait at least 200ms) upload the new data. In this case we obtain an auto-saving form. This alternate strategy is also quite common, therefore it is implemented as a template:`
simple_form_with_autosave = function(mode:Mode, model_name:(_:M)=>string, entries:FormEntry[], download_M:C, upload_M:(_:M)=>C) : C
#### Workflow template
Given various components, each associated with a name, it is possible to show them sequentially, connecting them via the well known "next"/"prev" buttons. This is precisely what the
does. It takes as input a map of step names (of type S) and individual pages of the workflow (of type WorkflowData), and manages the workflow:`
simple_workflow = function(workflow_name:string, steps:Immutable.Map) => C>>, initial_model:C, initial_step:S) : C
The
contains the current value of the model (of type M) being built by the workflow, and the current step (of type S):`
type WorkflowData = { model:M, step:S }
$3
It might seem that the current library, despite its great expressive power, could be restrictive: since everything has to conform to interface , it might seem that the existing world of react components is cut out. Fortunately, this is not the case: it is possible to use external components with a very simple wrapping strategy, which is called custom. custom accepts as input a render function which will, in turn, accept as input the monadic react context and the continuation to invoke when the wrapped component is done. The result of custom is yet another C, but the yielded values of type A are passed through from the custom component:`
custom = function(key?:string, dbg?:() => string) : (render:(ctxt:()=>Context) => (_:Cont) => JSX.Element) => C {
An example of this wrapping strategy involves defining one's (adapter) component which must accept context and continuation as properties:
type CounterProps = { ..., context:()=>Context, cont:Cont }
type CounterState = { ... }
class Counter extends React.Component {
...
}
This component is then later on invoked by
:`
custom()(ctxt => cont =>
$3
The core of the application is meant to be stable and unchanging. This means that the basic behaviour of , then, map, etc. can simply be expected to remain the same.Templates and combinators, on the other hand, should rather be seen as dynamic entities: depending on the domain, it is possible to build one's own templates and combinators in order to capture local structures of the application being built.
#### Building your own templates
_Note: the following contains a mix of TypeScript and pseudocode_
Building templates is perhaps the most commonly occurring scenario. Templates are reusable components which automate some recurring tasks. Templates are therefore used to capture domain-specific knowledge, and reduce code duplication.
Typical uses for templates are the definition of page structures, for example a page that is divided in four blocks would take as input four components, joining them together roughly as:
`
four_blocks : (b1:C,b2:C,b3:C,b4:C) => C
The implementation of
would roughly just invoke the four blocks inside any. Whenever a block has an output, the output is just passed through as output of four_blocks itself:`
let four_blocks = function(b1:C,b2:C,b3:C,b4:C) : C {
return any()([
_ => b1, _ => b2, _ => b3, _ => b4
])(null)
}
Of course, the blocks could be less anonymous. For example, a page with a menu, a header, a footer, and a content could have a signature such as:
standard_layout : (menu:C, content:(_:A) => C, header:C, footer:C) => C
The implementation of
thens the menu and the content together, whereas header and footer are just "silenced" by means of the never combinator:`
let standard_layout = function(menu:C, content:(_:A) => C, header:C, footer:C) : C {
return any()([
div( _ => header.never())
div( menu_with_content_class_name, _ => menu.then(menu with content, x => content(x)))
div( footer_class_name, _ => footer.never())
])(null)
}
`#### Building your own combinators
_Note: the following contains a mix of TypeScript and pseudocode_
It is also possible to define one's combinators. This usually requires defining a supporting React component (a separate class). The typical workflow for defining a combinator
usually involves defining:
- the attributes needed by k (KProps);
- the output type of k (B);
- the React component class for k (K);
- the function to instantiate the class.The general shape becomes therefore:
`
type KProps = { ...attributes needed by k... } & CmdCommon
type KState = { ...state needed by k... }
class K extends React.Component {
...
}
let k = function(...attributes needed by k...) : C {
return make_C(ctxt => cont =>
React.createElement(K,
{ ...attributes needed by k..., context:ctxt, cont:cont, key:key }))
}
The definition of class
should be quite careful when it comes to invoking cont. Too many accidental invocations can lead to loops, especially in the presence of repeat (very common when building forms). On the other hand, K is expected to invoke cont upon componentWill/DidMount and componentWillReceiveProps. componentWillReceiveProps should only (re)invoke cont` if the output has changed though.Giuseppe works as CTO for Hoppinger BV, a company focusing on web strategy, design, and development in Rotterdam (Netherlands). Hoppinger supports the development of the library with significant internal effort, and acts as beta user and corporate sponsor as part of its ongoing innovation strategy.
The github repository is also a great place to give feedback, and of course to participate!