Oaret NPM | npm.io

Oaret

Oaret is a library that allows you to embed observables into React Virtual DOM. Embedding observables into VDOM has the following benefits:

It allows you to use only functional components, because you can then use observables for managing state and ref for component lifetime, leading to more concise code.
It helps you to use React in an algorithmically efficient way:
- The body of a functional component is evaluated only once each time the component is mounted.
  - This also helps you to avoid issues such as the gotcha with ref.
- Only elements that contain embedded observables are rerendered when changes are pushed through observables. An update to a deeply nested VDOM element can be an O(1) operation.

Using Oaret couldn't be simpler. You just import * as React from "oaret" and you are good to go.

Tutorial

To use Oaret, you simply import it as React:

import * as React from "oaret"

and you can then write React components:

const oncePerSecond = Kefir.interval(1000).toProperty(() => {})

const Clock = () =>
  <div>
    The time is {oncePerSecond.map(() => new Date().toString())}.
  </div>

with VDOM that can have embedded Kefir observables. This works because Oaret exports an enhanced version of createElement.

NOTE: Oaret does not pass through other named React exports. Only createElement is exported, which is all that is needed for basic use of VDOM or the Babel JSX transform.

NOTE: The result, like the Clock above, is just a React component. If you export it, you can use it just like any other React component and even in modules that do not import oaret.

Reference

≡ `oaret-lift` attribute

Oaret only lifts built-in HTML elements implicitly. The oaret-lift attribute on a non-primitive element instructs Oaret to lift the element.

For example, you could write:

import * as RR    from "react-router"
import * as React from "oaret"

const Link1 = ({...props}) => <RR.Link oaret-lift {...props}/>

to be able to use Link1 with embedded Kefir observables:

<Link1 href="https://www.youtube.com/watch?v=Rbm6GXllBiw"
       ref={elem => elem && elem.focus()}>
  {Kefir.sequentially(1000, [3, 2, 1, "Boom!"])}
</Link1>

Note that the ref attribute is only there as an example to contrast with $$ref.

≡ `fromClass(Component)`

fromClass allows one to lift a React component.

For example:

import * as RR from "react-router"
import {fromClass} from "oaret"

const Link2 = fromClass(RR.Link)

WARNING: A difficulty with lifting components is that you will then need to use the $$ref attribute, which is not necessary when using oaret-lift to lift an element.

≡ `$$ref` attribute

The $$ref attribute on an element whose component is lifted using fromClass

<Link2 href="https://www.youtube.com/watch?v=Rbm6GXllBiw"
       $$ref={elem => elem && elem.focus()}>
  {Kefir.sequentially(1000, [3, 2, 1, "Boom!"])}
</Link2>

does the same thing as the ordinary JSX ref attribute: JSX/React treats ref as a special case and it is not passed to components, so a special name had to be introduced for it.