state-decorator 6.8.0-beta.1 → 6.10.0-beta.1

package/README.md

@@ -9,13 +9,14 @@ The StateDecorator is a set of Reacts hook that manages a complex component stat
 # Features
 
 - Deterministic state changes (clear separation of effects and side effects)
-- Ease asynchronous actions state changes (loading states, success & error handlers, parallel actions management, optimistic updates...)
+- Ease asynchronous actions state changes (loading / error states, success & error handlers, parallel actions management, optimistic updates...)
 - Easily and efficiently share slices of state.
-- Easily testable (test framework provided)
+- Easily testable (uses pure functions, utility functions provided)
 - Easily update state from or react to props changes
-- Ease debugging (trace state changes, dev tools)
+- Ease debugging (trace state changes)
 - Improve code conciseness (no boiler plate code)
-- Strongly typed (Typescript)
+- Enforce separation of container components and presentation components.
+- Strongly typed
 
 # 🏎️ V6: The Store
 
@@ -138,12 +139,12 @@ export function App(props: Props) => {
 
 # React hooks
 
-| Hook             | Purpose                                             | Return         | Component refreshed on store change | Store is destroyed on unmount |
-| ---------------- | --------------------------------------------------- | -------------- | ----------------------------------- | ----------------------------- |
-| useLocalStore    | Create a store, binds it to the react component.    | State, actions | Y                                   | Y                             |
-| useGetLocalStore | Create a store, binds it to the react component.    | Store          | N                                   | Y                             |
-| useStore         | Binds a store instance to the react component.      | State, actions | Y                                   | N                             |
-| useStoreSlice    | Binds a store slice to a react component (sharing). | Slice          | If slice has changed only           | N                             |
+| Hook          | Purpose                                                | Component refreshed on store change | Store is destroyed on unmount |
+| ------------- | ------------------------------------------------------ | ----------------------------------- | ----------------------------- |
+| useLocalStore | Create a store and binds it to the react component     | Y                                   | Y                             |
+| useStore      | Binds an existing store to a react component (sharing) | Y                                   | Y                             |
+| useBindStore  | Bind an existing store to a react component (sharing)  | N                                   | Y                             |
+| useStoreSlice | Binds a store slice to a react component (sharing)     | If slice has changed only           | N                             |
 
 # Initial state
 
@@ -236,12 +237,12 @@ const actions: StoreActions<State, Actions> = {
 
 ## Recipes
 
-- If the effects function returns **null**, the side effects, if any, are not executed when the action is called.
+- If the effects function returns `null`, the side effects, if any, are not executed when the action is called.
 - If not effects function is defined by side effects function is provided, the side effects will be executed when the action is called.
 
 ## Cancel action
 
-To cancel effects/side effects just return **null** instead of new state in **effects**.
+To cancel effects/side effects just return `null` instead of new state in **effects**.
 
 # Asynchronous actions
 
@@ -280,16 +281,36 @@ const actions: StoreActions<State, Actions> = {
 };
 ```
 
-- If **null** is returned by **getPromise**, the action is not executed. It allows to cancel an action depending on state or props etc.
+- If `null` is returned by **getPromise**, the action is not executed. It allows to cancel an action depending on state or props etc.
 
 - **getGetPromise** is a shortcut that sets the conflict policy to **ConflictPolicy.REUSE** and **retryCount** to 3.
 
-- To cancel any effects just return **null** instead of new state in **xxxEffects**.
+- To cancel any effects just return `null` instead of new state in **xxxEffects**.
 
 ## Asynchronous action lifecycle
 
 <!-- ![Lifecycle](https://raw.githubusercontent.com/GlobalSport/state-decorator/develop/doc/StateDecoratorDiagram.png) -->
 
+```mermaid
+graph TD
+    A(Call action) --> preEffects
+    preEffects --> optimisticEffects
+    optimisticEffects --> getPromise
+    getPromise --> promiseSuccess{Success?}
+    promiseSuccess -->|Yes| effects[effects]
+    effects --> notifySuccess[notifySuccess]
+    notifySuccess --> sideEffects[sideEffects]
+    sideEffects --> promiseResolved[Promise is resolved]
+    promiseResolved --> Z(End)
+    promiseSuccess -->|No| errorEffects[errorEffects]
+    errorEffects --> notifyError[notifyError]
+    notifyError --> errSideEffetcs[errorSideEffects]
+    errSideEffetcs --> errorManaged{Error managed?}
+    errorManaged --> |Yes| promiseResolved
+    errorManaged --> |No| promiseRejected
+    promiseRejected --> Z
+```
+
 - check if a previous call to this action is ongoing,
   - if yes, check if the conflict policy is parallel,
     - if yes, let the flow continue.
@@ -307,6 +328,7 @@ const actions: StoreActions<State, Actions> = {
     - **errorEffects**: change state from promise arguments and returned error.
     - if **notifyError** is set, call it with **getErrorMessage()**.
     - **errorSideEffects**: trigger a side effect with no change on state.
+    - Global **asyncErrorHandler** is called (with a flag indicating that the error was managed or not, see [Error management](#ErrorManagement) for more details).
 
 - If a conflicting action is stored, process it.
 
@@ -315,9 +337,10 @@ const actions: StoreActions<State, Actions> = {
 The loading state of asynchronous actions is automatically computed.
 
 ```typescript
-const { isLoading, loading } = useLocalStore(getInitialState, actionsImpl);
+const { isLoading, loading, loadingMap } = useLocalStore(getInitialState, actionsImpl);
 
 // loading is set to true is at least one asynchronous action is ongoing.
+// loadingMap is action name to boolean or undefined map
 
 // isLoading is a function that accepts 1+ arguments
 // It returns true, if at least one of the specified actions is loading.
@@ -335,9 +358,38 @@ A notification function can be called when the asynchronous action succeeded or
    1. _getErrorMessage_ (message built from the error and action context).
    2. _getSuccessMessage_ (message built from the action context)
 
+```typescript
+// global notification functions
+setGlobalConfig({
+  notifySuccess: (msg) => console.log(msg),
+  notifyError: (msg) => console.log(msg),
+});
+
+// local notification functions
+const store = useLocalStore(getInitialState, actionsImpl, props, {
+  notifySuccess: (msg) => console.log(msg),
+  notifyError: (msg) => console.log(msg),
+});
+```
+
+```typescript
+// action implementation
+const actions: StoreActions<State, Actions> = {
+  loadList: {
+    getPromise: () => new Promise((_, reject) => setTimeout(reject, 500, new Error('Too bad'))),
+    getSuccessMessage: () => 'success!',
+    getErrorMessage: ({ err }) => `Error: ${err.message}`,
+  },
+};
+```
+
 ## <a name="ErrorManagement"></a>Error management
 
-When an asynchronous action fails, if the state needs to be updated, set the _errorEffects_ property of the asynchronous action.
+### Effects and side effects
+
+When an asynchronous action fails, if the state needs to be updated, set the **errorEffects** property of the asynchronous action.
+
+If some actions need to be triggered, set **errorSideEffects**.
 
 ```typescript
 const actions: StoreActions<State, Actions> = {
@@ -352,7 +404,40 @@ const actions: StoreActions<State, Actions> = {
 };
 ```
 
-**Note:** If an error message or an error reducer is defined, the error will be trapped to prevent other error management (console traces...). If, for any reason, you need to have the promise to be rejected, set **rejectPromiseOnError** to _true_.
+### Promise result
+
+If **getPromise** is failing and the error is _managed_, the action promise will be returned as **resolved** to prevent other error managements (console traces…) to be executed, otherwise it will be returned as **rejected**.
+
+An error is _managed_ if:
+
+- **errorEffects** is defined and is not returning `null`.
+- or **errorSideEffects** is defined,
+- or **notifyError** is defined and **getErrorMessage** is not returning `null`,
+- or **isErrorManaged** is set to `true`.
+
+If the error is managed but you need to have the promise to be rejected, set **rejectPromiseOnError** to `true`.
+
+Global **asyncErrorHandler** is called for each error with this _managed_ flag for global error management (logging).
+
+### Error state
+
+In order to display UI after an error, the last error of each asynchronous action is available on **errorMap**.
+
+```typescript
+const { errorMap } = useLocalStore(getInitialState, actionsImpl);
+
+
+if (errorMap.action1)) {
+  // show retry action
+}
+
+if (errorMap.action1 instanceof MyCustomError){
+  // show retry action with custom error handling
+}
+
+```
+
+Recipe: When only using the **errorMap** to manage errors (ie. there's no effects nor message and so on), the error is considered _not managed_ resulting in a rejected promise and global **asyncErrorHandler** called with _managed_ flag set to false. In that case, set **isErrorManaged** to `true` to specify that the error is _managed_ externally.
 
 ## <a name="ConflictingActions"></a>Conflicting actions
 
@@ -491,235 +576,64 @@ When a hook that creates / binds a store is mounted, the **onMount** option is c
 ```typescript
 import { createStore } from 'state-decorator';
 
-// global store
 const store = createStore(getInitialState, actionsImpl, {
   onMount: ({ a }) => {
     a.loadList;
   },
 });
 
-store.init(initialProps);
-```
-
-```typescript
-import { createStore } from 'state-decorator';
-
-// local store
+// onMount is called when this component is mounted
 function Container(p: ContainerProps) {
-  const store = useGetLocalStore(getInitialState, actionsImpl, p, {
-    onMount: ({ a }) => {
-      a.loadList;
-    },
-  });
+  useBindStore(store, p);
 }
 ```
 
 If an initial action is launched each time a property changes, consider using the **onMount** flag of the **onPropsChange** entry.
 
-# Global and Local Stores VS State sharing
-
-There are two ways to share state and actions:
-
-- Using regular props.
-- Using state slices.
-
-There are two types of stores:
-
-- Global store:
-
-  - store is created as an instance and it is exported from the JS module.
-  - it can be imported in any other JS module.
-  - store lifespan is equal to the application one.
-
-- Local store:
-  - store is created by a hook and is bound to a React component (each instance of this component owns its own store).
-  - action and props can be shared using props or sharing the store itself (see example below)
-  - store is destroyed when its React component is unmounted.
-
-## Using props
-
-- Bind a React component to make store state / actions available on React component.
-- Any change in the store (state, loading actions, ...) will trigger a refresh of the bound React component.
-- Pass state / actions using regular React props.
-- Use React.memo to prevent unecessary React re-renders if needed.
+## State sharing and slices
 
-### Global store
+- Declare a store and bind it to a component using _useStore_ or _useBindStore_ hooks.
+- Deeper in the tree component, use _useStoreSlice_ to get a store slice.
+- Component using slices will be refreshed only if their store slice changes.
 
 ```typescript
-// Declare typings & actions as above
-
-// Create a store in a dedicated file, named GlobalStore.ts for example
-export const store = createStore(getInitialState, userAppActions);
-
-//----------------------
-
-// In another file
-import React, { memo } from 'react';
-import { useStore } from 'state-decorator';
-import store from './GlobalStore';
-
-// Bind to react component
-// Each time the store state changes, a re-render is done.
-export function Container(props: Props) {
-  const { state, actions } = useStore(store, props);
-  return (
-    <div>
-      <Title text={state.title} />
-      <Subtitle text={state.subtitle} />
-    </div>
-  );
-}
-
-// Simple presentation components
-// Use memo to prevent re-render if another part of the state has changed than "title"
-const Title = memo(function Title(props: { title: string }) {
-  return <div>{props.text}</div>;
-});
-
-const Subtitle = memo(function Subtitle(props: { subtitle: string }) {
-  return <div>{props.subtitle}</div>;
-});
-```
-
-### Local Store
-
-```typescript
-import React, { memo } from 'react';
-import { useLocalStore } from 'state-decorator';
-
-// Declare typings & actions as above
-
-// Create and bind to react component
-// Each time the store state changes, a re-render is done.
-export function Container(props: Props) {
-  const { state, actions } = useLocalStore(getInitialState, userAppActions, props);
-  return (
-    <div>
-      <Title text={state.title} />
-      <Subtitle text={state.subtitle} />
-    </div>
-  );
-}
-
-// Simple presentation components
-// Use memo to prevent re-render if another part of the state has changed than "title"
-const Title = memo(function Title(props: { title: string }) {
-  return <div>{props.title}</div>;
-});
-
-const Subtitle = memo(function Subtitle(props: { subtitle: string }) {
-  return <div>{props.subtitle}</div>;
-});
-```
-
-## State slices
-
-Using React props implies useless re-renders and optionally memoization.
-
-To prevent this, React provides [context](https://en.reactjs.org/docs/context.html) hooks.
-
-The problem is that if the context contains a complex state with lots of props, if **any** of these props is changing, **all** components that uses this context will be re-rendered.
-
-To overcome this problem, the StateDecorator provides a _useStoreSlice_ and _useStoreContextSlice_ hook that allow to define and extracts a slice of the state and trigger a re-render of the React component only if slice has changed.
-
-[![Edit Slice](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/slices-v6-eg471?file=/src/SliceView.tsx)
-
-## Global Store
-
-```typescript
-// Declare typings & actions as above
-
-// Create a store in a dedicated file, named GlobalStore.ts for example
-export const store = createStore(getInitialState, userAppActions);
-
-//----------------------
-
-import React, { memo } from 'react';
-import { useStoreSlice } from 'state-decorator';
-import store from './GlobalStore';
-
-export function Container(props: Props) {
-  return (
-    <div>
-      <Title />
-      <Subtitle />
-    </div>
-  );
-}
-
-function Title() {
-  // extracts the "title" slice
-  // component is refresh only if title is changed in the store
-  const { title } = useStoreSlice(store, ['title']);
-  return <div>{title}</div>;
-}
-
-function Subtitle(props: { subtitle: string }) {
-  const { subtitle } = useStoreSlice(store, ['subtitle']);
-  return <div>{subtitle}</div>;
-}
-```
-
-## Local Store
-
-```typescript
-// ------- stores/MyStore.ts --------
-
 import React from 'react';
-import { useGetLocalStore, useStoreContextSlice } from 'state-decorator';
+import { useStore, useStoreSlice, StoreActions } from 'state-decorator';
 
 // Declare typings & actions as above
 
-// Create a store context
-
-type StoreContextProps = StoreApi<State, Actions, Props>;
+// Create a store
 
-export const StoreContext = createContext<StoreContextProps>(null);
+export const store = createStore(getInitialState, userAppActions);
 
-// The StoreContext will allow to access to the store
-// But this context is NOT refreshed if the store state is changed
-export function StoreContextProvider(p: { children: any; propIn: string }) {
-  const { children, ...props } = p;
-  const store = useGetLocalStore(getInitialState, actionsImpl, props);
-  return <StoreContext.Provider value={store}>{children}</StoreContext.Provider>;
-}
+// Bind to react component
 
-// In a container file ------------------------
+export function Container(prop: Props) {
+  const { state, actions } = useStore(store, props);
 
-import { StoreContextProvider } from 'stores/MyStore';
+  // or
+  // useBindStore(store, props);
+  // if you are not interested in getting the state here
 
-// If Container is destroyed store is destroyed
-export function Container(props: Props) {
-  return (
-    <StoreContextProvider {...props}>
-      <SubComponent />
-      <SubComponent2 />
-    </StoreContextProvider>
-  );
+  return <div />;
 }
 
-// Component deeper in the component tree...
-
-import { StoreContext } from 'stores/MyStore';
-
-function Title() {
-  // extracts the "title" slice
-  // component is refresh only if title is changed in the store
-  const { title } = useStoreContextSlice(StoreContext, ['title']);
-
-  // same as
-  // const store = useContext(StoreContext)
-  // const { title } = useStoreSlice(store, ['title']);
+// Components deeper in the component tree will be refreshed if, and only if,
+// slice is changed (here: text property)
 
-  return <div>{title}</div>;
+export function SubComponent2() {
+  const s = useStoreSlice(store, ['text']);
+  return <div>{s.text}</div>;
 }
 
-function Subtitle(props: { subtitle: string }) {
-  const { subtitle } = useStoreContextSlice(StoreContext, ['subtitle']);
-  return <div>{subtitle}</div>;
+export function SubComponent() {
+  const s = useStoreSlice(store, (s) => ({ text: s.text }));
+  return <div>{s.text}</div>;
 }
 ```
 
+[![Edit Slice](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/slices-v6-eg471?file=/src/SliceView.tsx)
+
 # Global configuration
 
 Overrides configuration to set properties that will be used by all stores.
@@ -1101,172 +1015,6 @@ describe('Todo', () => {
     });
   });
 
-  it('onSetNewTitle', async () => {
-    // always return a promise whatever if the action is asynchronous or not
-    const { state, prevState } = await store.getAction('onSetNewTitle').call('new Title');
-
-    // previous state is available for comparison
-    expect(prevState.newTitle).toEqual('');
-    expect(state.newTitle).toEqual('new Title');
-  });
-
-  it('onCreate', async () => {
-    const {
-      state: { todoIds, todoMap, todos },
-    } = await store
-      // set partial state and return new store, source store is untouched
-      .setPartialState({
-        newTitle: 'new todo',
-      })
-      // get a mock action that can be shared too !
-      .getAction('onCreate')
-      // Invokes action. It has no side effect on state of mock action
-      .call();
-
-    // assert state
-    expect(todoIds).toEqual(['id', 'id2', 'id3']);
-    expect(todoMap).toEqual({
-      id: {
-        id: 'id',
-        completed: true,
-        title: 'todo',
-      },
-      id2: {
-        id: 'id2',
-        completed: false,
-        title: 'todo 2',
-      },
-      id3: {
-        id: 'id3',
-        completed: false,
-        title: 'new todo',
-      },
-    });
-
-    // assert derived state
-    //
-    // export const todoOptions: StoreOptions<State, Actions, Props, DerivedState> = {
-    //     derivedState: {
-    //       todos: {
-    //         getDeps: ({ s }) => [s.todoIds, s.todoMap],
-    //         get: ({ s }) => s.todoIds.map((id) => s.todoMap[id]),
-    //       },
-    //     },
-    //   };
-
-    expect(todos).toEqual([
-      {
-        id: 'id',
-        completed: true,
-        title: 'todo',
-      },
-      {
-        id: 'id2',
-        completed: false,
-        title: 'todo 2',
-      },
-      {
-        id: 'id3',
-        completed: false,
-        title: 'new todo',
-      },
-    ]);
-  });
-
-  describe('onToggle', () => {
-    // this mock action is shared in two tests but they can run in parallel
-    const onToggle = store.getAction('onToggle');
-
-    it('toggle false => true', async () => {
-      // arguments of call() depend on the Store action signature, use auto completion!
-      const {
-        state: { todoIds, todoMap },
-        actions,
-      } = await onToggle.call('id2');
-
-      expect(todoIds).toEqual(['id', 'id2']);
-      expect(todoMap).toEqual({
-        id: {
-          id: 'id',
-          completed: true,
-          title: 'todo',
-        },
-        id2: {
-          id: 'id2',
-          completed: true,
-          title: 'todo 2',
-        },
-      });
-
-      // if there are some side effects calling store actions, you can test them
-      // as mock actions are injected instead of real actions.
-      expect(actions.updateRemoteList).toHaveBeenCalled();
-    });
-
-    it('toggle true => false', async () => {
-      const {
-        state: { todoIds, todoMap },
-        actions,
-      } = await onToggle.call('id');
-
-      expect(todoIds).toEqual(['id', 'id2']);
-      expect(todoMap).toEqual({
-        id: {
-          id: 'id',
-          completed: false,
-          title: 'todo',
-        },
-        id2: {
-          id: 'id2',
-          completed: false,
-          title: 'todo 2',
-        },
-      });
-
-      // if there are some side effects calling store actions, you can test them
-      // as mock actions are injected instead of real actions.
-      expect(actions.updateRemoteList).toHaveBeenCalled();
-    });
-  });
-
-  // Another store / action
-  describe('loadRemoteList', () => {
-    // action is shared
-    const action = store.getAction('loadRemoteList');
-
-    it('success', async () => {
-      const { state } = await action
-        // override default promise result
-        .promiseResolves([
-          {
-            id: 'item1',
-            title: 'item title',
-            completed: true,
-          },
-        ])
-        .call();
-
-      expect(state.error).toBeFalsy();
-      expect(state.todoIds).toEqual(['item1']);
-      expect(state.todoMap).toEqual({
-        item1: {
-          id: 'item1',
-          title: 'item title',
-          completed: true,
-        },
-      });
-    });
-
-    it('error', async () => {
-      const { state } = await action
-        // override default promise result with error
-        .promiseRejects(new Error('boom'))
-        .call();
-
-      expect(state.error).toBeTruthy();
-    });
-  });
-
   // Test effects and side effect when props are changing
   //
   // Here:
@@ -1316,6 +1064,174 @@ describe('Todo', () => {
         expect(actions.loadRemoteList).not.toHaveBeenCalled();
       });
   });
+
+  describe('actions', () => {
+    it('onSetNewTitle', async () => {
+      // always return a promise whatever if the action is asynchronous or not
+      const { state, prevState } = await store.getAction('onSetNewTitle').call('new Title');
+
+      // previous state is available for comparison
+      expect(prevState.newTitle).toEqual('');
+      expect(state.newTitle).toEqual('new Title');
+    });
+
+    it('onCreate', async () => {
+      const {
+        state: { todoIds, todoMap, todos },
+      } = await store
+        // set partial state and return new store, source store is untouched
+        .setPartialState({
+          newTitle: 'new todo',
+        })
+        // get a mock action that can be shared too !
+        .getAction('onCreate')
+        // Invokes action. It has no side effect on state of mock action
+        .call();
+
+      // assert state
+      expect(todoIds).toEqual(['id', 'id2', 'id3']);
+      expect(todoMap).toEqual({
+        id: {
+          id: 'id',
+          completed: true,
+          title: 'todo',
+        },
+        id2: {
+          id: 'id2',
+          completed: false,
+          title: 'todo 2',
+        },
+        id3: {
+          id: 'id3',
+          completed: false,
+          title: 'new todo',
+        },
+      });
+
+      // assert derived state
+      //
+      // export const todoOptions: StoreOptions<State, Actions, Props, DerivedState> = {
+      //     derivedState: {
+      //       todos: {
+      //         getDeps: ({ s }) => [s.todoIds, s.todoMap],
+      //         get: ({ s }) => s.todoIds.map((id) => s.todoMap[id]),
+      //       },
+      //     },
+      //   };
+
+      expect(todos).toEqual([
+        {
+          id: 'id',
+          completed: true,
+          title: 'todo',
+        },
+        {
+          id: 'id2',
+          completed: false,
+          title: 'todo 2',
+        },
+        {
+          id: 'id3',
+          completed: false,
+          title: 'new todo',
+        },
+      ]);
+    });
+
+    describe('onToggle', () => {
+      // this mock action is shared in two tests but they can run in parallel
+      const onToggle = store.getAction('onToggle');
+
+      it('toggle false => true', async () => {
+        // arguments of call() depend on the Store action signature, use auto completion!
+        const {
+          state: { todoIds, todoMap },
+          actions,
+        } = await onToggle.call('id2');
+
+        expect(todoIds).toEqual(['id', 'id2']);
+        expect(todoMap).toEqual({
+          id: {
+            id: 'id',
+            completed: true,
+            title: 'todo',
+          },
+          id2: {
+            id: 'id2',
+            completed: true,
+            title: 'todo 2',
+          },
+        });
+
+        // if there are some side effects calling store actions, you can test them
+        // as mock actions are injected instead of real actions.
+        expect(actions.updateRemoteList).toHaveBeenCalled();
+      });
+
+      it('toggle true => false', async () => {
+        const {
+          state: { todoIds, todoMap },
+          actions,
+        } = await onToggle.call('id');
+
+        expect(todoIds).toEqual(['id', 'id2']);
+        expect(todoMap).toEqual({
+          id: {
+            id: 'id',
+            completed: false,
+            title: 'todo',
+          },
+          id2: {
+            id: 'id2',
+            completed: false,
+            title: 'todo 2',
+          },
+        });
+
+        // if there are some side effects calling store actions, you can test them
+        // as mock actions are injected instead of real actions.
+        expect(actions.updateRemoteList).toHaveBeenCalled();
+      });
+    });
+
+    // Another store / action
+    describe('loadRemoteList', () => {
+      // action is shared
+      const action = store.getAction('loadRemoteList');
+
+      it('success', async () => {
+        const { state } = await action
+          // override default promise result
+          .promiseResolves([
+            {
+              id: 'item1',
+              title: 'item title',
+              completed: true,
+            },
+          ])
+          .call();
+
+        expect(state.error).toBeFalsy();
+        expect(state.todoIds).toEqual(['item1']);
+        expect(state.todoMap).toEqual({
+          item1: {
+            id: 'item1',
+            title: 'item title',
+            completed: true,
+          },
+        });
+      });
+
+      it('error', async () => {
+        const { state } = await action
+          // override default promise result with error
+          .promiseRejects(new Error('boom'))
+          .call();
+
+        expect(state.error).toBeTruthy();
+      });
+    });
+  });
 });
 ```
 
@@ -1440,9 +1356,9 @@ TypeError: Cannot set property 'crash' of null
 ### MockStore
 
 | Function        | Arguments                            | Returns             | Description                                                                                 |
-| --------------- | ------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------- | --- |
+| --------------- | ------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------- |
 | getAction       | actionName: keyof A                  | MockStoreAction     | Get a mock action instance                                                                  |
-| onInit          | props?: Partial<P>                   | MockResult          | Test store initialization (onPropsChanged marked onMount + onMount)                         |     |
+| onInit          | props?: Partial<P>                   | MockResult          | Test store initialization (onPropsChanged marked onMount + onMount)                         |
 | onPropsChange   | props: P, init?: boolean             | MockResult          | Test prop changes. Does not change internal props. Init allows to test onMount prop changes |
 | setPartialProps | props: Partial<P>                    | new mock store      | Create a new store with the merge of current props and partial props                        |
 | setPartialState | state: Partial<S>                    | new mock store      | Create a new store with the merge of current state and partial state                        |
@@ -1473,7 +1389,7 @@ TypeError: Cannot set property 'crash' of null
 
 # Immutability
 
-- Immutability: each effects **must** return a new state instance (or **null** if there's no change).
+- Immutability: each effects **must** return a new state instance (or `null` if there's no change).
 - I recommend using [Immer](https://github.com/immerjs/immer) to manage complex cases (deep nesting). A **immerizeActions** action decorator is provided to decorate each effect with Immer.
 
 # Limitations