@airma/react-state

@airma/react-state

@airma/react-state is a simple reducer tool, you can use it to replace useReducer, if you want more functions like state synchronization and asynchronous request manage, you can try use-agent-reducer.

@airma/react-state works like that:

import React from 'react';
import {render} from 'react-dom'
import {useModel} from '@airma/react-state';

function App(){
    const {count, increase, decrease} = useModel((state:number)=>{
        const baseState = state >= 0? state : 0;
        return {
            count: baseState,
            increase(){
                return baseState + 1;
            },
            decrease(){
                return baseState - 1;
            }
        };
    },0);
    return (
        <div>
            <button onClick={decrease}>-</button>
            <span>{count}</span>
            <button onClick={increase}>+</button>
        </div>
    );
}

render(<App/>, document.getElementById('root'));

It calls the model generate function when component is mounting or the model method has been called everytime.

The example above shows how to use API to manage a step counting model. We call increase method to generate a next state, then useModel update this state by recall model generator again.

So, the state change flow of increase is like this:

// model function
const model = (state:number)=>{...};

// increase returns
const state = baseState + 1;
// recall model with what increase returns
return model(state);

Yes, it is close with useReducer, but more free for usage. It looks like agent-reducer too, but it support dynamic closure function style, and it is simple enough.

Try not use async methods, @airma/react-state will not support that, the target of @airma/react-state is supporting react local state manage. We will support transform state from side effect like async request in other ways.

API

useModel

• model - model generate function, it accepts a state param, and returns a model object, which contains methods for generating next state and any other properties for describing state.
• state - this is the default state for model initialization.
• option - this is an optional param, you can set it {refresh: true} to make param state change always affect current model as a new state. There is a more easy API useRefreshModel

returns modelInstance which is generated by calling model(state). Everytime when a method from modelInstance is called, the result of this method is treated as a next state param, and recalls model(state) to refresh modelInstance.

type AirModelInstance = Record<string, any>;

type AirReducer<S, T extends AirModelInstance> = (state:S)=>T;

function useModel<S, T extends AirModelInstance, D extends S>(
    model: AirReducer<S, T>,
    state: D,
    option?: {refresh:boolean}
): T

useTupleModel

• model - model generate function, it accepts a state param, and returns a model object, which contains methods for generating next state and any other properties for describing state.
• state - this is the default state for model initialization.
• onChangeOrOption - this is an optional param. If it is a callback, useTupleModel goes to a controlled mode, it only accepts state change, and uses onChange callback to change next state out, you can use useControlledModel to do this too. If it is an option config, you can set {refresh: true} to make param state change always affect current model as a new state.

returns the current param state and modelInstance, like [state, instance].

type AirModelInstance = Record<string, any>;

type AirReducer<S, T extends AirModelInstance> = (state:S)=>T;

function useTupleModel<S, T extends AirModelInstance, D extends S>(
    model: AirReducer<S, T>,
    state: D,
    onChangeOrOption?: ((s:S)=>any)|{refresh:boolean}
): [S, T]

With this api, you can split state and methods like:

const [count, {increase, decrease}] = useTupleModel((state:number)=>{
    return {
        increase(){
            return state + 1;
        },
        decrease(){
            return state - 1;
        }
    };
},0);

useControlledModel

• model - model generate function, it accepts a state param, and returns a model object, which contains methods for generating next state and any other properties for describing state.
• state - this is the state for model, model can only update this state by onChange callback.
• onChange - this is a callback for updating state to an outside state management, like useState API.

type AirModelInstance = Record<string, any>;

type AirReducer<S, T extends AirModelInstance> = (state:S)=>T;

function useControlledModel<
  S,
  T extends AirModelInstance,
  D extends S
>(model: AirReducer<S, T>, state: D, onChange: (s: S) => any): T

With this API, you can use your model function more free, and more reusable. This API is against useModel, useModel maintains state inside a model system, useControlledModel is always controlled by input value, onChange interfaces.

// model.ts
export const counter = (count:number)=>{
    return {
        count,
        increase(){
            return count + 1;
        },
        decrease(){
            return count - 1;
        }
    };
};

//......

// component.ts
import {useControlledModel} from '@airma/react-state';
import {counter} from './model';

const MyComp = ({
  value, 
  onChange
  }:{
    value:number, 
    onChange:(v:number)=>void
  })=>{
  const {
    count, 
    increase, 
    decrease
  } = useControlledModel(counter, value, onChange);
  return ...... 
}

function App(){
  const [value, setValue] = useState<number>(0);

  return (
    <div>
      <MyComp value={value} onChange={setValue}/>
      <div>{value}</div>
    </div>
  );
}

useRefreshModel

• model - model generate function, it accepts a state param, and returns a model object, which contains methods for generating next state and any other properties for describing state.
• state - this is the state outside for model. When this param changes, the model refreshes with it as a new state.

returns a model instance like useModel, but can be refreshed by state param too.

export function useRefreshModel<S, T extends AirModelInstance, D extends S>(
  model: AirReducer<S, T>,
  state: D
): T;

Tips

The state property of model object is not necessary, it can be ignored, you can have some properties as you wish.

import React from 'react';
import {render} from 'react-dom'
import {useModel} from '@airma/react-state';

function App(){
    const {count, isNegative, increase, decrease} = useModel((state:number)=>{
    return {
      count: state,
      isNegative: state<0,
      increase(){
        return state + 1;
      },
      decrease(){
        return state - 1;
      }
    };
  },0);

  return (
    <div>
      <div>react state ex 1</div>
      <div>
        <button onClick={decrease}>-</button>
          <span style={isNegative?{color:'red'}:undefined}>{count}</span>
        <button onClick={increase}>+</button>
      </div>
    </div>
  );
}

render(<App/>, document.getElementById('root'));

As we can see it is very easy to describe state properties for usage.

Persistent methods

The methods from useModel returns is persistent, so, you can pass it to a memo component directly, it can improve your app performance.

Update data out of model function

Yes, the methods are persistent, but the model function still can work with the data out of model when the model function is triggered by methods. They can be updated into model in time.

Secure reduce state

The API from useTupleModel(without onChange) like useModel, useRefreshModel are secure for state update. The state is outside of react system, so every update from methods is a secure reducing process. If you want to use useState to replace its job, you have to call it like: setState((s)=>s+1).

typescript check

@airma/react-state is a typescript support library, you can use it with typescript for a better experience.

It checks if the input state type is same with the param default state type.

If the method returning type is same with param default state type, and so on.

End

We hope you can enjoy this tool, and help us to enhance it in future.