/react-state-events

Lift React state via events

Primary LanguageJavaScript

react-state-events

Lift React state via events

See a working demo

NPM

Breaking changes from version 1.x

  • StateEvents constructor now takes a value to initialize the class.
  • useStateEvents hook and Subscription class no longer pass an initial value, they will now receive the initial value or the last published value of the StateEvents instance.
  • This was made so the initial value is consistent across views.

Install

npm install --save react-state-events

What is this?

This is a collection of tools to help you lift React state.

  • StateEvents: a class to publish and subscribe to.
  • ExternalStateEvents: same as above, but can communicate without having the original instance (useful with micro-frontends).
  • useStateEvents: a hook to publish data and update your component when data arrives.
  • Subscription: a component that will update when data arrives.

How is it useful?

  • It allows you to decouple data handling from react components, in a pattern similar to MVC.
  • It lets you put all the data handling code in a single class, so it's easier to test and maintain.
  • It lets your React components be solely about user interface, so they're simpler to read
  • It lets you handle state in a modular way, so you may bring code to another project untouched, without having to worry about how it fits into the global state or component hierarchy.
  • It lets you control instances yourself, so you could have more than one and choose which instance gets passed to which component, without modifying the code that handles the data.
  • It does the above using very little code.

Using the StateEvents class

Advantages

  • Can be subscribed/published to
  • Can handle exceptions in the callback
  • High performance
  • Multiple instances do not clash
import { StateEvents } from 'react-state-events'

const events = new StateEvents(0);
events.subscribe((data)=>console.log(data));
events.publish(1);
events.publish(2);
events.unsubscribeAll();

Using the ExternalStateEvents class

Advantages

  • Can be subscribed/published to
  • Can cross micro-frontend boundaries
  • Instances with the same name share streams
import { ExternalStateEvents } from 'react-state-events'

const events = new StateEvents(0, 'myStreamName');
events.subscribe((data)=>console.log(data));
events.publish(1);
events.publish(2);
events.unsubscribeAll();

Using the useStateEvents hook

Advantages

  • you can subscribe to multiple state events
  • you get a function to update the state events
  • jsx is simpler
import React, {useState} from 'react'
import {useStateEvents} from 'react-state-events'

export default ({myEvents})=>{
    const [val,setVal] = useStateEvents(myEvents);
    return (
        <span>
            {val}
        </span>
    );
}

Using the Subscription component

Advantages

  • you can use it from a class component
import React, {useState, useEffect} from 'react'
import {Subscription} from 'react-rxjs-tools'

export default ({myEvents})=>
        <Subscription stateEvents={myEvents}>
            {(data)=>
                <span>
                    {data}
                </span>
            }
        </Subscription>

Handling callback errors

All methods allow for handling callback errors. If a handler throws an exception and a single suscriber has no error handling callback, processing will rethrow the exception at that point, so (while it's optional) it's recommended that you always register an error handler, like so:

useBehaviorSubject hook

const [val,setVal] = useStateEvents(myEvents, errorCallback);

BehaviorSubscription component

<Subscription stateEvents={myEvents} onError={errorCallback} >
  {...}
</Subscription>

In both cases, errorCallback should be a function that takes a single argument for the error.

How do I lift state using react-state-events?

Using a combination of react-state-events and the Context API:

  • Create a controller class (not a React component!) that keeps state and a StateEvents instance.
  • Implement a method in the controller that returns the StateEvents instance, so components can subscribe to it. Have more instances if they need to update independently.
  • Implement methods in the controller that change the state and publish it
  • Create a context object to hold the instance (or instances!) of the controller.
  • In your components, get the controller instance from the context and use the hook or class to handle the subscription and notify the component of updates.

CounterController.js

import { StateEvents } from 'react-state-events'

export default class CounterController {
    constructor() {
        this.counterEvents = new StateEvents(0);
        this.counter = 0;
    }

    getCounterEvents() {
        return this.counterEvents;
    }

    increment() {
        this.counter++;
        this.counterEvents.publish(this.counter);
    }
}

counterContext.js

import { createContext } from 'react';
import CounterController from '../Controller/CounterController';

const counterContext = createContext(new CounterController());

export { counterContext };

counterView.js

import React, { useState, useContext } from 'react';
import { useStateEvents } from 'react-state-events';
import { counterContext } from '../Context/counterContext';

export default (props)=>{
  const counterController = useContext(counterContext);
  const [counter] = useStateEvents(Controller.getfilteredItemsEvents());
  const increment = ()=>counterController.increment();
  return (
    <div>
      <button onClick={increment}>{counter}</button>
    </div>
  )
}

When clicking the button

  • The controller's increment method will increment the counter in the state and publish.
  • The useStateEvents hook will get a notification of that subscription and trigger a render.
  • All instances of the component will be redrawn with the new counter.

Try adding more instances of the counter in the context, or even in a new context!

How do I share state across micro-frontends using react-state-events?

You don't need the context API, just use ExternalStateEvents in place of StateEvents and remember the event stream name parameter. External event streams are global, so it identifies the stream across ALL your application, ACROSS micro-frontends.

  • Create one ExternalStateEvents in micro-frontend A, use the useStateEvents hook with it.
  • Create one ExternalStateEvents in micro-frontend B with the same name you used in A and use the useStateEvents with it.
  • Make sure the ExternalStateEvents object is not being destroyed with every render! This causes multiple problems. Context API works here (as shown above), but passing an instance as a prop to the controlled component is also enough.
  • If you change the state in A, B will update with the value (and vice-versa).
  • A and B can be host/application or siblings, they will still communicate.
  • This is achieved using asynchronous messages, so performance is lower than StateEvents.

How do I share state with micro-frontends written in a different framework?

You can communicate with other frameworks by sending/handling messages in the proper format:

window.postMessage({
    type: "react-state-event",
    name: streamName,
    success: success,
    payload: data
}, window.origin);

Where:

  • type is always "react-state-event".
  • name is the global name of the stream.
  • success is true for success, false for error (which triggers registered error handlers).
  • payload is the state that will be sent in the event.

Is lifting state using ExternalStateEvents safer than using LocalStorage?

  • Messages are scoped to the window that emitted them.
  • Any Javascript running in the same window will see the passing messages, so it's vulnerable to XSS just like LocalStorage.
  • Messages are NOT stored (as in LocalStorage), so once the event is handled, an XSS attack cannot retrieve it anymore.
  • Messages can be sent to and received from the window through the javascript console

License

MIT © IndianaGeorge