@aptuitiv/use-simple-reducer
TypeScript icon, indicating that this package has built-in type declarations

0.0.8 • Public • Published

use-simple-reducer

Build Version Types Size Dependencies Pull Requests welcome

useSimpleReducer is a simple async state mechanism for ReactJS. It's designed to be used for managing service state data and result in easy-to-test reducer methods.

Need help or have questions?

This project is supported by Bitovi, an end-to-end JavaScript consultancy specializing in React. You can get help or ask questions on our:

Or, you can hire us for training, consulting, or development. Set up a free consultation.

Table of Contents

Install

npm i @bitovi/use-simple-reducer

The Hook

Use

In your component, call useSimpleReducer with:

Field Type Purpose
initialState any The initial state you want to manage.
actions {[key: string]: (state: any, payload: any) => any} A collection of reducer methods, each to be called with thestate as the first argument and values passed to the action method as the second argument. If you are unfamiliar with the reducer pattern you can check out the redux reducer.
function Counter() {
  const [state, actions, queue, error] = useSimpleReducer(
    // initial state
    { count: 0 },
    // collection of reducer methods
    {
      async add(state: CounterState, amountToAdd: number) {
        await updateCountOnServer(state.count + amountToAdd)
        return { ...state, count: state.count + amountToAdd }
      },
      async subtract(state: CounterState, amountToSubtract: number) {
        await updateCountOnServer(state.count - amountToSubtract)
        return { ...state, count: state.count - amountToSubtract }
      },
    },
  )
}

useSimpleReducer returns:

Field Type Purpose
state {[key: string]: any} The latest state. This will initially return the initial state value, then it will return the values returned by the reducer methods.
queue { isActive: boolean, pendingAction: ActionAndArgs[], runningAction : ActionAndArgs} The queue's state, whether it is still active and details of the running and pending actions in the queue.
actions {[key: string]: (arg: any) => void} An object of methods that can be used to update the state.
error Error | null An error that is returned if any of the actions fail, null if otherwise.

When the user interacts with the page, call the actions methods. For example, you might call actions.add and actions.subtract as follows:

return (
  <div>
    <button onClick={() => actions.add(2)}>Two Steps Forward</button>
    <button onClick={() => actions.subtract(1)}>One Step Back</button>
    <div>
      <p>Steps: {state.count}</p>
      <div>{queue.isActive ? <Loader /> : 'Processing completed'}</div>
    </div>
  </div>
)

The argument being passed to actions methods here actions.add(2) should match the type of the payload argument amountToAdd being passed to the reducer method async add (state, amountToAdd)

async add(state: CounterState, amountToAdd: number){
    return { ...state, count: state.count + amountToAdd };
}

The Queue

Any invoked reducer action gets added to a queue. The queue will then start processing those asynchrous actions in the same order they have been added. The isActive flag gets set to false once all actions has been processed.

Interface

Field Type Purpose
isActive boolean true if an async action is running, false if otherwise. This can be used to add loading, spinners or other UI elements to the page.
runningAction ActionAndArgs Details of the running action which include the action's name, method and arguments.
pendingActions ActionAndArgs[] An Array of details of the pending actions in the queue which include the actions' names, methods and arguments.

Error Handling

An error object gets returned if any of the reducer methods fails. The cause of the error, details of the failed action and some error handling methods are exposed as part of the object.

Use

    return (
        <div>
            <button onClick={()=> actions.add(2)}>Two Steps Forward</button>
            <button onClick={()=> actions.subtract(1)}>One Step Back</button>
            <div>
                <p>Steps: {state.count}</p>
                <div>{queue.isActive ? <Loader /> : "Processing completed"}</div>
            </div>
            {error && <AlertDialog content={error.reason} onConfirm={() => error.runFailedAction()} />}
        </div>
    );
}

Interface

The error could contain the following fields:

Field Type Purpose
reason any The cause of the error. This can be of any type depending on the error thrown.
failedAction ActionAndArgs Details of the failed action which include the action's name, method and arguments.
pendingActions ActionAndArgs[] An array of the details of the pending actions in the queue which include the actions' names, methods and arguments.
runFailedAction () => void An error recovery method to re-run the last failed action.
runPendingActions () => void An error recovery method to skip the failed action and only run the pending actions in the queue.
runAllActions () => void An error recovery method to re-run the failed action and all the pending actions in the queue.

Unless the user calls any of the error recovery methods listed above, a default behaviour of the queue is to clear the failed and pending actions in it once an error occurs.

Demonstration

CodeSandBox:

https://codesandbox.io/s/bitovi-use-simple-reducer--basic-91ywsu?file=/src/components/Counter/Counter.tsx

We want to hear from you.

Come chat with us about open source in our community Slack.

See what we're up to by following us on Twitter.

Readme

Keywords

none

Package Sidebar

Install

npm i @aptuitiv/use-simple-reducer

Weekly Downloads

6

Version

0.0.8

License

ISC

Unpacked Size

46.8 kB

Total Files

9

Last publish

Collaborators

  • erictompkins