✋Deprecated!!!

This project has been renamed to react-final-state and managed in a github organization.

Please move to https://github.com/final-state/react-final-state

For npm packages, please see: https://www.npmjs.com/package/react-final-state

react-deadly-simple-state

deadly-simple-state for react

Installation

yarn add deadly-simple-state
yarn add react-deadly-simple-state
# or
npm install deadly-simple-state
npm install react-deadly-simple-state

Quick Start

Prepare store instance

You can instantiate the store instance anywhere and export it out for use.

// file: YOUR_PATH/store.js

const initialState = {};
export const store = new Store(initialState);
// or if you have no other exports:
// export default new Store(initialState);

You may want to use multiple store in your app, that's fine, just create multiple store instances and export them out:

// file: YOUR_PATH/store.js

const fooInitialState = {};
export const fooStore = new Store(fooInitialState);

const barInitialState = {};
export const barStore = new Store(barInitialState);

How to track state

Let's see a raw way to use react-deadly-simple-state first. You can jump to deadly-simple way directly. But I really recommand you to read this raw way now or later to get a deeper understanding.

raw way:

import React, { useState, useEffect } from 'react';
import { store } from '<YOUR_PATH>/store';

/* Assume your state object is
{
  a: 1,
  b: 'good',
}
*/
// React component
export default function MyComponent() {
  // Define a local state to save the state that you want to track.
  const [a, setA] = useState(store.getState().a);
  // Subscribe the changes of store, and update `someState`
  useEffect(() => {
    // Define a listener, each time the state in store changed, it will be triggered.
    function listener() {
      const { a: nextA } = store.getState();
      setA(nextA);
    }
    // Do subscribe
    store.subscribe(listener);
    // Don't forget to unSubscribe
    return () => {
      store.unSubscribe(listener);
    };
  }, []);

  return <h1>{a}</h1>;
}

Looks complicated!!!😞😞😞But obviously, you can create a custom hook to save your life.

And react-deadly-simple-state did it for you!😃😃😃

deadly-simple way:

import React from 'react';
import { useCriteria } from 'react-deadly-simple-state';
import { store } from '<YOUR_PATH>/store';

/* Assume your state object is
{
  a: 1,
  b: 'good',
}
*/
// React component
export default function MyComponent() {
  const a = useCriteria(store, 'a');

  return <h1>{a}</h1>;
}

Just one line, cool? Check useCriteria for more information.

How to alter state

import { store } from '<YOUR_PATH>/store';

/* Assume your state object is
{
  a: 1,
  b: 'good',
}
*/

// Define an action to alter state
// `draftState` is a draft of your state
const incrementAction = (draftState) => {
  draftState.a = draftState.a + 1;
};

// React component
function MyComponent() {
  useEffect(() => {
    // Dispatch action to alter state
    // This is a side effect!
    store.dispatch(incrementAction);
  }, []);
  return *JSX*;
}

More details about dispatch and action, please see Store#dispatch.

Demo with typescript

See https://github.com/liyuanqiu/deadly-simple-state/tree/master/demo

API Reference

useCriteria

Important Note:

If you use useCriteria, your state must be a plain object. Continue reading for more details.

import { useCriteria } from 'react-deadly-simple-state';

useCriteria is a react hook that helps you to get a deep branch's value from the state object.

// Example
const a = useCriteria(store, 'a');

The signature of useCriteria:

// store is the instance of Store
useCriteria(store, path)

It's inner implementation is:

// `state` is the state object in the store
lodash.get(state, path);

So the path can be:

path = 'a[0].b.c';
path = 'a.b.c';
path = 'a[0][1][2].b.c';
// See https://lodash.com/docs/4.17.11#get for more detail about `path`.

If your path is invalid or not existing, you'll get a undefined from useCriteria.

useSubscription

import { useSubscription } from 'react-deadly-simple-state';

useSubscription is a react hook that helps you to subscribe the changes of state and automatically manages the lifecycle of a subscription.

Usually you can use useCriteria instead, only for those special cases you can give useSubscription a try.

// Example
const listener = React.useCallback(...);
// store is the instance of Store
useSubscription(store, listener);

Test

This project uses jest to perform testing.

yarn test