React-event-boundary NPM

React event boundary

Simple and scalable event system for React projects.

Install

npm i -S react-event-boundary

Highlights

Build to work with existing React state management solutions.
Typescript and Flow type definitions included.

Usage

To use event boundary in your React project you first need to create one.

Boundary creator accepts a React context instance that will be used to pass dispatch function down through your React tree:

import { createEventBoundary } from "react-event-boundary";

const DispatchContext = React.createContext(event => {
  // Here you will be recieving all events dispatched
  // in your application. Use this handler, for example,
  // to log events into console.
  console.log(event);
});

const EventBoundary = createEventBoundary(DispatchContext);

That's it. Now you are able to set up boundaries in your project to handle events propagated through your application.

const Root = () => {
  const [rootCount, setRootCount] = React.useState(0);

  const handleEvent = React.useCallback(event => {
    if (event === "INC") {
      // Each time local boundary cathes "INC" event
      // dispatched from child tree root count will be
      // incremented.
      setRootCount(prev => prev + 1);
    }
  }, []);

  return (
    <EventBoundary handler={handleEvent}>
      <div>{rootCount}</div>
      <Button />
    </EventBoundary>
  );
};

const Button = () => {
  const dispatch = React.useContext(DispatchContext);

  const handleButtonClick = React.useCallback(() => {
    // Dispatched event will bubble up to the
    // highest event boundary you set. Along the
    // way event can trigger as many state mutations
    // as you want.
    dispatch("INC");
  }, [dispatch]);

  return <button onClick={handleButtonClick}>increment</button>;
};

Any event bubbles up to the highest boundary in your tree. Therefore it becomes easy to handle a single event at different levels. See the working example on a codesandox:

For complex state management scenarios you may want to replace React.useState() with React.useReducer(). It's straitforward to use this approach with event boudary:

const reducer = (state, event) => {
  switch (event) {
    case "INC":
      return {
        ...state,
        count: state.count + 1
      };
    default:
      return state;
  }
};

const initialState = {
  count: 0
};

const Root = () => {
  const [state, dispatch] = React.useReducer(reducer, initialState);

  // All events dispatched from child tree will be passed
  // directly to dispatch function.
  return (
    <EventBoundary handler={dispatch}>
      <div>{rootCount}</div>
      <Button />
    </EventBoundary>
  );
};

See the working example on a codesandox: