Hubfx Core (WIP)

Description

Reactive state management with RxJS.

Table of Contents

1. Installation
2. Core concepts
   1. Reactables
   2. Hub and Stores
   3. Effects
   4. Scoped Effects
   5. Flow & Containment
3. Examples
   1. Basic Counter
   2. Scoped Effects - Updating Todos
   3. Connecting Multiple Hubs - Event Prices
4. API
   1. Reactable
   2. RxBuilder
      1. RxConfig
   3. Other Interfaces
      1. Effect
      2. ScopedEffects
      3. Action
      4. Reducer
5. Testing
   1. Reactables

Installation

npm i @hub-fx/core

Core concepts

Prerequisite: Basic understanding of Redux and RxJS is helpful.

In this documentation the term stream will refer to an RxJS observable stream.

Reactables

Reactables (prefixed with Rx) are objects that encapulate all the logic required for state management. They expose a state$ observable and actions methods. Applications can subscribe to state$ to receive state changes and call action methods to trigger them.

import { RxCounter } from '@hub-fx/examples';

const counterReactable = RxCounter();

const { state$, actions: { increment, reset } } = counterReactable;

state$.subscribe(({ count }) => {
  // Update the count when state changes.
  document.getElementById('count').innerHTML = count;
});

// Bind click handlers
document.getElementById('increment').addEventListener('click', increment);
document.getElementById('reset').addEventListener('click', reset);

For a full example, see Basic Counter Example.

Hub and Stores

Reactables are composed of Hubs & Stores.

The Hub is responsible for dispatching actions to the store(s) registered to the hub. It is also responsible for handling side effects. The main stream that initiates all actions and effects is the dispatcher$

Effects

When initializing a hub we can declare effects. The hub can listen for various actions and perform side effects as needed. Stores that are registered to the hub will be listening to these effects as well the dispatcher$.

Scoped Effects

Scoped Effects are dynamically created streams scoped to a particular action & key combination when an action is dispatch.

Flow & Containment

Actions and logic flow through the App in one direction and are contained in their respective streams. This makes state updates more predictable and traceable during debugging.

Avoid tapping your streams. This prevents logic leaking from the stream(s).

• i.e do not tap stream A to trigger an action on stream B. Instead consider declaring stream A as a source for stream B so the dependency is explicit.

Examples

Basic Counter

Basic counter example. Button clicks dispatch actions to increment or reset the counter.

Basic Counter | Design Diagram | Try it out on StackBlitz. Choose your framework :-------------------------:|:-------------------------:|:-------------------------: | |

Scoped Effects - Updating Todos

Updating statuses of todo items shows scoped effects in action. An 'update todo' stream is created for each todo during update. Pending async calls in their respective stream are cancelled if a new request comes in with RxJS switchMap operator.

Todo Status Updates | Design Diagram | Try it out on StackBlitz. Choose your framework :-------------------------:|:-------------------------:|:-------------------------: | |

Connecting Multiple Hubs - Event Prices

This examples shows two sets of hubs & stores. The first set is responsible for updating state of the user controls. The second set fetches prices based on input from the first set.

Event Prices | Design Diagram | Try it out on StackBlitz. Choose your framework :-------------------------:|:-------------------------:|:-------------------------: | |

API

Reactable

Reactables provide the API for applications and UI components to receive and trigger state updates.

export interface Reactable<T, S = ActionMap> {
  state$: Observable<T>;
  actions?: S;
}

export interface ActionMap {
  [key: string | number]: (payload?: unknown) => void;
}

| Property | Description | | -------- | ----------- | | state$ | Observable that emit state changes | | actions (optional) | Dictionary of methods that dispatches actions to update state |

RxBuilder

RxBuilder factory help build Reactables. Accepts a RxConfig configuration object

type RxBuilder = <T, S extends Cases<T>>(config: RxConfig<T, S>) => Reactable<T, unknown>

RxConfig

Configuration object for creating Reactables.

interface RxConfig <T, S extends Cases<T>>{
  initialState: T;
  reducers: S;
  store?: boolean;
  debug?: boolean;
  effects?: Effect<unknown, unknown>[];
  sources?: Observable<Action<unknown>>[];
}

interface Cases<T> {
  [key: string]: SingleActionReducer<T, unknown>
    | {
        reducer: SingleActionReducer<T, unknown>
        effects?: (payload?: unknown) => ScopedEffects<unknown>
      };
}

type SingleActionReducer<T, S> = (state: T, action: Action<S>) => T;

| Property | Description | | -------- | ----------- | | initialState | Initial state of the Reactable | | reducers | Dictionary of cases for the Reactable to handle. Each case can be a reducer function or a configuration object. RxBuilder will use this to generate Actions, Reducers, and add ScopedEffects. | | debug (optional) | to turn on debugging to console.log all messages received by the store and state changes | | store (optional) | Option to store value if Reactable is used to persist application state. Subsequent subscriptions will received the latest stored value. Default to false | | effects (optional) | Array of Effects to be registered to the Reactable | | sources (optional) | Additional Action Observables the Reactable is listening to |

Debug Example:

Other Interfaces

Effect

Effects are expressed as RxJS Operator Functions. They pipe the dispatcher$ stream and run side effects on incoming Actions.

type Effect<T, S> = OperatorFunction<Action<T>, Action<S>>;

ScopedEffects

Scoped Effects are declared in Actions. They are dynamically created stream(s) scoped to an Action type & key combination.

interface ScopedEffects<T> {
  key?: string;
  effects: Effect<T, unknown>[];
}

| Property | Description | | -------- | ----------- | | key (optional) | key to be combined with the Action type to generate a unique signature for the effect stream(s). Example: An id for the entity the action is being performed on. | | effects | Array of Effects scoped to the Action type & key |

Example:

const UPDATE_TODO = 'UPDATE_TODO';
const UPDATE_TODO_SUCCESS = 'UPDATE_TODO_SUCCESS';
const updateTodo = ({ id, message }, todoService: TodoService) => ({
  type: UPDATE_TODO,
  payload: { id, message },
  scopedEffects: {
    key: id,
    effects: [
      (updateTodoActions$: Observable<Action<string>>) =>
        updateTodoActions$.pipe(
          mergeMap(({ payload: { id, message } }) => todoService.updateTodo(id, message))
          map(({ data }) => ({
            type: UPDATE_TODO_SUCCESS,
            payload: data
          }))
        )
    ]
  }
})

Action

interface Action<T = undefined> {
  type: string;
  payload?: T;
  scopedEffects?: ScopedEffects<T>;
}

| Property | Description | | -------- | ----------- | | type | type of Action being dispatched | | payload (optional) | payload associated with Action | | scopedEffects (optional) | See ScopedEffects |

Reducer

From Redux Docs

Reducers are functions that take the current state and an action as arguments, and return a new state result

type Reducer<T> = (state?: T, action?: Action<unknown>) => T;

Testing

We can use RxJS's built in Marble Testing for testing Reactables.

Reactables

// https://github.com/hub-fx/hub-fx/blob/main/packages/examples/src/Counter/Counter.test.ts
import { Counter } from './Counter';
import { Subscription } from 'rxjs';
import { TestScheduler } from 'rxjs/testing';

describe('Counter', () => {
  let testScheduler: TestScheduler;
  let subscription: Subscription;

  beforeEach(() => {
    testScheduler = new TestScheduler((actual, expected) => {
      expect(actual).toEqual(expected);
    });
  });
  afterEach(() => {
    subscription?.unsubscribe();
  });

  it('should increment and reset', () => {
    testScheduler.run(({ expectObservable, cold }) => {
      // Create Counter Reactable
      const {
        state$,
        actions: { increment, reset },
      } = Counter();

      // Call actions
      subscription = cold('--b-c', {
        b: increment,
        c: reset,
      }).subscribe((action) => action());

      // Assertions
      expectObservable(state$).toBe('a-b-c', {
        a: { count: 0 },
        b: { count: 1 },
        c: { count: 0 },
      });
    });
  });
});