state-decorator 6.6.1 → 6.8.0-beta.1

package/README.md

@@ -11,12 +11,11 @@ The StateDecorator is a set of Reacts hook that manages a complex component stat
 - 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...)
 - Easily and efficiently share slices of state.
-- Easily testable (uses pure functions, utility functions provided)
+- Easily testable (test framework provided)
 - Easily update state from or react to props changes
-- Ease debugging (trace state changes)
+- Ease debugging (trace state changes, dev tools)
 - Improve code conciseness (no boiler plate code)
-- Enforce separation of container components and presentation components.
-- Strongly typed
+- Strongly typed (Typescript)
 
 # 🏎️ V6: The Store
 
@@ -76,19 +75,19 @@ type Props = {
 // Initial state & actions
 
 export const getInitialState = (): State => ({
-  selectedUser: null,
+  selectedUserId: null,
   user: null,
 });
 
 export const userAppActions: StoreActions<State, Actions, Props> = {
   // synchronous action (simple form)
-  selectUser: ({ state, args: [id] }) => ({ ...state, selectedUser: id }),
+  selectUser: ({ state, args: [id] }) => ({ ...state, selectedUserId: id }),
 
   // a synchronous action with side effects
   selectAndLoadUser: {
     // same as simple form, using aliases (use short context alias 's' instead of 'state')
     // effects contain only immutable state changes
-    effects: ({ s, args: [id] }) => ({ ...s, selectedUser: id }),
+    effects: ({ s, args: [id] }) => ({ ...s, selectedUserId: id }),
     // side effects (ie. other effects than state changes), using "actions" alias
     sideEffects: ({ a }) => {
       a.loadUser();
@@ -139,12 +138,12 @@ export function App(props: Props) => {
 
 # React hooks
 
-| 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                             |
+| 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                             |
 
 # Initial state
 
@@ -492,63 +491,234 @@ 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;
   },
 });
 
-// onMount is called when this component is mounted
+store.init(initialProps);
+```
+
+```typescript
+import { createStore } from 'state-decorator';
+
+// local store
 function Container(p: ContainerProps) {
-  useBindStore(store, p);
+  const store = useGetLocalStore(getInitialState, actionsImpl, p, {
+    onMount: ({ a }) => {
+      a.loadList;
+    },
+  });
 }
 ```
 
 If an initial action is launched each time a property changes, consider using the **onMount** flag of the **onPropsChange** entry.
 
-## State sharing and slices
+# Global and Local Stores VS State sharing
 
-- 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.
+There are two ways to share state and actions:
 
-```typescript
-import React from 'react';
-import { useStore, useStoreSlice, StoreActions } from 'state-decorator';
+- Using regular props.
+- Using state slices.
 
-// Declare typings & actions as above
+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.
 
-// Create a store
+- 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.
+
+### 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);
 
-// Bind to react component
+//----------------------
+
+// In another file
+import React, { memo } from 'react';
+import { useStore } from 'state-decorator';
+import store from './GlobalStore';
 
-export function Container(prop: Props) {
+// 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>
+  );
+}
 
-  // or
-  // useBindStore(store, props);
-  // if you are not interested in getting the state here
+// 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>;
+});
 
-  return <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>
+  );
 }
 
-// Components deeper in the component tree will be refreshed if, and only if,
-// slice is changed (here: text property)
+// 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
 
-export function SubComponent2() {
-  const s = useStoreSlice(store, ['text']);
-  return <div>{s.text}</div>;
+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>
+  );
 }
 
-export function SubComponent() {
-  const s = useStoreSlice(store, (s) => ({ text: s.text }));
-  return <div>{s.text}</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>;
 }
 ```
 
-[![Edit Slice](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/slices-v6-eg471?file=/src/SliceView.tsx)
+## Local Store
+
+```typescript
+// ------- stores/MyStore.ts --------
+
+import React from 'react';
+import { useGetLocalStore, useStoreContextSlice } from 'state-decorator';
+
+// Declare typings & actions as above
+
+// Create a store context
+
+type StoreContextProps = StoreApi<State, Actions, Props>;
+
+export const StoreContext = createContext<StoreContextProps>(null);
+
+// 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>;
+}
+
+// In a container file ------------------------
+
+import { StoreContextProvider } from 'stores/MyStore';
+
+// If Container is destroyed store is destroyed
+export function Container(props: Props) {
+  return (
+    <StoreContextProvider {...props}>
+      <SubComponent />
+      <SubComponent2 />
+    </StoreContextProvider>
+  );
+}
+
+// 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']);
+
+  return <div>{title}</div>;
+}
+
+function Subtitle(props: { subtitle: string }) {
+  const { subtitle } = useStoreContextSlice(StoreContext, ['subtitle']);
+  return <div>{subtitle}</div>;
+}
+```
 
 # Global configuration
 
@@ -571,7 +741,7 @@ setGlobalConfig({
   notifyError: undefined,
   // Notification function injected in side effects action context (success and error) to notify warning
   notifyWarning: undefined,
-  // Function called to return common error message if error message is not provided or error not managed in action
+  // Function called to return common error message if error message is not provided or error not managed in action. To override locally in action, provide a function that returns _null_.
   getErrorMessage: undefined,
 });
 ```
@@ -812,42 +982,138 @@ function Container(props: Props) {
 # Unit testing
 
 - The state decorator provides a testing framework for stores.
-- The base principle is that a mock store is immutable. A new store is created is setting state/props. It allows to share mock store across tests.
-- On each test, reuse/setup store or store action and:
-  - call the action and test state, side effect calls,...
-  - calls have no effects on mock store
-  - test prop changes
+- The base principle is that a mock store is immutable:
+  - a new store is created each time state or props are set.
+  - it allows to share mock store across tests.
+- The API is chainable: functions are returning a mock store, excepting test functions.
+- On a mock store, we can test the store internals after initialiation, after inbound props have changed, after actions are called.
 
 ## Getting started
 
+1. Create and setup a mock store (_createMockFromStore_)
+2. Test store after initialization (_onInit_)
+3. Test store after props changes (_onPropsChange_)
+4. Test each action:
+   1. Get mock store action (_getAction_)
+   2. setup store state/prop (_setPartialState_, _setPartialProps_)
+   3. if action is asynchronous, you can mock promise (_promiseResolves_, _promiseRejects_)
+   4. call action with params (_call_)
+   5. await response to test state/actions called...
+
+## Example
+
+The store definition is available at [TodoStore.ts](https://github.com/GlobalSport/state-decorator/blob/develop/tests/fixtures/TodoStore.ts).
+
+The test is available at [Todo.test.ts](https://github.com/GlobalSport/state-decorator/blob/develop/tests/Todo.test.ts).
+
 ```typescript
 import { createMockFromStore } from 'state-decorator/test';
 
-import { todoStore, TodoItem } from './Todos';
+import todoStore from './fixtures/TodoStore';
 
 describe('Todo', () => {
   // create a mock store and setup initial state
-  // state / props can be set in full form or partial form
   // this store can be shared accross tests because it is immutable
-  const store = createMockFromStore(todoStore, {}).setPartialState({
-    idCount: 3,
-    todoIds: ['id', 'id2'],
-    todoMap: {
-      id: {
-        id: 'id',
-        completed: true,
-        title: 'todo',
-      },
-      id2: {
-        id: 'id2',
-        completed: false,
-        title: 'todo 2',
+  const store = createMockFromStore(todoStore)
+    // or
+    //   const store = createMockStore(getInitialState, actions, props, options)
+    // initial state / props can be set in full form or partial form
+    .setPartialState({
+      idCount: 3,
+      todoIds: ['id', 'id2'],
+      todoMap: {
+        id: {
+          id: 'id',
+          completed: true,
+          title: 'todo',
+        },
+        id2: {
+          id: 'id2',
+          completed: false,
+          title: 'todo 2',
+        },
       },
-    },
+    });
+
+  describe('Initialization', () => {
+    it('if not initial todo => load list', () => {
+      store
+        .setPartialState({
+          todoIds: [],
+          todoMap: {},
+        })
+        .onInit({ initialTodos: null })
+        .test(({ state, actions }) => {
+          // test state after initialization, ie:
+          // - options.onPropsChange with onMount: true
+          // - options.onMount
+          expect(state.todoIds).toEqual([]);
+          expect(state.todoMap).toEqual({});
+
+          // test derived state
+          expect(state.todos).toEqual([]);
+
+          // test side effects also
+          expect(actions.loadRemoteList).toHaveBeenCalled();
+        });
+    });
+
+    it('initial todos => setup state and do not load list', () => {
+      store
+        .setPartialState({
+          todoIds: [],
+          todoMap: {},
+        })
+        .onInit({
+          initialTodos: [
+            {
+              id: 'item1',
+              title: 'Item 1',
+              completed: false,
+            },
+          ],
+        })
+        .test(({ state, actions }) => {
+          // test state after initialization, ie:
+          // - options.onPropsChange with onMount: true
+          // - options.onMount
+          expect(state.todoIds).toEqual(['item1']);
+          expect(state.todoMap).toEqual({
+            item1: {
+              id: 'item1',
+              title: 'Item 1',
+              completed: false,
+            },
+          });
+
+          // test derived state
+          expect(state.todos).toEqual([
+            {
+              id: 'item1',
+              title: 'Item 1',
+              completed: false,
+            },
+          ]);
+
+          // test side effects also
+          expect(actions.loadRemoteList).not.toHaveBeenCalled();
+        });
+    });
+  });
+
+  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 () => {
-    await store
+    const {
+      state: { todoIds, todoMap, todos },
+    } = await store
       // set partial state and return new store, source store is untouched
       .setPartialState({
         newTitle: 'new todo',
@@ -855,37 +1121,69 @@ describe('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()
-      // always return a promise whatever if the action is asynchronous or not
-      .then(({ state: { todoIds, todoMap } }) => {
-        // 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',
-          },
-        });
-      });
+      .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',
+      },
+    ]);
   });
 
-  it('onToggle', async () => {
-    // this mock action is shared
+  describe('onToggle', () => {
+    // this mock action is shared in two tests but they can run in parallel
     const onToggle = store.getAction('onToggle');
 
-    // arguments of call() depend on the Store action signature, use auto completion!
-    await onToggle.call('id2').then(({ state: { todoIds, todoMap } }) => {
+    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: {
@@ -899,9 +1197,18 @@ describe('Todo', () => {
           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();
     });
 
-    await onToggle.call('id').then(({ state: { todoIds, todoMap } }) => {
+    it('toggle true => false', async () => {
+      const {
+        state: { todoIds, todoMap },
+        actions,
+      } = await onToggle.call('id');
+
       expect(todoIds).toEqual(['id', 'id2']);
       expect(todoMap).toEqual({
         id: {
@@ -915,53 +1222,103 @@ describe('Todo', () => {
           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
-  it('getList', async () => {
-    await store
-      .getAction('getList')
-      // override default promise result
-      .promiseResolves([])
-      // simulate error
-      //.promiseRejects(new Error('boom'))
-      .call()
-      .then((res) => {
-        // if there are some side effects calling store action, you test them
-        // as mock actions are injected instead of real actions.
-        expect(res.actions.sideEffectAction).toHaveBeenCalledWith('sideEffect');
-        expect(res.state).toEqual({
-          //  state...
-        });
+  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();
+    });
   });
 
-  // Another store
+  // Test effects and side effect when props are changing
+  //
+  // Here:
+  //   export const todoOptions: StoreOptions<State, Actions, Props, DerivedState> = {
+  //     onPropsChange: [
+  //       {
+  //         getDeps: (p) => [p.initialTodos],
+  //         effects: ({ s, p }) => ({ ...s, ...splitList(p.initialTodos) }),
+  //         onMount: true,
+  //       },
+  //     ],
+  //   };
   it('onPropsChange', () => {
     store
       // onPropsChange allows to test prop change, no side effect on original store
       // to create a new store with new props, use setProps or setPartialProps
       .onPropsChange({
-        prop: 'new_prop',
+        initialTodos: [
+          {
+            id: 'item1',
+            title: 'Item 1',
+            completed: false,
+          },
+        ],
       })
-      .test((res) => {
-        // test side effects
-        expect(res.actions.sideEffectAction).toHaveBeenCalledWith('sideEffect');
-        // test store props
-        expect(res.props.prop).toEqual('new_prop');
-        //
-        expect(res.state).toEqual({
-          prop1: 'new_prop',
-          derived: '', // derived state is updated
+      .test(({ state, actions }) => {
+        // test state after prop has changed
+        expect(state.todoIds).toEqual(['item1']);
+        expect(state.todoMap).toEqual({
+          item1: {
+            id: 'item1',
+            title: 'Item 1',
+            completed: false,
+          },
         });
+
+        // test derived state after prop has changed
+        expect(state.todos).toEqual([
+          {
+            id: 'item1',
+            title: 'Item 1',
+            completed: false,
+          },
+        ]);
+
+        // test side effects also
+        expect(actions.loadRemoteList).not.toHaveBeenCalled();
       });
   });
 });
 ```
 
-[![Edit Todo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/todo-forked-ml0z6?file=/src/TodoApp.tsx)
-
 ## Error testing
 
 ### Managed error
@@ -1083,10 +1440,9 @@ TypeError: Cannot set property 'crash' of null
 ### MockStore
 
 | Function        | Arguments                            | Returns             | Description                                                                                 |
-| --------------- | ------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------- |
+| --------------- | ------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------- | --- |
 | getAction       | actionName: keyof A                  | MockStoreAction     | Get a mock action instance                                                                  |
-| init            | props?: Partial<P>                   | MockResult          | Test store initialization (onPropsChanged marked onMount + onMount)                         |
-| onMount         | props: P                             | MockResult          | Test onMount. Does not change internal props.                                               |
+| 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                        |