state-decorator 6.8.0-beta.1 → 6.8.0

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
 
@@ -315,15 +316,34 @@ 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.
 const isOneLoading = isLoading('action1', 'action2', ['parallelAction', 'promiseId']);
 ```
 
+## Error state
+
+The last error of each asynchronous actions is available on the 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
+}
+
+```
+
 ## Success / error notifications
 
 A notification function can be called when the asynchronous action succeeded or failed.
@@ -491,235 +511,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.
-
-### 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);
-
-//----------------------
-
-// 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>;
-});
-```
+## State sharing and slices
 
-### Local 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
-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']);
+// Components deeper in the component tree will be refreshed if, and only if,
+// slice is changed (here: text property)
 
-  // same as
-  // const store = useContext(StoreContext)
-  // const { title } = useStoreSlice(store, ['title']);
-
-  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 +950,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 +999,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 +1291,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                        |