realar

Realar

Multiparadigm state manager for React based on reactive mathematic.

Light, Fast, and Pretty looked :kissing_heart:

Realar targeted to clean code, modulable architecture, and time of delivery user experience.

Supported two kinds of data and logic definitions.

• Plain functional reactive programming with only functions

const [getCount, set] = box(0);

const tick = () => set(getCount() + 1);
setInterval(tick, 200);

const App = () => {
  const count = useValue(getCount);
  return (
    <p>{count}</p>
  )
}

Try on CodeSandbox

• And transparent functional reactive programming with classes, decorators and jsx wrapper

class Ticker {
  @prop count = 0
  tick = () => ++this.count;
}

const ticker = new Ticker();
setInterval(ticker.tick, 200);

const App = () => (
  <p>{ticker.count}</p>
)

Try wrapped version on CodeSandbox

Realar targeted to all scale applications up to complex enterprise solutions on microfrontends architecture.

You can use as many from Realar as you want. For small websites or theme switchers, two functions are enough:ok_hand: Step by step on applications scale stairs you can take more and more. From sharing state to all application parts, to modulable architecture with apps composition.

Abstraction

The abstraction of the core is an implementation of functional reactive programming on javascript and binding that with React.

It uses usual mathematic to describe dependencies and commutation between reactive values.

In contradistinction to stream pattern, operator functions not needed. The reactive “sum” operator used a simple “+” operator (for example).

const [getA, setA] = box(0)
const [getB, setB] = box(0)

const sum = () => getA() + getB()

on(sum, console.log)

That code has a graph of dependencies inside. “sum” - reactive expression depends from “A” and “B”, and will react if “A” or “B” changed. It is perfectly demonstrated with “on” function (that subscribes to reactive expression) and “console.log” (developer console output).

On each change of “A” or “B” a new value of that sum will appear in the developer console output.

And for tasty easy binding reactive expressions and values with React components.

const App = () => {
  const val = useValue(sum);
  return (
    <p>{val}</p>
  );
}

That component will be updated every time when new sum value is coming.

The difference from exists an implementation of functional reactive programming (mobx) in Realar dependency collector provides the possibility to write in selectors and nested writable reactions.

Realar provides big possibility abstractions for reactive flow. We already know about reactive value container, reactive expressions, and subscribe mechanism. But also have synchronization between data, cycled reactions, cached selectors, and transactions.

Below I will talk about high level abstractions provided from Realar out of the box.

• Shared instances decomposition. The pattern for decomposing applications logic to separate independent or one direction dependent modules. Each module can have its own set of reactive values. (ssr, comfort “mock” mechanism for simple unit testing)

• Actions are a necessary part of reactive communication, well knows for most javascript developers. Possibility for subscribing to action, call action, and wait for the next action value everywhere on the code base.

• React components context level scopes. Declaration one scope and use as many reactive value containers as you want no need to define a new React context for each changeable value.

• Decorators for clasess lovers. And babel plugin for automatic wrap all arrow functions defined in the global scope with JSX inside to observe wrapper for the total implementation of transparent functional reactive programming (TFRP) in javascript with React.

Classes usage

If you don't have an interest in classes or decorators, you can code in functional style with a wide and full feature API.

But if you like, it looks likes very clear and natively, and you can start development knows only two functions.

prop. Reactive value marker. Each reactive value has an immutable state. If the immutable state will update, all React components that depend on It will refresh.

shared. One of the primary reasons for using state manager in your application is a shared state accessing, and using shared logic between scattered React components and any place of your code.

import React from 'react';
import { prop, shared } from 'realar';

class Counter {
  @prop value = 0;

  inc = () => this.value += 1;
  dec = () => this.value -= 1;
}

const sharedCounter = () => shared(Counter);

const Count = () => {
  const { value } = sharedCounter();
  return <p>{value}</p>;
};

const Buttons = () => {
  const { inc, dec } = sharedCounter();
  return (
    <>
      <button onClick={inc}>+</button>
      <button onClick={dec}>-</button>
    </>
  );
};

const App = () => (
  <>
    <Count />
    <Buttons />
    <Count />
    <Buttons />
  </>
);

export default App;

For best possibilities use realar babel plugin, your code will be so beautiful to look like.

But otherwise necessary to wrap all React function components that use reactive values inside to observe wrapper. Try wrapped version on CodeSandbox.

Functional usage

import React from "react";
import { box, useValue } from "realar";

const [get, set] = box(0);

const next = () => get() + 1;

const inc = () => set(next());
const dec = () => set(get() - 1);

const Current = () => {
  const value = useValue(get);
  return <p>current: {value}</p>;
};

const Next = () => {
  const value = useValue(next);
  return <p>next: {value}</p>;
};

const App = () => (
  <>
    <Current />
    <Next />

    <button onClick={inc}>+</button>
    <button onClick={dec}>-</button>
  </>
);

export default App;

Try on CodeSandbox.

Actions

The action allows you to trigger an event and delivers the functionality to subscribe to it anywhere in your application code.

const add = action();

const [get, set] = box(1);
on(add, num => set(get() + num));

add(15);
console.log(get()); // 16

Edit on RunKit

An action is convenient to use as a promise.

const fire = action();

const listen = async () => {
  for (;;) {
    await fire; // await as a usual promise
    console.log('Fire');
  }
}

listen();
setInterval(fire, 500);

Edit on RunKit

Access visibility levels

The basic level of scopes for React developers is a component level scope (for example useState, and other standard React hooks has that level).

Every React component instance has its own local state, which is saved every render for the component as long as the component is mounted.

In the Realar ecosystem useLocal hook used to make components local state.

const CounterLogic = () => {

  const [get, set] = box(0);
  const inc = () => set(get() + 1);

  return sel(() => ({
    value: get(),
    inc
  }));
}

const Counter = () => {
  const { value, inc } = useLocal(CounterLogic);

  return (
    <p>{value} <button onClick={inc}>+</button></p>
  );
}

export const App = () => (
  <>
    <Counter />
    <Counter />
  </>
);

Play on CodeSandbox

Or If you coding in classes style:

class CounterLogic {
  @prop value = 0;
  inc = () => this.value += 1
}

const Counter = () => {
  const { value, inc } = useLocal(CounterLogic);

  return (
    <p>{value} <button onClick={inc}>+</button></p>
  );
}

Play wrapped on CodeSandbox

This feature can be useful for removing logic from the body of a component to keep that free of unnecessary code, and therefore cleaner.

Documentation

box

The first abstraction of Realar is reactive container - box. The box is a place where your store some data as an immutable struct. When you change box value (rewrite to a new immutable struct) all who depend on It will be updated synchronously.

For create new box we need box function from realar, and initial value that will store in reactive container. The call of box function returns array of two functions.

• The first is value getter.
• The second one is necessary for save new value to reactive container.

const [get, set] = box(0);

set(get() + 1);

console.log(get()); // 1

Edit on RunKit

In that example

• for a first we created box container for number with initial zero;
• After that, we got the box value, and set to box its value plus one;
• Let's print the result to the developer console, that will is one.

We learned how to create a box, set, and get its value.

on

The next basic abstraction is expression. Expression is a function that read reactive boxes or selectors. It can return value and write reactive boxes inside.

We can subscribe to change any reactive expression using on function (which also works with action).

const [get, set] = box(0);

const next = () => get() + 1;

on(next, (val, prev) => console.log(val, prev));

set(5); // We will see 6 and 1 in developer console output, It are new and previous value

Edit on RunKit

In that example expression is next function, because It get box value and return that plus one.

cycle

const [get, set] = box(0);

cycle(() => {
  console.log(get() + 1);
});

set(1);
set(2);

// In output of developer console will be 1, 2 and 3.

Edit on RunKit

• Takes a function as reactive expression.
• After each run: subscribe to all reactive boxes accessed while running
• Re-run on data changes

sync

const [getSource, setSource] = box(0);
const [getTarget, setTarget] = box(0);

sync(getSource, setTarget);
// same as sync(() => getSource(), val => setTarget(val));

setSource(10);

console.log(getTarget()) // 10

Edit on RunKit

Documentation not ready yet for sel, shared, effect, initial, mock, unmock, free, useValue, useShared, useScoped, Scope, observe, transaction, cache, prop functions. It's coming soon.

Demos

• Hello - shared state demonstration.
• Todos - todomvc implementation.
• Jest - unit test example.

Installation

npm install realar
# or
yarn add realar

If you like OOP update your babel config for support class decorators and using babel plugin for automatic observation arrow function components.

//.babelrc
{
  "plugins": [
    ["@babel/plugin-proposal-decorators", { "legacy": true }],
    ["@babel/plugin-proposal-class-properties", { "loose": true }],
    ["realar", {
      "include": [
        "src/components/*",
        "src/pages/*"
      ]
    }]
  ]
}

Enjoy and happy coding!