react-use-mutator

A React hook for inspecting and mutating shared state without subscribing to render updates.

🚀 Getting Started

Using npm:

npm install --save react-use-mutator

Using yarn:

yarn add react-use-mutator

🤔 What is this for?

Some applications depend on useState to manage a value which can be both consumed by and written to by many children, but because of the way React updates your components, their changes have the chance to overwrite or not reflect upon previous changes since the last render.

Additionally, sometimes it is useful to interrogate the value of the state held by a hook, without necessarily wanting to subscribe to those changes.

react-use-mutator enables us to both predictably update shared state, and inspect the current value of that state.

✍️ Example

In this example, we render 5000 children who all have shared access to the global state, who on mount, all attempt to register their unique identifier. Without using mutations, printing to the console in our useLayoutEffect hook would have a the contents of a single child key, since all children effectively complete to register against the initial, empty state.

By contrast, useMutator allows us to register all 5000 children safely, without an insane amount of render updates. This takes just a single render operation!

import React, { useContext, useEffect, useLayoutEffect } from 'react';
import uuidv4 from 'uuid/v4';
import { Map } from 'immutable';
import { useMutator } from 'react-use-mutator';

const StateContext = React.createContext();
const MutatorContext = React.createContext();

const Child = ({ ...extraProps }) => {
  // XXX: Registers this child to the currently mounted
  //      value of the StateContext in the DOM.
  const currentState = useContext(StateContext)();
  const mutateState = useContext(MutatorContext);
  const [ myId ] = useState(
    () => uuidv4(),
  );
  useEffect(
    () => {
      mutateState(
        currentState => currentState
          .set(myId, true),
      );
    },
    [],
  );
  return null;
};

export default () => {
  const [ useMutations, mutate ] = useMutator(
    () => Map({}),
  );
  useLayoutEffect(
    // XXX: The current value of the state can be used any times by calling mutate().
    //      (mutate()) normally inspects a mutation function, but if this is not provided,
    //      it returns early with the current state.
    () => console.log(JSON.stringify(mutate()));
  );
  return (
    <MutatorContext.Provider
      value={mutate}
    >
      <StateContext
        value={useMutations}
      >
        {[...Array(5000)]   
          .map(
            (_, i) => (
              <Child
                key={i}
              />
            ),
          )}
      </StateContext>
    </MutatorContext.Provider>
  );
};

✌️ License

MIT