react-cognito-auth v1.0.0

react-quantum-state

A flexible React state-management library based on Hooks. Manage complex application state with simple setup and access state with a single function from within your functional components.

Manage simple global state

For manageing simple global state, we use the quantumState method.

import { quantumState } from 'react-quantum-state'

The quantumState method takes 3 properties:

interface quantumStateProps {
  id: string,
  initialValue?: any,
  returnValue?: boolean
}

• id: unique identifier to reference the according global state
• initialState (optional): sets the initial state. The initial state needs to be set once otherwise it will be set to null. If the state has been initialized before, every initialValue property will be ignored
• returnValue (optional): option to disable the returned value. This is ment for components that should update states, but should not receive updated state in order to not rerender.

Simple usage:

// a component that initializes, updates and displays the global state
const StateManager = () => { 
  const [count, setCount] = quantumState({ id: "counter", initialValue: 0 })
  
  return (
    <div>
      <button onClick={() => setCount(count + 1)}>
        Increment
      </button>
      <button onClick={() => setCount(count - 1)}>
        Decrement
      </button>
      <p>
        Current count is: {count}
      </p>
    </div>
  )
}

// a component that only sets state and doesnt rerender on updated state
const StateSetter = () => { 
  const [_, setCount] = quantumState({ id: "counter", returnValue: false })
  
  return (
    <div>
      <button onClick={() => setCount(count + 1)}>
        Increment
      </button>
      <button onClick={() => setCount(count - 1)}>
        Decrement
      </button>
    </div>
  )
}

// a component that only displays the global state
const StateObserver = () => {
  const [count] = quantumState({ id: "counter" })
  
  return (
    <div>
      <p>
        Current count is: {count}
      </p>
    </div>
  )
}

By referencing the global state value by a given unique id, you can have components communicate and exchange state with a single function.

Set simple global state from outside your components

For this case we can use the setQuantumValue method

 import { setQuantumValue } from 'react-quantum-state'
 
 const resetCounter = () => setQuantumValue("counter", 0)
 
 // this component sets the global state for "counter" to 0
 const StateResetter = () => ( 
  <div>
    <button onClick={() => resetCounter()}>
      Reset
    </button>
  </div>
)

Managing state from within and from without components gives you flexibility to integrate your state management with everything in your application.

Manage complex global state

For manageing complex global state, we use the quantumReducer method that supports Redux-like functionality.

A simple usage within a functional component will look like this:

import { quantumReducer } from 'react-quantum-state'

// at this point we assume that our reducer contains a state object with { firstName, lastName, age, edits }
// everytime we edit the properties of the object, the edits counter will be incremented

const ComplexStateManager = () => {
  const { state, dispatch } = quantumReducer({ id: "infos" })
  
  const {
    firstName,
    lastName,
    age,
    edits
  } = state
  
  return (
    <div>
      <h4>
        You have edited the data: {edits} times
      </h4>
      <input 
        type="text" 
        value={firstName} 
        onChange={({ target: { value } }) => 
          dispatch({ type: "changeAttribute", payload: { attribute: "firstName", value }})
        }/>
      <input 
        type="text" 
        value={lastName} 
        onChange={({ target: { value } }) => 
          dispatch({ type: "changeAttribute", payload: { attribute: "lastName", value }})
        }/>
      <input 
        type="number" 
        value={age} 
        onChange={({ target: { value } }) => 
          dispatch({ type: "changeAttribute", payload: { attribute: "age", value }})
        }/>
    </div>
  )
}

So far we can see how simple it is to interact with a global reducer and its associated state

At this point we still need to define out reducer and set up our global store that manages that reducer.

For this example the reducer will look like this:

 const reducer = (
  state,
  action
) => {
  switch (action.type) {
    case "changeAttribute":
      return {
        ...state,
        [action.data.attribute]: action.data.value,
        edits: state.edits + 1
      }
    default:
      return state
  }
};

so far there is nothing special to this reducer, this is a simple basic reducer as we know it from Redux.

Before we can access a stores state, we need to initialize it.

To initialize global stores with reducers we use the initializeStores method

import { initializeStores } from 'react-quantum-state'

The initializeStores method takes an array with store configurations. You can initialize as many stores as you want to. Each store will be treated as a single state object. In contrast to Redux, a dispatched action will only be emitted to that stores reducer and will not effect any other stores.

To store has the following properties

interface StoreProperties {
    id: string,
    reducer: Function,
    initialState: any
}

Taking the above defined reducer, we can initiate a store like this:

initializeStores([
  {
    id: "infos",
    reducer, // as defined above
    initialState: {
      firstName: "",
      lastName: "",
      age: 0,
      edits
    }
  }
])

At this point we have defined a store, passed a reducer with initial state and accessed that state from within a component

For flexible state management we can also interact with our stores from outside a components

for this we will use the dispatchToStore method

import { dispatchToStore } from 'react-quantum-state'

const resetEdits = () => dispatchToStore({ id: "infos", action: { type: "changeAttribute": { data: { attribute: "edits", value: 0 } } } })
// call from outside component
resetEdits()

// or call from within component
const ResetEdits = () => {

  return (
    <div>
      <button onClick={() => resetEdits()}>
        Reset Edits Count
      </button>
    </div>
  )
}

No we are able to manage simple and complex state from within and from outside components! Awesome :)