martineboh / easy-peasy Goto Github PK

Easy Peasy exports numerous types to help you declare your model correctly.

import { Action, Reducer, Thunk, Select } from 'easy-peasy'

interface TodosModel {
  items: Array<string>
  // represents a "select"
  firstItem: Select<TodosModel, string | void>
  // represents an "action"
  addTodo: Action<TodosModel, string>
}

interface UserModel {
  token?: string
  loggedIn: Action<UserModel, string>
  // represents a "thunk"
  login: Thunk<UserModel, { username: string; password: string }>
}

interface StoreModel {
  todos: TodosModel
  user: UserModel
  // represents a custom reducer
  counter: Reducer<number>
}

import { useStore, useActions, Actions, State } from 'easy-peasy';
import { StoreModel } from './your-store';

function MyComponent() {
  const token = useStore((state: State<StoreModel>) =>
    state.user.token
  )
  const login = useActions((actions: Actions<StoreModel>) =>
	  actions.user.login,
  )
  return (
    <button onClick={() => login({ username: 'foo', password: 'bar' })}>
      {token || 'Log in'}
    </button>
  )
}

The above can become a bit cumbersome - having to constantly provide your types to the hooks. Therefore we recommend using the bundled createTypedHooks helper in order to create pre-typed versions of the hooks.

// hooks.js

import { createTypedHooks } from "easy-peasy";
import { StoreModel } from "./model";

export default createTypedHooks<StoreModel>();

We could then revise our previous example.

import { useStore, useActions } from './hooks';

function MyComponent() {
  const token = useStore((state) => state.user.token)
  const login = useActions((actions) => actions.user.login)
  return (
    <button onClick={() => login({ username: 'foo', password: 'bar' })}>
      {token || 'Log in'}
    </button>
  )
}

That's far cleaner - and it's still fully type checked.

React Native, hybrid, desktop and server side Redux apps can use Redux Dev Tools using the [Remote Redux DevTools](https://github.com/zalmoxisus/remote-redux-devtools) library.

To use this library, you will need to pass the DevTools compose helper as part of the config object to createStore

import { createStore } from 'easy-peasy';
import { composeWithDevTools } from 'remote-redux-devtools';
import model from './model';

/**
 * model, is used for passing through the base model
 * the second argument takes an object for additional configuration
 */

const store = createStore(model, {
  compose: composeWithDevTools({ realtime: true, trace: true })
  // initialState: {}
});

export default store;

See https://github.com/zalmoxisus/remote-redux-devtools#parameters for all configuration options.

Actions are relatively simple to test as they are essentially an immutable update to the store. We can therefore test the difference.

Given the following model under test:

const todosModel = {
  items: {},
  add: (state, payload) => {
    state.items[payload.id] = payload
  },
}

We could test it like so:

test('add action', async () => {
  // arrange
  const todo = { id: 1, text: 'foo' }
  const store = createStore(todosModel)

  // act
  store.dispatch.add(todo)

  // assert
  expect(store.getState().items).toEqual({ [todo.id]: todo })
})

Thunks are more complicated to test than actions as they can invoke network requests and other actions.

There will likely be seperate tests for our actions, therefore it is recommended that you don't test for the state changes of actions fired by your thunk. We rather recommend that you test for what actions were fired from your thunk under test.

To do this we expose an additional configuration value on the createStore API, specifically mockActions. If you set the mockActions configuration value, then all actions that are dispatched will not affect state, and will instead be mocked and recorded. You can get access to the recorded actions via the getMockedActions function that is available on the store instance. We took inspiration for this functionality from the awesome redux-mock-store package.

In addition to this approach, if you perform side effects such as network requests within your thunks, we highly recommend that you expose the modules you use to do so via the injections configuration variable of your store. If you do this then it makes it significantly easier to provide mocked instances to your thunks when testing.

We will demonstrate all of the above within the below example.

Given the following model under test:

const todosModel = {
  items: {},
  add: (state, payload) => {
    state.items[payload.id] = payload
  },
  fetchById: thunk(async (actions, payload, helpers) => {
    const { injections } = helpers
    const todo = await injections.fetch(`/todos/${payload}`).then(r => r.json())
    actions.add(todo)
  }),
}

We could test it like so:

import { createStore, actionName, thunkStartName, thunkCompleteName } from 'easy-peasy'

const createFetchMock = response =>
  jest.fn(() => Promise.resolve({ json: () => Promise.resolve(response) }))

test('fetchById', async () => {
  // arrange
  const todo = { id: 1, text: 'Test my store' }
  const fetch = createFetchMock(todo)
  const store = createStore(todosModel, {
    injections: { fetch },
    mockActions: true,
  })

  // act
  await store.dispatch.fetchById(todo.id)

  // assert
  expect(fetch).toHaveBeenCalledWith(`/todos/${todo.id}`)
  expect(store.getMockedActions()).toEqual([
    { type: thunkStartName(todosModel.fetchById), payload: todo.id },
    { type: actionName(todosModel.add), payload: todo },
    { type: thunkCompleteName(todosModel.fetchById), payload: todo.id },
  ])
})

When testing your components I strongly recommend the approach recommended by Kent C. Dodd's awesome Testing Javascript course, where you try to test the behaviour of your components using a natural DOM API, rather than reaching into the internals of your components. He has published a very useful package by the name of react-testing-library to help us do so. The tests below shall be adopting this package and strategy.

Imagine we were trying to test the following component.

function Counter() {
  const count = useStore(state => state.count)
  const increment = useActions(actions => actions.increment)
  return (
    <div>
      Count: <span data-testid="count">{count}</span>
      <button type="button" onClick={increment}>
        +
      </button>
    </div>
  )
}

As you can see it is making use of our hooks to gain access to state and actions of our store.

We could adopt the following strategy to test it.

import { createStore, StoreProvider } from 'easy-peasy'

test('Counter', () => {
  // arrange
  const store = createStore({
    count: 0,
    increment: state => {
      state.count += 1
    },
  })

  const app = (
    <StoreProvider store={store}>
      <ComponentUnderTest />
    </StoreProvider>
  )

  // act
  const { getByTestId, getByText } = render(app)

  // assert
  expect(getByTestId('count').textContent).toEqual('0')

  // act
  fireEvent.click(getByText('+'))

  // assert
  expect(getByTestId('count').textContent).toEqual('1')
})

As you can see we create a store instance in the context of our test and wrap the component under test with the StoreProvider. This allows our component to act against our store.

We then interact with our component using the DOM API exposed by the render.

This grants us great power in being able to test our components with a great degree of confidence that they will behave as expected.

Some other strategies that you could employ whilst using this pattern include:

• Providing an initial state to your store within the test.

  test('Counter', () => {
    // arrange
    const store = createStore(model, { initialState: initialStateForTest })
  
    // ...
  })

• Utilising the injections and mockActions configurations of the createStore to avoid performing actions with side effects in your test.

There is no one way to test your components, but it is good to know of the tools available to you. However you choose to test your components, I do recommend that you try to test them as close to their real behaviour as possible - i.e. try your best to prevent implementation details leaking into your tests.

• model (Object, required)

  Your model representing your state tree, and optionally containing action functions.

• config (Object, not required)

  Provides custom configuration options for your store. It supports the following options:

  • compose (Function, not required, default=undefined)

    Custom compose function that will be used in place of the one from Redux or Redux Dev Tools. This is especially useful in the context of React Native and other environments. See the Usage with React Native notes.

  • devTools (bool, not required, default=true)

    Setting this to true will enable the Redux Dev Tools Extension.

  • disableInternalSelectFnMemoize (bool, not required, default=false)

    Setting this to true will disable the automatic memoisation of a fn that you may return in any of your select implementations. Please see the select documentation for more information.

  • initialState (Object, not required, default=undefined)

    Allows you to hydrate your store with initial state (for example state received from your server in a server rendering context).

  • injections (Any, not required, default=undefined)

    Any dependencies you would like to inject, making them available to your effect actions. They will become available as the 4th parameter to the effect handler. See the effect docs for more.

  • middleware (Array, not required, default=[])

    Any additional middleware you would like to attach to your Redux store.

  • mockActions (boolean, not required, default=false)

    Useful when testing your store, especially in the context of thunks. When set to true none of the actions dispatched will update the state, they will be instead recorded and can be accessed via the getMockedActions API that is added to the store. Please see the "Writing Tests" section for more information.

  • reducerEnhancer (Function, not required, default=(reducer => reducer))

    Any additional reducerEnhancer you would like to enhance to your root reducer (for example you want to use redux-persist).

When you have created a store all the standard APIs of a Redux Store are available. Please reference their docs for more information. In addition to the standard APIs, Easy Peasy enhances the instance to contain the following:

• dispatch (Function & Object, required)

  The Redux store dispatch behaves as normal, however, it also has the actions from your model directly mounted against it - allowing you to easily dispatch actions. Please see the docs on actions/thunks for examples.

• getMockedActions (Function, required)

  When the mockActions configuration value was passed to the createStore then calling this function will return the actions that have been dispatched (and mocked). This is useful in the context of testing - especially thunks.

• clearMockedActions (Function, required)

  When the mockActions configuration value was passed to the createStore then calling this function clears the list of mocked actions that have been tracked by the store. This is useful in the context of testing - especially thunks.

• state (Object, required)

  The part of the state tree that the action is against. You can mutate this state value directly as required by the action. Under the hood we convert these mutations into an update against the Redux store.

• payload (Any)

  The payload, if any, that was provided to the action.

When your model is processed by Easy Peasy to create your store all of your actions will be made available against the store's dispatch. They are mapped to the same path as they were defined in your model. You can then simply call the action functions providing any required payload. See the example below.

• action (Function, required)

  The thunk action definition. A thunk typically encapsulates side effects (e.g. calls to an API). It can be asynchronous - i.e. use Promises or async/await. Thunk actions cannot modify state directly, however, they can dispatch other actions to do so.

  It receives the following arguments:

  • actions (required)

    The actions that are bound to same section of your model as the thunk. This allows you to dispatch another action to update state for example.

  • payload (Any, not required)

    The payload, if any, that was provided to the action.

  • helpers (Object, required)

    Contains a set of helpers which may be useful in advanced cases. The object contains the following properties:

    • dispatch (required)

      The Redux store dispatch instance. This will have all the Easy Peasy actions bound to it allowing you to dispatch additional actions.

    • getState (Function, required)

      When executed it will provide the root state of your model. This can be useful in the cases where you require state in the execution of your effectful action.

    • injections (Any, not required, default=undefined)

      Any dependencies that were provided to the createStore configuration will be exposed as this argument. See the createStore docs on how to specify them.

    • meta (Object, required)

      This object contains meta information related to the effect. Specifically it contains the following properties:

      • parent (Array, string, required)

        An array representing the path of the parent to the action.

      • path (Array, string, required)

        An array representing the path to the action.

      This can be represented via the following example:

      const store = createStore({
        products: {
          fetchById: thunk((dispatch, payload, { meta }) => {
            console.log(meta);
            // {
            //   parent: ['products'],
            //   path: ['products', 'fetchById']
            // }
          })
        }
      });

When your model is processed by Easy Peasy to create your store all of your thunk actions will be made available against the store's dispatch. They are mapped to the same path as they were defined in your model. You can then simply call the action functions providing any required payload. See the examples below.

import { createStore, thunk } from 'easy-peasy';

const store = createStore({
  audit: {
    logs: [],
    add: (state, payload) => {
      audit.logs.push(payload);
    }
  },
  todos: {
    // dispatch allows you to gain access to the store's dispatch
    //                                      👇
    saveTodo: thunk((actions, payload, { dispatch }) => {
      // ...
      dispatch.audit.add('Added a todo');
    })
  }
});

store.dispatch.todos.saveTodo('foo');

We don't recommned doing this, and instead encourage you to use the listeners helper to invert responsibilites. However, there may be cases in which you need to do the above.

• fn (Function, required)

  The reducer function. It receives the following arguments.

  • state (Object, required)

    The current value of the property that the reducer was attached to.

  • action (Object, required)

    The action object, typically with the following shape.

    • type (string, required)

      The name of the action.

    • payload (any)

      Any payload that was provided to the action.

• selector (Function, required)

  The selector function responsible for resolving the derived state. It will be provided the following arguments:

  • state (Object, required)

    The local part of state that the select property was attached to.

  You can return any derived state you like.

  It also supports returning a function. This allows you to support creating a "dynamic" selector that accepts arguments (e.g. productById(1)). We will automatically optimise the function that you return - ensuring that any calls to the function will be automatically be memoised - i.e. calls to it with the same arguments will return cached results. This automatic memoisation of the function can be disabled via the disableInternalSelectFnMemoize setting on the createStore's config argument.

• dependencies (Array, not required)

  If this selector depends on data from other selectors then you should provide the respective selectors within an array to indicate the case. This allows us to make guarantees of execution order so that your state is derived in the manner you expect it to.

• on (Function, required)

  Allows you to attach a listener to an action. It expects the following arguments:

  • action (Function | string, required)

    The target action you wish to listen to - you provide the direct reference to the action, or the string name of it.

  • thunk (Function, required)

    The handler thunk to be executed after the target action is fired successfully. It has the same arguments and characteristics of a thunk action. Please refer to the thunk API documentation for more information.

    The only difference is that the payload argument will be the payload value that the action being listened to received.

• mapState (Function, required)

  The function that is used to resolved the piece of state that your component requires. The function will receive the following arguments:

  • state (Object, required)

    The root state of your store.

• externals (Array of any, not required)

  If your useStore function depends on an external value (for example a property of your component), then you should provide the respective value within this argument so that the useStore knows to remap your state when the respective externals change in value.

Your mapState can either resolve a single piece of state. If you wish to resolve multiple pieces of state then you can either call useStore multiple times, or if you like resolve an object within your mapState where each property of the object is a resolved piece of state (similar to the connect from react-redux). The examples will illustrate the various forms.

Please be careful in the manner that you resolve values from your mapToState. To optimise the rendering performance of your components we use equality checking (===) to determine if the mapped state has changed.

When an action changes the piece of state your mapState is resolving the equality check will break, which will cause your component to re-render with the new state.

Therefore deriving state within your mapState in a manner that will always produce a new value (for e.g. an array) is an anti-pattern as it will break our equality checks.

// ❗️ Using .map will produce a new array instance every time mapState is called
//                                                     👇
const productNames = useStore(state => state.products.map(x => x.name))

You have two options to solve the above.

Firstly, you could just return the products and then do the .map outside of your mapState:

const products = useStore(state => state.products)
const productNames = products.map(x => x.name)

Alternatively you could use the select helper to define derived state against your model itself.

import { select, createStore } from 'easy-peasy';

const createStore = ({
  products: [{ name: 'Boots' }],
  productNames: select(state => state.products.map(x => x.name))
});

Note, the same rule applies when you are using the object result form of mapState:

const { productNames, total } = useStore(state => ({
  productNames: state.products.map(x => x.name), // ❗️ new array every time
  total: state.basket.total
}));

• mapActions (Function, required)

  The function that is used to resolved the action(s) that your component requires. Your mapActions can either resolve single or multiple actions. The function will receive the following arguments:

  • actions (Object, required)

    The actions of your store.

• action (Function, required)

  The action function to execute the effects. It can be asynchronous, e.g. return a Promise or use async/await. Effectful actions cannot modify state, however, they can dispatch other actions providing fetched data for example in order to update the state.

  It accepts the following arguments:

  • dispatch (required)

    The Redux store dispatch instance. This will have all the Easy Peasy actions bound to it allowing you to dispatch additional actions.

  • payload (Any, not required)

    The payload, if any, that was provided to the action.

  • getState (Function, required)

    When executed it will provide the root state of your model. This can be useful in the cases where you require state in the execution of your effectful action.

  • injections (Any, not required, default=undefined)

    Any dependencies that were provided to the createStore configuration will be exposed as this argument. See the createStore docs on how to specify them.

  • meta (Object, required)

    This object contains meta information related to the effect. Specifically it contains the following properties:

    • parent (Array, string, required)

      An array representing the path of the parent to the action.

    • path (Array, string, required)

      An array representing the path to the action.

    This can be represented via the following example:

    const store = createStore({
      products: {
        fetchById: effect((dispatch, payload, getState, injections, meta) => {
          console.log(meta);
          // {
          //   parent: ['products'],
          //   path: ['products', 'fetchById']
          // }
        })
      }
    });
    
    await store.dispatch.products.fetchById()

When your model is processed by Easy Peasy to create your store all of your actions will be made available against the store's dispatch. They are mapped to the same path as they were defined in your model. You can then simply call the action functions providing any required payload. See the example below.

• attach (Function, required)

  The attach callback function allows you to attach the listeners to specific actions. It is provided the following arguments:

  • actions (Object, required)

    The actions (and effects) of the store.

  • on (Function, required)

    Allows you to attach a listener to an action. It expects the following arguments:

    • action (Function, required)

      The target action you wish to listen to - you provide the direct reference to the action.

    • handler (Function, required)

      The handler function to be executed after the target action is fired successfully. It will receive the following arguments:

      • dispatch (required)

        The Redux store dispatch instance. This will have all the Easy Peasy actions bound to it allowing you to dispatch additional actions.

      • payload (Any, not required)

        The original payload that the targetted action received.

      • getState (Function, required)

        When executed it will provide the root state of your model.

      • injections (Any, not required, default=undefined)

        Any dependencies that were provided to the createStore configuration will be exposed as this argument. See the createStore docs on how to specify them.

• mapAction (Function, required)

  The function that is used to resolved the action that your component requires. The function will receive the following arguments:

  • dispatch (Object, required)

    The dispatch of your store, which has all the actions mapped against it.

Your mapAction can either resolve a single action. If you wish to resolve multiple actions then you can either call useAction multiple times, or if you like resolve an object within your mapAction where each property of the object is a resolved action. The examples below will illustrate these options.