State

Is blazingly fast javascript library for managing reactive state.

Visit the docs website to learn more about how to use @xania/state in your project.

Getting started

1npm install @xania/state

1import { State } from "@xania/state"
2
3const a = new State(1);
4const b = a.map(x => x + 1);
5const c = a.map(x => x * 2);
6const d = a.bind(x => x % 2 === ? b : c);

Motivation

@xania/state is intended to be complementary to RxJS and is especially an alternative to BehaviorSubject and it's main goal to provide reactivity for the View library. RxJS is on the other hand better suited for handling events coming from view, e.g. for debounce, async, etc...

;

• Compatibility with RxJS, RxJS for events and scheduling, and xania for fine grained state.
• Side effects are hidden
• Side effects are idempotent
• (eventual) consistency between source state and observer state

fine-grained state

In realworld, a state is practically never isolated from other parts of the state. e.g. firstName can be represented by a state object but it is also part of the Employee state and the two and all there observers needs to be in sync. Most used pattern for updating firstName in other libraries use a coarse grained approach where the whole person updates is updates. Biggest disadvantage is that the handling of firstName gets entangled with the structure of Person, which also means that this affected by any changes in structure.

@xania/state provides a different pattern using fine-grained approach. @xania/state provides a prop method to create an isolated state object and uses (internal) operators to keep the parent en it's property in sync.

1const person = new State({
2  firstName: 'Ibrahim',
3});
4const firstName = person.prop('firstName');
5firstName.set('Ramy');
6
7console.log(person.get().firstName); // prints 'Ramy'

1. we can create rxjs observables from state objects

1import * as Rx from 'rxjs';
2
3const s = new State(1);
4const x = Rx.from(s);

2. And we can connect rxjs back to state objects

1const x = Rx.timer(0, 1000);
2const s = State.from(x);

Design and concepts

State objects encapsulate values and are responsible for synchronisation with derived state and derived state of derived state etc..

1new State(1).set(2);

Derived state

The are three core methods of creating a derived state.

• prop: property of a root object
• map: monadic map
• bind: monadic bind

State mutations

State mutation is done by calling set on root object. Derived states do not allow for direct mutations. Changes can only flow from root states with one exception, namely a property state mapped directly of a root state in which case we can guarantee consistency for all derived states.

Sync external mutations

Xania does not ignore the fact that we can mutate the state outside the formal set operation. That's where sync comes into play.

1const data = {
2  firstName: 'Ibrahim',
3};
4const person = new State(data);
5const firstName = state.prop('firstName');
6firstName.subscribe({
7  next(x) {
8    console.log('Hello, ', x);
9  },
10});
11// console output: Hello, Ibrahim
12
13// external mutation
14data.firstName = 'Ramy';
15sync(person);
16// console output: Hello, Ramy

To maintain

Diamond problem

Xania ensures correct order in which the updates are propagated in a single roundtrip. This is especially important in case of the known diamond problem.

live demo

Features:

• monadic state (map, bind)
• topological sorting
• asynchronuous data (in progress)
• scheduling (in progress)
• batching (in progress)