@sethwebster/simple-state

React Simple State

Simple, global, high-performance state management for React.

...
import {useQuark} from '@sethwebster/simple-state';

function ComponentA() {
  const [ value, useQuark ] = useQuark('some-thing', 0);

  return (
    <div>
      <p>Value: {value}</p>
    </div>
  )
}

function ComponentB() {
  // Default value is ignored when declared a second time
  const [ value, useQuark ] = useQuark('some-thing', 0);

  return (
    <div>
      <p>Value: {value}</p>
      <button onClick={() => useQuark(value + 1)}>Increment</button>
    </div>
  )
}
...

Installation

npm i @sethwebster/simple-state

Usage

There are two primary apis:

• useQuark - A hook that returns a value and a setter function
• useDerivedQuark - A hook that returns a derived value based on other quark(s).

State is shared globally, but you can segment your data by using a context, <SimpleStateRoot>. This is useful if your data model organized in such a way that some is global to the whole app, and some is shared amongst a sub-section.

import { SimpleStateRoot } from '@sethwebster/simple-state';

function Products() {
  const products = getProducts();
  const [selectedProduct, setSelectedProduct] = useQuark('selected-product', products[0]);

  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>
          <button onClick={() => setSelectedProduct(product)}>{product.name}</button>
        </li>
      ))}
    </ul>
  )
}

function Nav() {
  const [selectedTab, setSelectedTab] = useQuark("selected-tab", "products");
}

function App() {
  return (
    {/* The state here is separate from that state within the <SimpleStateRoot /> below */}
    <Header>
      <Nav selectedTab={selectedTab} />
    </Header>
    {/* new state context */}
    <SimpleStateRoot>
      <Products />
    </SimpleStateRoot>
  )
}

API

useQuark

const [value, setValue] = useQuark<T>(key: string, initialValue: T): [T, (newValue: T) => void]

This hook is strongly typed and returns a value and a setter function. The setter function is memoized, so it can be passed to child components without causing unnecessary re-renders if desired. However, this is not strictly necessary as it's all the same shared state.

parameter	type	notes
T	type	(optional) Supply the type of data to store
key	string	Supply the globally unique key for this data. Any other invocations of `useQuark` will refer to the same state, and return the same value.
initialValue	(optional) T	The inital value to store.

useDerivedQuark

const value = useDerivedQuark<T>(
   key: string, 
   selector: (({get: (key: string): ?}) => T)
): T

This hook is strongly typed and returns a value derived using the selector function.

import { useQuark, useDerivedQuark } from '@sethwebster/simples-state';

function ComponentA() {
  const [value, setValue] = useQuark('some-thing', 10);
  const [otherValue, setOtherValue] = useQuark('some-other-thing', 15);

  // Update the values in some way
  useEffect(()=>{
    const interval = setInterval(() => {
      setValue(value + 5);
      setOtherValue(otherValue + 10);
    }, 1000)
  },[]);

  ...
}

function DerivedComponentB() {
  const value = useDerivedQuark('some-key-derived', ({get}) => {

    // Run when either value changes, and this component re-renders
    const someThing = get<number>('some-thing');
    const someOtherThing = get<number>('some-other-thing');

    return someThing * someOtherThing;
  })  
  
  return <div>{value}</div>
}
// 0s
// <div>150</div>
// 1s
// <div>375</div>
...

parameter	type	notes
T	(optional) return type	(optional) Supply the type of data to return
key	string	Supply the globally unique key for this derived data. Any other invocations of `useDerivedQuark` will refer to the same item, and will not overwrite the selector.
selector	<TReturn>({get<T>: (key: string) => T}) => TReturn	A selector. This selector is called with a `get` function that can be used to retrieve other quarks. When a quark is retrieved, the selector will be re-run when that quark changes. The selector should return a value of type `TReturn`.

License: MIT